Guía de API y logística
API de contratos y ofertas de transporte
Cómo diseñar flujos de ofertas, pujas y contratos sin confundir estados comerciales con datos de operación.
Respuesta directa
Los contratos y ofertas requieren un modelo de estados explícito y control de concurrencia. La integración debe confirmar en el OpenAPI qué acciones existen y bajo qué rol; no debe presentar pujas o contratos como acceso público por defecto.
Acceso: esta API se consulta según el acuerdo y las credenciales de la cuenta; no presentamos estos recursos como una funcionalidad pública anónima.
Qué cubre esta integración
- ofertas y pujas si están habilitadas
- contratos y referencias comerciales
- estados, permisos y auditoría
Flujo recomendado
- 1. Identifica actores y acciones permitidas por rol.
- 2. Mapea estados y transiciones antes de programar botones o jobs.
- 3. Envía cambios con referencia de negocio e idempotencia acordada.
- 4. Verifica el estado remoto después de acciones sensibles.
- 5. Conserva auditoría y deriva conflictos a revisión humana.
Consideraciones del contrato de datos
- Usa los nombres, tipos, estados y relaciones definidos en el OpenAPI vigente; no derives campos por intuición.
- Define qué sistema es la fuente de verdad y conserva el identificador remoto para correlacionar lecturas y escrituras.
- Versiona tu adaptador, registra fecha de sincronización y trata las fechas, unidades y estados como datos contractuales.
- Documenta las reglas específicas de contratos y ofertas de transporte y cómo se reconcilian los cambios.
Errores y seguridad
- Distingue autenticación, autorización, validación y errores transitorios; registra el código y el contexto sin secretos.
- Aplica reintentos solo a fallos transitorios y evita duplicados mediante una estrategia idempotente acordada.
- Protege credenciales, limita permisos, cifra el transporte y no expongas respuestas completas en logs.
Límites y supuestos
- La disponibilidad de recursos depende del acceso concedido y del contrato de la cuenta.
- Esta guía no sustituye el OpenAPI: no inventa rutas, payloads, límites ni webhooks no confirmados.
- Prueba primero con datos no productivos y valida el comportamiento con Cargoffer antes de activar sincronizaciones.
Siguiente paso
Revisa el contrato vigente, permisos y operaciones disponibles en la documentación oficial antes de implementar.
Consultar docs.cargoffer.com →Preguntas frecuentes
¿La API de contratos y ofertas de transporte está abierta a cualquier visitante?
No debe asumirse. El acceso depende del acuerdo, la cuenta y las credenciales concedidas; consulta docs.cargoffer.com.
¿Dónde están las rutas y los campos exactos?
En el OpenAPI y la documentación oficial de Cargoffer. Esta guía explica el diseño, no replica payloads.
¿Puedo integrar cualquier TMS?
El patrón es agnóstico del TMS, pero debes comprobar que el acceso y las operaciones necesarias estén disponibles para tu cuenta.
¿Cómo manejo errores?
Clasifica autenticación, permisos, validación y fallos transitorios; registra el código sin secretos y reintenta solo cuando proceda.
¿Qué hago antes de pasar a producción?
Alinea el contrato de datos, prueba casos límite, verifica duplicados y acuerda con Cargoffer el alcance y las credenciales.