QuadMinds Stork API — Visibilidad y Ejecución en Tiempo Real

La capa de tracking en vivo. Responde preguntas técnicas sobre monitoreo de última milla, alertas, integración con sistemas externos y capacidades de visibilidad en tiempo real.

Qué es Stork y por qué importa

Stork es la API de ejecución de QuadMinds. Mientras que la API v2 se ocupa de la planificación (qué rutas hacer, cómo optimizarlas), Stork toma el control una vez que el conductor sale a la calle.

Es la capa que responde preguntas como:

¿Dónde está mi flota ahora mismo?
¿Qué pedidos están demorados?
¿Cuándo llegó el conductor al cliente X?
¿Qué incidentes ocurrieron hoy?
¿Cómo me entero en tiempo real cuando algo sale mal?

Base URL: https://stork-test.quadminds.com/apis/stork-api

Entidades principales de Stork

Trips (Viajes)

La entidad central de Stork. Un Trip representa un viaje en ejecución — el conductor en la calle haciendo entregas.

Operaciones disponibles:

GET /trips — listar trips con filtros
POST /trips — crear trip
PATCH /trips/{id} — actualizar trip
DELETE /trips/{id} — eliminar trip
POST /trips/bulk — creación masiva de trips
PUT /trips/bulk — actualización masiva
DELETE /trips/bulk — eliminación masiva
POST /trips/{id}/start — iniciar un trip
POST /trips/{id}/close — cerrar un trip
POST /trips/{id}/checkpoint — registrar checkpoint (llegada a un punto)
POST /trips/{id}/checkpoint/certification — certificar entrega en un checkpoint

Alerts (Alertas)

Sistema de alertas en tiempo real para monitoreo de incidentes en la operación.

Qué monitorea:

Desvíos de ruta
Demoras respecto al ETA
Incidentes reportados por conductores
Eventos que requieren acción del equipo de control

Operaciones:

GET /alerts — consultar alertas activas y históricas
POST /alerts — crear alerta manual
POST /alerts/{id}/comments — agregar comentario a una alerta
PUT /alerts/{id} — actualizar alerta (auditable — el sistema registra quién y cuándo)

La auditabilidad de las alertas es clave para compliance operativo: cada modificación queda trazada.

Events (Eventos)

Sistema de eventos que registra todo lo que ocurre en la operación. Más granular que las alertas.

Capacidades:

GET /events — consultar eventos con filtros (por trip, carrier, driver, fecha)
POST /events/{id}/resolve — resolver un evento
POST /events/bulk/resolve — resolución masiva de eventos
POST /events/{id}/comments — agregar comentarios colaborativos

Los eventos son la base para integraciones con sistemas externos: un ERP o WMS puede consultar el feed de eventos para actualizar su estado interno.

Triggers

Mecanismo de webhooks y notificaciones automáticas. Permiten que sistemas externos sean notificados cuando ocurren eventos específicos en la operación.

Casos de uso:

Notificar al cliente final cuando el conductor está a N minutos
Disparar un proceso en el ERP cuando una entrega se certifica
Alertar al equipo de control cuando un trip supera el tiempo estimado
Integrar con sistemas de atención al cliente (CRM) ante incidentes

Locations (Ubicaciones)

Gestión de ubicaciones geográficas dentro del sistema Stork.

Operaciones: CRUD completo + creación masiva (POST /locations/bulk)

Zones (Zonas)

Definición de zonas geográficas de operación en el contexto de Stork. Usadas para:

Delimitar áreas de cobertura por carrier
Definir reglas de negocio por zona (tiempos de servicio, restricciones)
Análisis de performance por territorio

Carriers (Transportistas)

Gestión de los operadores de transporte — propios o terceros (3PL, última milla contratada).

Permite a empresas que tercerizan parte de su distribución tener visibilidad unificada: flota propia + carriers externos en el mismo dashboard.

Drivers y Vehicles (en Stork)

Gestión de conductores y vehículos en el contexto de ejecución — separada de la planificación, lo que permite actualizar el estado operativo en tiempo real sin afectar la planificación.

Trip Definitions y State Definitions

State Definitions: Catálogo configurable de estados posibles para un Trip. Cada cliente puede definir sus propios estados (ej: "En depósito", "En tránsito", "Esperando descarga", "Completado").

Trip Definitions: Templates de trips — configuración reutilizable para tipos de operación frecuentes.

Logs

Registro de eventos internos de cada trip. Permite:

POST /trips/{id}/logs — agregar entradas de log
DELETE /trips/{id}/logs/{logId} — remover entradas

Útil para integraciones que necesitan inyectar eventos de sistemas externos (ej: un escáner de código de barras en el depósito).

Tags y Organization Keys

Tags: Etiquetado flexible de trips y entidades para categorización y filtrado
Organization Keys: Gestión de claves de organización para control de acceso multi-tenant

Autenticación en Stork

Stork soporta dos métodos, a diferencia de la API v2 que solo usa API Key:

Método	Header	Uso recomendado
API Key	`x-stork-apikey: [key]`	Integraciones server-to-server, cron jobs, webhooks
Bearer JWT	`Authorization: Bearer <TOKEN>`	Sesiones de usuario (~15 min de vida)

La doble autenticación hace a Stork apropiada tanto para integraciones de backend (API key) como para apps móviles o dashboards web (JWT).

Casos de integración técnica con Stork

Torre de Control en tiempo real

Un cliente puede construir su propia torre de control consultando Stork:

GET /trips + GET /alerts en polling o via triggers (webhooks)
Visualizar en mapa la posición de toda la flota
Ver demoras, incidentes y certificaciones en vivo

Notificación proactiva al cliente final

Usando Triggers: configurar un webhook que dispare cuando el conductor certifica llegada al POI anterior → notificar al cliente siguiente "tu entrega llega en X minutos".

Cierre automático de órdenes en ERP

Cuando Stork registra POST /trips/{id}/checkpoint/certification → Trigger → webhook → ERP marca la Order como entregada y lanza la facturación.

Auditoría y compliance

Todos los estados, checkpoints, certifications y alert updates son auditables con timestamp. Permite responder auditorías: "¿a qué hora llegó el conductor?, ¿quién modificó el estado?, ¿hay foto de la entrega?".

Por qué Stork diferencia a QuadMinds

La mayoría de los TMS del mercado planifican rutas pero tienen visibilidad limitada en la ejecución. Stork cierra ese gap:

La planificación y la ejecución están integradas en la misma plataforma — no hay que cruzar datos entre sistemas
Los triggers/webhooks permiten que sistemas externos (ERP, CRM, e-commerce) reaccionen en tiempo real a lo que pasa en la calle
El modelo de Carriers permite visibilidad unificada de flota propia + terceros
La auditabilidad de alertas y eventos cubre requerimientos de compliance en industrias reguladas (farma, alimentos, logística refrigerada)
Las operaciones bulk soportan operaciones de alto volumen sin degradación — miles de trips y eventos procesados en un solo request