← Hub
Commercial Brain — Knowledge Base
API Docs ↗

QuadMinds — Modelo de Datos y Capacidades de la API

Para responder preguntas técnicas sobre qué puede hacer la plataforma a nivel de datos, operaciones y configuración.

Qué puede controlar un integrador por API

QuadMinds expone prácticamente toda la operativa logística por API. Esto significa que un cliente puede automatizar el 100% del ciclo —desde la carga de pedidos hasta la consulta de resultados de entrega— sin tocar la interfaz gráfica.

Entidades del modelo de datos (QuadMinds API v2 / CloudFlash)

Gestión de pedidos y entregas

Orders (Órdenes)

  • CRUD completo: crear, consultar, modificar, eliminar
  • Cada Order tiene: items, medidas (peso, volumen, bultos), ventanas horarias, estado
  • El estado de una Order se actualiza en tiempo real según las acciones del conductor en la app
  • Posibles estados: pendiente, en ruta, entregada, fallida, certificada

OrderItems

  • Ítems individuales dentro de una Order
  • Permiten tracking a nivel de producto dentro del pedido

OrderMeasures

  • Unidades de medida configurables (kg, litros, bultos, pallets)
  • Se usan para respetar la capacidad de cada vehículo en la optimización

OrderStatus / ConstraintTypes

  • Catálogos configurables para clasificar estados y restricciones de entrega según la operación del cliente

Collections

  • Gestión de cobranzas o recolecciones en el mismo viaje (útil para distribuidores que cobran en punto de entrega)

Red logística

POIs — Points of Interest

  • La entidad base de la red de distribución
  • Representan: clientes, depósitos, puntos de carga, centros de distribución
  • Cada POI tiene: código único, tipo, coordenadas, ventanas horarias, frecuencia de visita
  • Errores controlados: duplicados de código (2020), solapamiento de ventanas horarias (2004), frecuencias inválidas (2024)

PoiTypes

  • Clasificación de POIs: cliente, depósito, punto intermedio, etc.
  • Configurable por organización

Areas

  • Regiones geográficas de operación
  • Usadas para segmentar la planificación por territorio

Zones

  • Subdivisiones dentro de las áreas
  • Opcionales, pero necesarias para enfoques de planificación por zona

Waypoints

  • Las paradas dentro de una ruta ya generada
  • Cada waypoint tiene: POI asignado, ETA calculado, duración de servicio estimada, orden en la ruta
  • Es la "foto" de la ruta optimizada antes de ejecutarse

Flota y recursos humanos

Vehicles

  • Flota completa con capacidades (peso, volumen, bultos), restricciones operativas y disponibilidad
  • La capacidad del vehículo es el constraint principal del optimizador

Drivers

  • Conductores con sus horarios, zonas habilitadas y app móvil asignada
  • Salida (Salida): si un conductor tiene más carga de la que cabe en un viaje, se generan múltiples salidas en el día

Things

  • Activos físicos adicionales: remolques, contenedores, equipamiento especial

Estructura comercial y organizativa

Merchants

  • Operadores o clientes B2B en modelos de operación multi-tenant
  • Permite que un 3PL gestione múltiples clientes (shipper/retailer) en una sola instancia

Organizations

  • Estructura jerárquica para empresas con múltiples unidades de negocio o países

Users

  • Gestión de usuarios y roles por API

ActivityTypes / Notifications

  • Tipos de actividades en la operación y configuración de notificaciones automáticas

Products

  • Catálogo de productos transportados, vinculados a OrderItems

Planificación: cómo funciona el optimizador

El optimizador de QuadMinds toma los Inputs y genera rutas considerando múltiples restricciones simultáneas:

Constraints de cantidad por ruta:

  • Duración máxima del viaje (horas)
  • Distancia máxima por ruta (km)
  • Capacidad del vehículo (peso, volumen, unidades)

Constraints de secuencia:

  • Menor distancia total recorrida
  • Menor tiempo de viaje
  • Ventanas horarias de los clientes (horario en que pueden recibir)

Requisitos mínimos para planificar:

  • Al menos un depósito configurado (obligatorio)
  • Zonas (opcional, según el enfoque de planificación elegido)

Concepto de Salida: Si el volumen de pedidos supera la capacidad de un vehículo, o si las ventanas horarias lo requieren, el sistema genera múltiples salidas diarias para el mismo conductor (viaje 1, viaje 2, etc.).

Certificación de entregas

La certificación es el proceso de verificación de que una entrega ocurrió. Es técnicamente relevante porque:

  1. El conductor usa la app móvil para registrar en campo: fotos, firma digital, comentarios, resultado (entregado / no entregado)
  2. Cada acción del conductor actualiza el estado de la Order en tiempo real — consultando el endpoint de Orders se obtiene el estado actual
  3. Vía Stork API existe un endpoint específico: POST /trips/{id}/checkpoint/certification para registrar certificaciones de checkpoints en el contexto de un Trip
  4. La ruta cierra cuando el conductor completa todos los waypoints o finaliza su turno

Escalabilidad: qué pasa con grandes volúmenes

  • Paginación estándar: hasta 1.000 registros por request
  • Operaciones bulk disponibles en Stork (creación masiva de trips, órdenes, resolución de eventos)
  • El modelo de Organizations + Merchants soporta operaciones multi-país y multi-cliente desde una sola API

Soporte a desarrolladores

  • Documentación completa en: docs.quadminds.com
  • Email técnico: api@quadminds.com
  • Errores tienen respuesta estructurada con statusCode, error, message y code interno — facilita el manejo de errores en integraciones de producción