Guía de API y logística
API de direcciones para logística
Cómo tratar direcciones logísticas como datos compartidos entre TMS, cargas, entregas y documentos.
Respuesta directa
Una API de direcciones ayuda a evitar que cada sistema mantenga una versión incompatible de un origen o destino. La integración debe respetar el esquema documentado, los identificadores y la calidad de los datos; no debe inventar geocodificación ni campos.
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
- altas, lecturas y cambios disponibles para tu cuenta
- uso de direcciones en cargas y entregas
- identificadores y validación de calidad
Flujo recomendado
- 1. Normaliza entradas y detecta duplicados antes de enviar.
- 2. Mapea la dirección al esquema oficial y conserva su referencia.
- 3. Valida permisos y resultado de la operación.
- 4. Reutiliza referencias en cargas y entregas en lugar de copiar datos sin control.
- 5. Programa una reconciliación y un proceso de corrección.
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 direcciones logísticas 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 direcciones logísticas 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.