Conecta tu negocio.
Coordina cada entrega.

Una organización. Una conexión.

Un propietario o administrador gestiona la conexión desde el dashboard, incluso en el navegador del celular. La API limita cada clave a su organización y a los pedidos que creó esa integración. No necesitas credenciales de Supabase de TRAQQI.

1https://traqqi-worker.iqqiadmin.workers.dev

No están implementados cancelación o transferencia por API, checkout de Stripe, claves de sandbox, tokens públicos para compradores ni eventos independientes de inicio/cierre de ruta. Los pedidos de prueba usan la base actual: acuerda una organización de pruebas antes de enviar datos.

Tu clave se queda en tu servidor.

Inicia sesión con la misma cuenta de la app, selecciona tu negocio y entra a Conexión API. Solo owner/admin puede crear, pausar, reactivar, configurar, rotar o revocar la integración; el servidor vuelve a comprobar la sesión y la membresía en cada comando.

1Authorization: Bearer <CLAVE_PRIVADA_DE_LA_INTEGRACION>

• La clave tiene prefijo tq_live_ y solo se revela al crearla o rotarla. Guarda el valor en un gestor de secretos; nunca en URLs, JavaScript público, apps móviles o repositorios.
• Rotar invalida la clave anterior inmediatamente, sin período de convivencia. Coordina el reemplazo en tu backend. Si perdiste la respuesta de creación, consulta la conexión y rota la clave; no repitas el alta.
• Permisos: deliveries:read, deliveries:write, events:read, codes:read y tracking:read. Para obtener códigos por consulta de eventos necesitas tanto events:read como codes:read.
• Configura hasta diez orígenes HTTPS exactos, sin rutas ni comodines. Si envías Origin, debe estar permitido. Sin esa cabecera se admite un servidor con clave válida, salvo que actives require_origin.

Crea una vez. Reintenta con seguridad.

1curl -X POST 'https://traqqi-worker.iqqiadmin.workers.dev/v1/deliveries' \
2  -H 'Authorization: Bearer <CLAVE_PRIVADA>' \
3  -H 'Content-Type: application/json' \
4  -H 'Idempotency-Key: pedido-123-intento-01' \
5  --data '{
6  "external_id": "PEDIDO-123",
7  "recipient_name": "Cliente de ejemplo",
8  "recipient_phone": "+12025550101",
9  "delivery_address": "Dirección ilustrativa de entrega, Monterrey",
10  "latitude": 25.68,
11  "longitude": -100.31,
12  "delivery_notes": "Pedido sintético; no entregar ni contactar."
13}'

El cuerpo es plano. No envíes campos adicionales como organización, repartidor o estado: se rechazan con 400 unknown_field. La clave determina el negocio. La referencia que muestra la app se genera como API-<uuid>; conserva también el ID retornado.

1{
2  "id": "6d12b2ba-a0ca-49ef-9bfc-8bc9ca0b5bfa",
3  "external_id": "PEDIDO-123",
4  "replayed": false
5}

Idempotency-Key es obligatoria: 8–100 caracteres de [A-Za-z0-9_-]. Repetir la misma clave y cuerpo devuelve 201 con el mismo ID y replayed: true. Cambiar el cuerpo produce 409 idempotency_conflict; otro intento de crear una referencia existente produce 409 external_id_exists. El recibo dura siete días; la referencia externa sigue siendo única después.

Consultar y reconciliar

Los tres GET de pedidos devuelven {data: [...]}. La consulta por UUID contiene un elemento o devuelve 404; la búsqueda por referencia retorna cero o uno. El listado contiene como máximo 50, ordenados por UUID, no por fecha: usa el último id como after y continúa hasta recibir una página vacía. Codifica los parámetros de búsqueda.

1{
2  "data": [
3    {
4      "id": "6d12b2ba-a0ca-49ef-9bfc-8bc9ca0b5bfa",
5      "external_id": "PEDIDO-123",
6      "reference": "API-6d12b2ba-a0ca-49ef-9bfc-8bc9ca0b5bfa",
7      "status": "awaiting_pickup",
8      "version": 1,
9      "created_at": "2026-11-04T17:00:00Z",
10      "assigned_at": null,
11      "delivered_at": null,
12      "failed_at": null,
13      "failure_reason": null
14    }
15  ]
16}

