Saltar al contenido principal
Version: 1.0.0

ECMR Backend API

Plataforma API REST del backend ECMR de Cargoffer para digitalizar y operar el ciclo completo del documento de transporte electrónico (Electronic Consignment Note) en contextos B2B logísticos. Esta API cubre tanto flujos de empresa cargadora como flujos de transportista, incluyendo operaciones de preparación, ejecución, firma, evidencia documental, seguimiento y cierre.

Propósito del sistema​

Este backend está diseñado para servir como capa transaccional central del ecosistema ECMR. Su objetivo es unificar en un mismo contrato API:

  • Gestión operativa del eCMR y sus estados de negocio.
  • Gestión de actores logísticos (empresa, usuarios, conductores, vehículos).
  • Gestión de datos maestros (direcciones, categorías, perfiles).
  • Gestión de evidencias (firmas, documentos, imágenes, QR, incidencias).
  • Gestión de facturación y capacidades asociadas a billing.

Dominios funcionales cubiertos​

La especificación se organiza por módulos funcionales para facilitar integración incremental:

  • Auth y Apikeys: autenticación por JWT/API Key, onboarding y acceso programático.
  • Users, Profile, Company_data: identidad, permisos operativos y datos empresariales.
  • Addresses, Drivers, Vehicles, Country, Categories: datos de soporte para construir y validar operaciones de transporte.
  • ECMR Core + ECMR Documents + ECMR Pallets + ECMR Sign + ECMR QR: operaciones nucleares del expediente eCMR.
  • Ecmr-templates: reutilización de configuraciones para acelerar creación.
  • Issues y Notifications: soporte operativo y comunicación de eventos.
  • Files e Images: entrega de recursos multimedia/documentales.
  • Billing/Webhooks (según despliegue): procesos de cobro y eventos externos.

Flujo operativo eCMR (alto nivel)​

Los documentos eCMR atraviesan un ciclo de vida principal: planned -> accepted -> collected -> locked -> delivered|claimed|canceled.

Este flujo refleja la transición entre planificación, aceptación, recogida, bloqueo legal/operativo del documento y estado final del servicio. A nivel funcional, varios módulos interactúan sobre este ciclo:

  • Core para crear/editar/bloquear.
  • Sign para registrar firmas de actores.
  • Documents/Images para adjuntar evidencias.
  • QR para consulta/firma/descarga en escenarios móviles.
  • Issues para gestionar excepciones durante la operación.

Modelo de autenticación y acceso​

La API soporta dos mecanismos de autenticación:

  • JWT Bearer token en headers.
  • API Key en query para accesos integrados/automatizados.

Reglas generales:

  • Endpoints de negocio suelen requerir middleware de sesión (isLoged).
  • Si no se envía token ni API key, el backend responde 401 con NO_TOKEN_OR_APIKEY.
  • Según el flujo y el módulo, puede haber validaciones adicionales de contexto de usuario/compañía y permisos por rol.

Contrato de respuesta y errores​

Para mantener consistencia transversal entre módulos, el backend utiliza convenciones uniformes:

  • Éxito (returnOK): objeto con status, data y campo legacy 0.
  • Error (returnKO): objeto con status y message.
  • Códigos HTTP usados para distinguir validación (400), autenticación (401), recursos no encontrados (404), conflicto de negocio (409) y fallo interno (500).

Esta normalización permite a clientes frontend, integraciones y procesos backend consumidores aplicar manejo homogéneo de respuestas.

Capacidades técnicas y de integración​

Capacidades operativas expuestas por la API:

  • Endpoints REST en JSON con estructuras tipificadas en OpenAPI.
  • Paginación, filtrado y ordenación en listados.
  • Validación de payloads y errores de negocio por módulo.
  • Gestión de subida/consulta de archivos y evidencias.
  • Integraciones con servicios externos, incluyendo Stripe (billing) y AWS S3 (almacenamiento de ficheros/imágenes).
  • Instrumentación orientada a operación y observabilidad (según entorno).

Entornos y despliegue​

La especificación contempla servidores de:

  • Producción para operación real.
  • Demo para pruebas funcionales/integración.
  • Localhost para desarrollo y validación interna.

Se recomienda validar siempre diferencias de configuración por entorno (credenciales, servicios externos, flags y catálogos) antes de pasar a producción.

Authentication​

JWT Bearer authentication

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT

License