RutaDocs

Empezar

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:

Texto
ruta_test_ab12cd34ef56_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Guardala en una variable de entorno de tu servidor:

Terminal
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.

2. Creá una entrega

Terminal
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"
     }'
JavaScript
// 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);

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).

3. Consultala

Terminal
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…
Terminal
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.

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.

Ver en Markdown