La lectura no devuelve teléfono, dirección, identidad del repartidor ni código. Tu sistema conserva los datos originales y relaciona cada pedido con su comprador.

Cada entrega tiene su momento.

1awaiting_pickup → assigned → in_transit → delivered
2                                    ↘ failed
3failed → awaiting_pickup (reprogramación autorizada)

assigned significa que el repartidor tomó el pedido. in_transit significa que inició la ruta. La app y sus comandos autorizados gestionan estas transiciones; la API externa no permite forzar estados ni confirmar una entrega. Un intento fallido conserva su motivo y requiere el flujo operativo de devolución/reprogramación antes de un nuevo intento.

Usa version en lecturas y aggregate_version en eventos para reconocer estados anteriores. No supongas orden de llegada de los webhooks. Un evento de código puede compartir versión con el estado del intento: deduplica por event_id, no solo por versión.

Recibe cambios sin perder el contexto.

Consulta con cursor

1GET https://traqqi-worker.iqqiadmin.workers.dev/v1/events?after=0
2Authorization: Bearer <CLAVE_PRIVADA>
3
4{ "data": [], "retention_days": 7 }

Se devuelven hasta 50 eventos en orden ascendente. El cursor es un decimal de hasta 18 dígitos representado como texto: no lo conviertas a Number. Procesa y guarda de forma durable el cursor del último evento; úsalo como after en la siguiente consulta. Tolera huecos. Tras una interrupción mayor a siete días, reconcilia los estados con el listado de pedidos. No es un historial permanente.

Receptor HTTPS y firma

Solicita a soporte la autorización del host público de tu receptor. El operador lo incluye en WEBHOOK_HOSTS; escribir una URL en el dashboard no autoriza su dominio automáticamente. Después configura una URL HTTPS sin credenciales, puerto, parámetros ni fragmento y guarda el secreto de firma mostrado una vez. Solo se admite un receptor por negocio. Se envían los eventos de esa integración; actualmente no hay selección de tipos de webhook. Los permisos de consulta de códigos no sustituyen la protección del receptor, que también recibe códigos.

1Content-Type: application/json
2Traqqi-Event-Id: 7e97735d-0f3b-4ac1-a737-7872b9179281
3Traqqi-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
4
5{
6  "cursor": "125",
7  "event_id": "7e97735d-0f3b-4ac1-a737-7872b9179281",
8  "event_type": "delivery.confirmation_code.issued",
9  "schema_version": 1,
10  "organization_id": "db875790-dd98-47a7-9307-647ea1201711",
11  "delivery_id": "6d12b2ba-a0ca-49ef-9bfc-8bc9ca0b5bfa",
12  "external_id": "PEDIDO-123",
13  "aggregate_version": 2,
14  "attempt_id": "425079ec-ec86-4892-b0fa-c3407851289e",
15  "occurred_at": "2026-11-04T18:00:00Z",
16  "expires_at": "2026-11-05T18:00:00Z",
17  "payload": {
18    "code": "123456"
19  }
20}

Verifica HMAC-SHA256 sobre timestamp + "." + cuerpo_original, con el secreto de firma del webhook (distinto a la clave API), comparación en tiempo constante y tolerancia de cinco minutos. El cuerpo debe ser los bytes originales, antes de parsear JSON; no lo serialices de nuevo para verificarlo. Comprueba que la cabecera de ID coincida con event_id.

Los eventos de estado incluyen payload.status y, cuando corresponde, payload.failure_reason. El sobre contiene schema_version: 1, aggregate_version, fechas UTC, IDs y cursor. Tolera campos nuevos y eventos desconocidos. Algunas respuestas de polling pueden incluir ciphertext: null; no es un campo que deba consumir tu aplicación.

El código llega al comprador.

