Para desarrolladores
API y webhooks
Su tienda en línea u otro sistema envía los pedidos a Routehive como paradas y recibe el estado de la entrega por webhook o por consulta. Disponible en los planes Pro y Flota.
Autenticación
El propietario o un administrador crea la clave API en la página API y webhooks de la aplicación. La clave se muestra una sola vez. Envíela en la cabecera de cada solicitud como token Bearer. Con una clave de solo lectura no se pueden añadir paradas.
curl -X POST https://routehive.eu/api/v1/stops \
-H "Authorization: Bearer rh_..." \
-H "Content-Type: application/json" \
-d '{
"address": "Budapest, Andrássy út 1.",
"name": "Example Ltd.",
"phone": "+36 30 123 4567",
"reference": "WS-1001",
"cod_amount": 12500,
"packages": ["PKG-1001"]
}'Endpoints
GET /api/v1/routes?date=YYYY-MM-DD- Las rutas de un día (por defecto hoy, en la zona horaria de la empresa).
GET /api/v1/routes/{id}- Una ruta con sus paradas, en orden.
POST /api/v1/stops- Una parada nueva, por ejemplo un pedido en línea.
GET /api/v1/stops/{id}- Estado de una parada: entregada, fallida, importe cobrado, foto y firma.
Añadir una parada
Sin ruta, la parada va a la ruta Entrantes del día y el despachador la asigna desde allí. Si vuelve a enviar el mismo número de pedido (reference) para el mismo día, no se crea una parada nueva: recibe la existente. Reenviar es seguro.
Campos
address- La dirección (obligatoria). Con coordenadas se omite la geocodificación.
name- Nombre del destinatario o de la empresa.
phone, email- Teléfono y correo electrónico para las notificaciones.
reference- Su número de pedido: identifica la parada en los webhooks y evita duplicados.
cod_amount, payment_required- Contra reembolso en la unidad más pequeña de la moneda (forinto: forintos enteros, euro: céntimos).
date- Día de la ruta Entrantes (AAAA-MM-DD). Por defecto hoy.
route_id- Una ruta concreta en lugar de Entrantes, si aún admite paradas.
packages- Códigos de barras de los paquetes: el conductor los escanea antes de la entrega.
require_photo, require_signature- Foto o firma obligatoria para la entrega.
Webhooks
Indique la URL del webhook en la misma página (solo https) y elija los eventos. Routehive envía un JSON por POST en cada evento; el contenido es el mismo que la respuesta del estado de una parada.
stop.delivered- Se entregó una parada (con el importe cobrado y los indicadores de foto y firma).
stop.failed- Una entrega falló (con la nota del conductor).
route.dispatched- Se envió una ruta al conductor.
route.completed- Se completó una ruta.
{
"event": "stop.delivered",
"event_id": "stop_..._delivered_20261120143005123",
"created_at": "2026-11-20T14:30:05Z",
"data": {
"id": "...",
"route_id": "...",
"reference": "WS-1001",
"status": "delivered",
"delivered_at": "2026-11-20T14:30:04Z",
"note": null,
"payment_required": true,
"paid": true,
"cod_amount": 12500,
"collected_amount": 12500,
"has_photo": true,
"has_signature": false
}
}Verificar la firma
Cada solicitud lleva la cabecera X-Routehive-Signature: t=marca de tiempo,v1=firma. La firma es el HMAC-SHA256 de la marca de tiempo, un punto y el cuerpo sin procesar, con el secreto del webhook. Si no coincide, rechace la solicitud.
import { createHmac, timingSafeEqual } from "node:crypto";
// header: X-Routehive-Signature, body: the raw request body (string)
function verify(header, body, secret) {
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && timingSafeEqual(Buffer.from(v1, "hex"), Buffer.from(expected, "hex"));
}Cualquier respuesta 2xx confirma la recepción. Ante errores reintentamos cada vez con menos frecuencia (1 minuto, 5 minutos, 30 minutos, 2 horas, 12 horas, 24 horas). Tras 50 fallos seguidos, el webhook se desactiva y el propietario recibe un correo.
Errores y límites
Los errores tienen la forma {"error": {"code": …, "message": …}}. El código está en inglés, el mensaje en el idioma de su empresa. Cada clave puede hacer 120 solicitudes por minuto; por encima recibe 429.
Mañana por la mañana ya podrá planificar así
Regístrese, añada a sus conductores y cargue sus direcciones. Gratis hasta 15 paradas en total, en 2 rutas, sin tarjeta de crédito.