# Inicio rápido

Vas a crear una entrega de prueba, consultarla y recibir un aviso firmado. Necesitás `curl` y una clave.

## 1. Conseguí una clave

En el panel de tu courier: **Configuración → Desarrolladores → Conexión con tu sistema (claves de API)**. Poné un nombre (por ejemplo, «Tienda online»), elegí el **Tipo de clave** **De prueba** y los permisos **Crear entregas** y **Consultar entregas**. La clave completa se muestra **una sola vez**:

```text
ruta_test_ab12cd34ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

Guardala en una variable de entorno de tu servidor:

```bash
export RUTA_API_KEY='ruta_test_ab12cd34ef56_…'
export RUTA_API='https://<tu-courier>'   # el mismo dominio del panel
```

> Una clave de prueba trabaja en un espacio aislado: sus entregas no aparecen en el panel, no las ve ningún repartidor y no consumen cupo. Ver [entorno de prueba](entorno-de-prueba.html).

## 2. Creá una entrega

<div class="tabs">

```bash
curl -X POST "$RUTA_API/api/v1/deliveries" \
  -H "Authorization: Bearer $RUTA_API_KEY" \
  -H "Idempotency-Key: pedido-1042" \
  -H "Content-Type: application/json" \
  -d '{
       "customerName": "Ana Pérez",
       "address": "Av. Italia 1234, apto 5",
       "recipientPhone": "+59899123456",
       "externalReference": "1042"
     }'
```

```js
// Node.js 18+ (fetch incluido)
const response = await fetch(`${process.env.RUTA_API}/api/v1/deliveries`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RUTA_API_KEY}`,
    'Idempotency-Key': 'pedido-1042',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "customerName": "Ana Pérez",
    "address": "Av. Italia 1234, apto 5",
    "recipientPhone": "+59899123456",
    "externalReference": "1042"
  }),
})
if (!response.ok) throw new Error(`Ruta respondió ${response.status}`)
const delivery = await response.json()
```

```python
# Python 3 con requests (pip install requests)
import os

import requests

response = requests.post(
    f"{os.environ['RUTA_API']}/api/v1/deliveries",
    headers={
        "Authorization": f"Bearer {os.environ['RUTA_API_KEY']}",
        "Idempotency-Key": "pedido-1042",
    },
    json={
        "customerName": "Ana Pérez",
        "address": "Av. Italia 1234, apto 5",
        "recipientPhone": "+59899123456",
        "externalReference": "1042",
    },
    timeout=30,
)
response.raise_for_status()
delivery = response.json()
```

```php
<?php // PHP 8 con la extensión curl
$ch = curl_init(getenv('RUTA_API') . '/api/v1/deliveries');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RUTA_API_KEY'),
        'Idempotency-Key: pedido-1042',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'customerName' => 'Ana Pérez',
        'address' => 'Av. Italia 1234, apto 5',
        'recipientPhone' => '+59899123456',
        'externalReference' => '1042',
    ], JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 30,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($status >= 400) throw new RuntimeException("Ruta respondió $status");
$delivery = json_decode($body, true);
```

</div>

Respuesta `201 Created` (resumida):

```json
{
  "id": "6f1c1d0e-2f5e-4bb5-9c1a-1c1b1f0e9a77",
  "status": "CREATED",
  "externalReference": "1042",
  "trackingUrl": "https://<tu-courier>/track/test-0b6d…",
  "attemptNumber": 1,
  "test": true
}
```

Si la respuesta se pierde, **repetí exactamente la misma llamada**: con la misma `Idempotency-Key` recibís la misma entrega, nunca una segunda ([idempotencia](idempotencia.html)).

## 3. Consultala

```bash
curl "$RUTA_API/api/v1/deliveries/6f1c1d0e-2f5e-4bb5-9c1a-1c1b1f0e9a77" \
  -H "Authorization: Bearer $RUTA_API_KEY"

# o por el número de tu pedido
curl "$RUTA_API/api/v1/deliveries?externalReference=1042" \
  -H "Authorization: Bearer $RUTA_API_KEY"
```

## 4. Recibí avisos

1. En **Avisos a tu sistema (webhooks)**, agregá la URL de tu servidor (https), elegí **De prueba** y los eventos que te interesan. Guardá el secreto `whsec_…`.
2. Tocá **Enviar evento de prueba**: tu servidor recibe un `POST` firmado con `type: "webhook.test"`.
3. Simulá el recorrido de la entrega y vas a recibir `delivery.assigned`, `delivery.out_for_delivery`, `delivery.delivered`…

```bash
for action in ASSIGN START DELIVER; do
  curl -X POST "$RUTA_API/api/v1/deliveries/6f1c1d0e-2f5e-4bb5-9c1a-1c1b1f0e9a77/simulate" \
    -H "Authorization: Bearer $RUTA_API_KEY" -H "Content-Type: application/json" \
    -d "{\"action\": \"$action\"}"
done
```

Verificá cada aviso como explica [Webhooks → Verificar la firma](webhooks.html#verificar-la-firma).

## 5. Pasá a producción

Creá una clave **Real** y un webhook **Real** (en la API y en estas guías, «producción»). Las llamadas son las mismas; ahora las entregas aparecen en el panel, las reparten los repartidores reales y cuentan para el cupo mensual del plan.