Envía pedidos de reparto a MOVEQIA desde tu sistema

Cómo funciona

Una integración con MOVEQIA tiene dos mitades. Las dos usan HTTPS y una firma HMAC-SHA256, en sentidos opuestos:

• Tú → MOVEQIA: envías un pedido de reparto a un único endpoint (ordersWebhook), firmado con la clave de tu comercio.
• MOVEQIA → tú: MOVEQIA envía cada cambio de estado del pedido (aceptado, recogido, en reparto, entregado…) a la URL que hayas registrado, firmado con un secreto compartido.

MOVEQIA se ocupa del emparejamiento con el rider, del precio del reparto y del cobro al comercio. Tú solo envías el pedido y consumes los estados.

Autenticación

Cada petición que envías a MOVEQIA se autentica con tres cabeceras. No se usan tokens de sesión ni OAuth: la identidad del comercio es su api_key, y la integridad del mensaje la garantiza la firma.

Cómo se calcula la firma

La firma se calcula sobre la marca de tiempo y el cuerpo crudo, unidos por un punto, usando tu propia api_key como secreto:

x-signature = HMAC_SHA256( clave = api_key ,  mensaje = "{x-timestamp}.{cuerpo_crudo}" )   →  hex

Ventana anti-repetición

MOVEQIA rechaza peticiones cuya x-timestamp se aleje más de 5 minutos del reloj del servidor. Mantén tu reloj sincronizado por NTP. La comparación de firmas se hace en tiempo constante.

const crypto = require("crypto");
const rawBody   = JSON.stringify(pedido);
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac("sha256", apiKey)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");

Crear un pedido

Envía un pedido de reparto en el formato canónico de MOVEQIA. El comercio en cuyo nombre creas el pedido es el dueño de la api_key con la que firmas.

Cuerpo de la petición

POST /functions/ordersWebhook
x-api-key: e82fbf5a…9ed5f1
x-timestamp: 1758560400
x-signature: 7542710c59fa…c0a1
Content-Type: application/json

{
  "external_order_id": "PEDIDO-2026-000123",
  "recipient": {
    "name": "Ana Martín",
    "phone": "+34600112233",
    "address": "Calle de Alcalá 100, 28009 Madrid"
  },
  "items_count": 1,
  "notes": "Portal, 3º B. Llamar al llegar."
}

{
  "ok": true,
  "order_id": "6ab2d29406429152e81ad62e",
  "external_order_id": "PEDIDO-2026-000123",
  "status": "buscando_rider"
}

Respuestas y errores

Webhooks de estado

Cuando el pedido avanza, MOVEQIA hace un POST a la URL que registraste. No tienes que consultar (no hay polling): los estados llegan solos.

Eventos

Cuerpo del webhook

X-Moveqia-Signature: 5b1c…e9af
Content-Type: application/json

{
  "event": "order.accepted",
  "order_id": "6ab2d29406429152e81ad62e",
  "external_order_id": "PEDIDO-2026-000123",
  "status": "accepted",
  "tracking_url": "https://app.moveqia.com/track/6ab2d294…",
  "rider": { "id": "218", "name": "Carlos R." },
  "timestamp": "2026-09-22T18:04:11Z"
}

Verificar la firma del webhook

Cada webhook llega firmado en la cabecera X-Moveqia-Signature. Verifícala antes de procesar el evento: calcula el HMAC-SHA256 del cuerpo crudo con tu secreto de webhook y compáralo en tiempo constante.

X-Moveqia-Signature = HMAC_SHA256( clave = tu_secreto_webhook , mensaje = cuerpo_crudo )  →  hex

Conciliación e idempotencia

• Concilia por external_order_id. Es tu clave del pedido de principio a fin: viaja en la creación y vuelve en cada webhook.
• Los webhooks pueden repetirse. Por los reintentos, un mismo evento puede llegarte más de una vez. Haz que tu procesamiento sea idempotente (por ejemplo, ignora un estado que ya registraste).
• Un comercio, una cuenta. Cada comercio tiene una única cuenta y una única api_key. Un comercio con varias sedes las gestiona dentro de su cuenta, no como cuentas separadas.

Checklist de integración

• Reloj sincronizado por NTP (la firma caduca a los 5 minutos).
• Firmas y envías el mismo cuerpo crudo, sin re-serializar.
• Guardas tu api_key y tu secreto de webhook fuera del código (variables de entorno / gestor de secretos).
• Verificas X-Moveqia-Signature en cada webhook antes de procesarlo.
• Tu receptor responde 200 rápido y es idempotente.
• Manejas order.no_coverage y order.dispatch_failed como estados que requieren tu atención.