API de Rutery

Autenticación

Todas las peticiones requieren un header Authorization con formato Bearer:

Authorization: Bearer TU_API_KEY

Tu API key se genera automáticamente al crear tu cuenta de comercio. Puedes regenerarla desde tu portal en Perfil → API Key.

Endpoints

curl -X POST https://rutery.com/api/v1/quote \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"direccion_destino": "Av. Principal, Chacao"}'

{
  "ok": true,
  "direccion_destino": "Av. Principal, Chacao, Caracas",
  "lat_destino": 10.4967,
  "lng_destino": -66.8512,
  "distancia_km": 2.4,
  "costo_envio_usd": 1.42,
  "costo_envio_ves": 1272.49,
  "tasa_cambio_usada": 896.12,
  "desglose": {
    "base": 1.00,
    "subtotal_segmentos": 0.42,
    "recargos_aplicados": [],
    "monto_recargos": 0
  }
}

curl -X POST https://rutery.com/api/v1/orders/create \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_final_nombre": "María López",
    "cliente_final_telefono": "+584141234567",
    "direccion_destino": "Av. Principal, Chacao",
    "codigo_externo": "PEDIDO-1042"
  }'

{
  "ok": true,
  "orden": {
    "id": 1042,
    "codigo_externo": "PEDIDO-1042",
    "estatus": "ASIGNADA",
    "costo_envio_usd": 1.42,
    "costo_envio_ves": 1272.49,
    "tasa_cambio_usada": 896.12,
    "jornada_id": 15,
    "created_at": "2026-11-07 15:30:00",
    "tracking_url": "https://rutery.com/rastrear/a1b2c3d4e5f6...z9"
  }
}

curl https://rutery.com/api/v1/orders/1042/status \
  -H "Authorization: Bearer TU_API_KEY"

curl -X POST https://rutery.com/api/v1/orders/1042/cancel \
  -H "Authorization: Bearer TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"motivo": "Cliente canceló el pedido"}'

Webhooks

Si configuras una webhook_url en tu comercio, te enviaremos un POST con cada cambio de estado de tus órdenes. Ideal para que tu bot notifique automáticamente al cliente.

Eventos disponibles:

• order.created — Orden creada
• order.assigned — Rider asignado
• order.at_pickup — Rider llegó al comercio
• order.on_way — Rider en camino al cliente
• order.delivered — Entregado
• order.cancelled — Cancelado

Payload recibido:

{
  "evento": "order.delivered",
  "orden_id": 1042,
  "codigo_externo": "PEDIDO-1042",
  "estatus": "ENTREGADA",
  "cliente": {
    "nombre": "María López",
    "telefono": "+584141234567"
  },
  "destino": {
    "direccion": "Av. Principal, Chacao",
    "lat": 10.4967,
    "lng": -66.8512
  },
  "costo_envio_usd": 1.42,
  "timestamp": "2026-11-07T15:30:00-04:00"
}

Verificación de firma:

Cada webhook incluye un header X-Signature-256 con la firma HMAC-SHA256 del payload usando tu webhook.secret_hmac.

// Ejemplo en Node.js
const crypto = require('crypto');
const signature = req.headers['x-signature-256'];
const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(req.body))
  .digest('hex');

if (signature !== expected) {
  throw new Error('Firma inválida');
}

Tracking público (comparte con el cliente)

Cada orden creada genera automáticamente un enlace público de rastreo. El cliente final puede abrirlo sin necesidad de cuenta ni login para ver el estado del envío en tiempo real.

El link:

https://rutery.com/rastrear/{token_tracking}

El token_tracking (64 caracteres hexadecimales) se devuelve automáticamente en:

• La respuesta de POST /orders/create → campo tracking_url
• La respuesta de GET /orders/{id}/status → campo tracking_url
• La respuesta de GET /orders → campo tracking_url por cada orden

Qué ve el cliente al abrir el link:

• Mapa interactivo con el destino (rojo) y el rider (verde) en vivo
• Estatus actual del pedido ("En camino a tu dirección", "¡Entregado!", etc.)
• Timeline de progreso visual
• Nombre del rider asignado
• Auto-actualización cada 10 segundos

Qué NO ve el cliente (privacidad):

• Dirección exacta (solo aparece el pin en el mapa)
• Datos del comercio (nombre, teléfono, dirección)
• Precio del envío ni datos de facturación
• Otros pedidos del mismo comercio

Integración con bots (WhatsApp, Telegram, Instagram)

Puedes automatizar el flujo completo de venta y entrega con un bot. No necesitas programar: con Make, Zapier o n8n puedes conectar tu bot (ManyChat, Chatfuel, WhatsApp Cloud API) con la API de Rutery.

Flujo de 5 pasos:

POST /api/v1/quote
{ "direccion_destino": "Av. Principal, Chacao" }
→ { "costo_envio_usd": 1.42, "costo_envio_ves": 1272.49 }

POST /api/v1/orders/create
{
  "cliente_final_nombre": "María López",
  "cliente_final_telefono": "+584141234567",
  "direccion_destino": "Av. Principal, Chacao",
  "codigo_externo": "PEDIDO-1042"
}
→ { "orden": { "id": 1042, "tracking_url": "https://rutery.com/rastrear/abc..." } }

Casos de uso