← Hub
Commercial Brain — Knowledge Base
API Docs ↗

QuadMinds — Arquitectura Técnica e Integración

Documento técnico para responder preguntas de CTOs, CEOs técnicos y equipos de integración.

Modelo conceptual: Input → Optimización → Output

La arquitectura de QuadMinds se basa en un flujo simple y poderoso:

Inputs que recibe la plataforma:

  • POIs (Points of Interest): puntos de entrega, clientes, depósitos, zonas de servicio
  • Orders: órdenes de entrega con sus restricciones (ventanas horarias, capacidad, prioridad)

Outputs que genera la plataforma:

  • Routes con Waypoints: rutas optimizadas asignadas a cada conductor, en el orden y horario óptimo
  • Resultados de entrega: estado de cada Order (entregada, fallida, certificada, con incidente)

Este modelo aplica tanto vía interfaz gráfica como 100% por API.

Las 3 APIs de QuadMinds

QuadMinds expone tres APIs distintas que cubren el ciclo completo de operaciones logísticas:

1. QuadMinds API v2

Rol: Planificación y optimización
Base URL: https://saas.quadminds.com
Ambiente: SaaS (clientes estándar)

Gestiona el core del proceso: desde la ingesta de pedidos hasta la generación de rutas optimizadas.

Entidades principales:

  • Orders — pedidos con ventanas horarias, medidas, ítems y status
  • Routes / Consolidated Routes — rutas generadas por el optimizador
  • Waypoints — paradas dentro de cada ruta con ETA calculado
  • Vehicles — flota con capacidades, restricciones y disponibilidad
  • Drivers — conductores con horarios y zonas asignadas
  • Pois (Points of Interest) — puntos de entrega y depósitos
  • Areas / Zones — delimitación geográfica del territorio
  • Merchants — operadores o clientes B2B en modelos multi-tenant
  • Products — catálogo de productos transportados
  • Organizations — estructura multi-organización

2. CloudFlash API

Rol: Planificación y optimización (variante de entorno)
Base URL: https://flash.quadminds.com
Ambiente: CloudFlash (clientes en entorno dedicado)

Misma estructura de entidades y endpoints que la v2. Los clientes operan en uno u otro ambiente según el tipo de contrato. Permite a empresas con requerimientos específicos de aislamiento tener su propia instancia.

3. Stork API

Rol: Ejecución y visibilidad en tiempo real
Base URL: https://stork-test.quadminds.com/apis/stork-api

La capa de tracking y ejecución. Una vez que las rutas están planificadas, Stork toma el control del seguimiento en campo. (Ver documento 33-stork-visibilidad-tiempo-real para detalle completo.)

Entidades clave: Trips, Alerts, Events, Checkpoints, Carriers, Locations, Triggers, Zones.

Autenticación

QuadMinds API v2 y CloudFlash

  • Método: API Key por header HTTP
  • Header: x-saas-apikey: [tu_api_key]
  • Gestión: Las API keys se generan y regeneran desde la sección Configuración del usuario en la plataforma
  • Ejemplo:
curl --request GET \
  --url 'https://saas.quadminds.com/api/v2/pois/search?limit=100&offset=0' \
  --header 'x-saas-apikey: [tu_api_key]'

Stork API

Soporta dos métodos:

  1. API Key: Header x-stork-apikey: [tu_api_key] — para integraciones server-to-server
  2. Bearer Token (JWT): Header Authorization: Bearer <TOKEN> — tokens de vida corta (~15 minutos), para contextos donde se requiere autenticación por sesión

Ambientes de despliegue

Ambiente URL Base Descripción
SaaS https://saas.quadminds.com Ambiente multi-tenant estándar
CloudFlash https://flash.quadminds.com Ambiente dedicado por cliente
Stork https://stork-test.quadminds.com Tracking y ejecución

Los clientes identifican en cuál ambiente están al momento del onboarding. Las credenciales y configuración son específicas por ambiente.

Paginación estándar

Todas las APIs usan paginación consistente:

Parámetro Descripción Default Máximo
limit Registros por página 100 1.000
offset Registros a saltear 0 —

Respuesta incluye siempre un objeto meta:

{
  "meta": {
    "total": 4116,
    "offset": 0,
    "limit": 100
  }
}

Esto permite a integraciones procesar grandes volúmenes de datos (miles de órdenes) de forma eficiente y predecible.

Contacto técnico