Ir al contenido

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.

Descripción legible por máquina (OpenAPI)

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.

API y webhooks

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.