Guía de API y logística
API para una bolsa de carga: qué puedes integrar
Qué revisar para conectar una bolsa de carga con tus sistemas de transporte usando la API de Cargoffer.
Respuesta directa
La integración de una bolsa de carga debe separar publicar, consultar y gestionar el ciclo de una oferta. No presupongas que una operación pública o anónima existe: valida permisos, estados y alcance comercial con Cargoffer.
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
- publicación y consulta de cargas según acceso
- ofertas, pujas y contratos cuando estén habilitados
- correlación de estados con el TMS
Flujo recomendado
- 1. Define quién puede publicar, buscar o actuar sobre cada recurso.
- 2. Alinea estados y transiciones con el contrato vigente.
- 3. Implementa búsqueda y lectura con paginación documentada.
- 4. Procesa cambios evitando duplicados y conflictos.
- 5. Audita quién hizo cada operación y cuándo.
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 bolsa de carga 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 bolsa de carga 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.