Guía de integración · MOVEQIA Delivery

Conecta tu sistema a MOVEQIA en cinco pasos

Esta guía te lleva de cero a un pedido de reparto real: dar de alta tu integración, enviar tu primer pedido y recibir sus estados. Para el detalle exacto de cada campo y código, tienes al lado la referencia de la API.

Tiempo estimado: una tarde · Necesitas: poder hacer peticiones HTTPS y exponer un endpoint público.

Antes de empezar

MOVEQIA reparte los pedidos que tú le envías en nombre de un comercio. Tu sistema hace dos cosas: manda pedidos y escucha sus estados. Nada más. El emparejamiento con el rider, el precio del reparto y el cobro al comercio los gestiona MOVEQIA.

Qué necesitas de MOVEQIA El alta es asistida. Escribe al equipo y te entregan: tu api_key (identifica a tu comercio), tu secreto de webhook (para verificar los estados que te llegan) y registran la URL donde quieres recibirlos.

Los cinco pasos

1

Da de alta tu integración

Ponte en contacto con MOVEQIA para dar de alta tu comercio y tu integración. Al terminar tendrás tres cosas guardadas en un lugar seguro (variables de entorno o un gestor de secretos, nunca en el código):

  • Tu api_key — 64 caracteres hexadecimales.
  • Tu secreto de webhook — para comprobar que los estados vienen de MOVEQIA.
  • La URL base de la API (por ejemplo https://app.moveqia.com).

Y le habrás dado a MOVEQIA la URL pública donde quieres recibir los estados.

2

Envía tu primer pedido

Un pedido es un JSON con el destinatario y, como mínimo, tu external_order_id (tu identificador del pedido). Se envía firmado al endpoint /functions/ordersWebhook. La firma es un HMAC-SHA256 del cuerpo con tu api_key; los detalles están en la referencia.

La forma más rápida de probar es con el cliente de ejemplo:

MOVEQIA_API_BASE="https://app.moveqia.com" \
MOVEQIA_API_KEY="tu_api_key" \
node enviar-pedido.js

Una respuesta HTTP 200 significa que el pedido entró y MOVEQIA empieza a buscar rider. Si ves un 409, el comercio todavía no está verificado: complétalo una vez en MOVEQIA y vuelve a probar.

3

Recibe los estados

A partir de la creación, MOVEQIA te avisa de cada cambio (aceptado, recogido, en reparto, entregado…) haciendo un POST a tu URL. No tienes que preguntar: los estados llegan solos. Levanta el receptor de ejemplo para verlos:

MOVEQIA_WEBHOOK_SECRET="tu_secreto_de_webhook" \
PORT=3000 \
node receptor-webhook.js

Cada webhook llega firmado en la cabecera X-Moveqia-Signature. Verifica siempre esa firma antes de fiarte del contenido: el ejemplo ya lo hace por ti.

4

Concilia y actúa sobre los estados

Usa tu external_order_id como clave para casar cada webhook con tu propio pedido. Además de los estados normales, presta atención a dos avisos:

  • order.no_coverage — ningún rider aceptó. Decide si reintentar, subir el precio o avisar al cliente.
  • order.dispatch_failed — el pedido se aceptó pero hubo un problema al asignarlo; conviene revisarlo.

Como un mismo evento puede repetirse (MOVEQIA reintenta si tu endpoint no responde), haz que tu procesamiento sea idempotente: ignora un estado que ya habías registrado.

5

Antes de pasar a producción

  • Sincroniza el reloj de tu servidor por NTP — la firma caduca a los 5 minutos.
  • Guarda la api_key y el secreto fuera del código.
  • Responde 200 rápido en tu receptor y procesa después.
  • Verifica la firma de todos los webhooks.
  • Prueba el camino de error, no solo el feliz: un pedido sin cobertura y uno cancelado.

Recursos

  • Referencia de la API — el contrato completo: campos, códigos de respuesta, firma y webhooks.
  • Cliente de ejemplo — enviar-pedido.js, receptor-webhook.js y su README. Node.js, sin dependencias.
¿Dudas en el alta? El equipo de MOVEQIA configura tu integración contigo. Si un pedido no entra o un webhook no llega, revisa primero la firma y el reloj; son la causa del 90 % de los problemas.