Al recoger un pedido integrado se solicita un código de seis dígitos. El Worker lo emite de forma asíncrona: procesa hasta diez pendientes cada minuto. Puede tardar un minuto o más si hay cola. Tu backend espera delivery.confirmation_code.issued y comunica payload.code únicamente al comprador autorizado.

Conserva el código como texto para preservar ceros iniciales. attempt_id y expires_at están en el sobre del evento, no dentro de payload. Caduca como máximo a las 24 horas y deja de ser válido al consumirse o invalidarse el intento. La app del repartidor solicita el código al recibir el paquete; no puede consultar el código privado de la integración.

Los códigos caducados o de intentos terminados no se recuperan mediante polling ni deben reutilizarse desde tu copia. Si un webhook de código llega después de un cambio de estado, consulta el estado actual y descártalo cuando ya no corresponda. No registres códigos en logs, analítica o herramientas de soporte.

Solo cuando corresponde compartir.

El endpoint está implementado y se verificó técnicamente con ubicaciones sintéticas. Para responder con coordenadas requiere: pedido propio en in_transit, ruta activa, última ubicación de menos de dos minutos y autorización temporal de seguimiento de ese pedido. Ese foco caduca a los cinco minutos y su conexión con la selección de destino en la app todavía está pendiente.

1{ "available": false, "location": null }

1{
2  "available": true,
3  "location": {
4    "latitude": 25.68,
5    "longitude": -100.31,
6    "accuracy": 15,
7    "observed_at": "2026-11-04T18:00:00Z"
8  }
9}

Trata available: false como un estado normal, sin mostrar una ubicación vieja como actual. No hay historial de recorrido, identidad del repartidor ni acceso al resto de su ruta. La entrega finalizada corta la disponibilidad. No anuncies rastreo externo completo hasta validar el recorrido con dispositivos reales.

Tu backend autoriza al comprador; el navegador nunca consulta TRAQQI con la clave privada. Como recomendación de consumo, consulta cada uno o dos minutos mientras la vista esté abierta y detén las consultas cuando termine la entrega. Ese intervalo es una recomendación, no una cuota adicional implementada.

Diseña también para los reintentos.

1{ "error": "idempotency_conflict", "request_id": "4e5486cb-62e9-44b2-af1b-56743e4c0447" }

Los errores llevan un identificador de solicitud y la cabecera X-Request-Id. Guarda este identificador para soporte; no registres Authorization, teléfonos, direcciones ni cuerpos con códigos.

Reintentos de webhooks

Hasta diez intentos durante un máximo de 24 horas, con espera exponencial y jitter. Fallos de red, timeout, 408, 429 y 5xx se reintentan. Retry-After del receptor se respeta dentro del límite de una hora. No se siguen redirecciones: 3xx y los demás 4xx terminan el envío. No existe todavía un panel de reenvío ni alertas automáticas al administrador; usa polling como recuperación y monitoriza tu receptor.

Menos datos. Más claridad.

• 120 solicitudes por minuto calendario por integración, compartidas entre lecturas y escrituras. Existe además un limitador aproximado de 60 solicitudes por IP por minuto en el borde de Cloudflare; no es una cuota global exacta.
• Cuerpo JSON máximo: 16 KiB. UUID para IDs, UTC ISO 8601 para fechas, enteros para versiones y cadenas para códigos/cursors.
• Eventos y recibos de idempotencia: siete días. Código recuperable: máximo 24 horas o fin del intento. Auditoría de integración: 90 días. Solo última ubicación, sin historial continuo de GPS.
• Respuestas privadas con Cache-Control: no-store. No expongas respuestas privadas en cachés compartidas.
• El procesamiento inicial usa lotes de diez webhooks y dos receptores simultáneos. No se garantiza entrega inmediata ni se anuncia SLA.

Pedidos, cuentas y otros datos tienen sus propias políticas: estos plazos no significan que todos los datos se borren a los siete días. Consulta el aviso de privacidad. Tolera cambios aditivos en respuestas y eventos.

Comprueba el recorrido completo.