Guía de API y logística

Cómo publicar una carga por API

Diseña un flujo seguro para publicar cargas desde un TMS o ERP en Cargoffer.

Respuesta directa

Publicar una carga por API significa transformar una orden interna en el recurso que el OpenAPI admite y verificar su resultado. Los campos obligatorios, rutas y estados deben leerse de la documentación y del acceso de tu cuenta, no de ejemplos inventados.

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

  • datos de origen y destino
  • ventanas, requisitos y referencias que el contrato soporte
  • seguimiento del identificador y estado remoto

Flujo recomendado

  1. 1. Valida internamente que la carga está completa y autorizada.
  2. 2. Construye el mapeo contra el esquema exacto documentado.
  3. 3. Envía la operación con credenciales de escritura protegidas.
  4. 4. Guarda la referencia remota y evita republicar por reintentos.
  5. 5. Reconcilia el estado y deriva incidencias al equipo operativo.

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 publicación de cargas 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 publicación de cargas 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.