Estándares de API de DCSA - Haciendo los datos accesibles en la industria naviera global

Implemente ahora las API de DCSA: priorice los puntos finales de reserva, eventos y seguimiento y adopte cargas útiles estandarizadas en 12 semanas para reducir los puntos de contacto manuales en ~40% y entregar actualizaciones casi en tiempo real a cada usuario.

Comience con tres pasos prácticos: mapear las interfaces existentes, exponer una capa de API delgada para sistemas heredados que aún usan EDI y probar las fuentes de posición basadas en satélites para enriquecer los registros de eventos. Este enfoque preserva las operaciones actuales mientras crea un camino sin interrupciones para notificaciones automatizadas y correcciones de ETA.

Mida los resultados para demostrar el valor: rastree el tiempo promedio de confirmación de una reserva, el porcentaje de reducción de hilos de correo electrónico, la frecuencia de las actualizaciones de estado por viaje y la utilización de llamadas a la API por cliente. Estas métricas muestran cómo la transformación está cambiando la adquisición y las operaciones en toda la cadena de suministro y cómo los equipos trabajan juntos para reducir el tiempo de permanencia y el desvío en un barco.

Siga planes claros: ejecute una prueba piloto de tres partes con una naviera, dos expedidores y una terminal; publique reglas de SLA y versionado; proporcione SDK y cargas útiles de ejemplo; y programe puntos de control de integración semanales. Esos pasos concretos producen resultados repetibles hoy y ponen datos estandarizados a disposición de los sistemas posteriores, análisis e integraciones de socios.

Estándares de API de DCSA: Haciendo accesibles los datos en la industria naviera mundial: alineación de las llegadas de buques portacontenedores y despliegue de plataformas para la digitalización

Implemente los estándares de API de DCSA en 12 meses para sincronizar la publicación de ETA de buques, la asignación de muelles y el despliegue de plataformas, reduciendo las transferencias manuales y desbloqueando actualizaciones operativas automáticas.

Exija que las API publiquen actualizaciones de ETA y estado a intervalos de 15 minutos y que admitan webhooks basados en eventos para una comunicación inmediata entre transportistas, terminales y agentes. Integre fuentes AIS y satelitales para capturar la posición y la velocidad a lo largo de la ruta y transferirlas a los sistemas portuarios; estandarice las cargas útiles con marcas de tiempo ISO 8601 y UN/LOCODEs para evitar errores de mapeo durante la transferencia. Planifique tres lanzamientos importantes por año con versionado semántico y ventanas claramente publicadas para la compatibilidad con versiones anteriores para brindar a los usuarios ciclos de actualización predecibles.

Optimice las ventanas de atraque combinando fuentes operativas de los sistemas de operación de terminales y los sistemas de planificación de transportistas; las pruebas piloto con Maersk y socios de terminales muestran una reducción de hasta el 20% en el tiempo de espera de atraque y una mayor tasa de utilización de muelles en comparación con la programación manual. Utilice reglas automáticas de reasignación de muelles y comunicaciones de notificación para reducir los minutos de inactividad de los muelles entre movimientos de buques, mejorando el rendimiento más de lo que pueden lograr los mensajes ad hoc.

Incluya métricas ambientales en cada carga útil de API: consumo de combustible, horas de motores auxiliares y estimaciones de emisiones derivadas de satélites. Ingrese esas métricas capturadas en los tableros de gestión de puertos y transportistas para cuantificar el CO2 por TEU y establecer objetivos medibles para el desarrollo sostenible. Permiten a los operadores comparar las opciones de enrutamiento y atraque en términos de emisiones y costos operativos, lo que permite tomar decisiones estratégicas que ofrecen mejores resultados de sostenibilidad.

Establezca una gobernanza que vincule la conformidad con los estándares a los SLA contractuales, aclare los protocolos de comunicación y asigne la responsabilidad de la calidad de los datos. Promueva kits de herramientas para desarrolladores, entornos sandbox y documentación abierta para acelerar el desarrollo y la incorporación de nuevos usuarios. Monitoree los KPI: precisión de la hora de llegada, tasa de éxito de transferencia automática y reducción de intervenciones manuales, y publique informes trimestrales para que las partes interesadas puedan medir el progreso y planificar una mayor integración.

Plano Operacional: Aplicación de las API de DCSA para Alinear los Datos de Llegada de Buques

Implemente un proceso estandarizado de conciliación del estado de llegada utilizando las API de Eventos, Viajes y Llamadas a Puerto de DCSA con un SLA de 24 horas para alinear las llegadas de buques entre transportistas, puertos y terminales.

Capture los datos de llegada de tres fuentes primarias: manifiestos de transportistas a través de la API de Viajes de DCSA, sistemas de terminales a través de la API de Llamadas a Puerto y fuentes AIS. Utilice webhooks de la API de Eventos para actualizaciones rápidas y recurra a sondeos periódicos a intervalos de 5 minutos cuando los webhooks fallen. Etiquete cada registro con un campo SOURCE (fuente) y capture_timestamp para preservar la procedencia y respaldar los registros de auditoría.

Normalice las cargas útiles entrantes a un único modelo operativo con estos campos canónicos específicos: vessel_imo, voyage_id, eta_utc, ata_utc, berth, status_code, bunker_onboard_mt, estimated_fuel_burn_mt, customs_status y event_origin. Convierta todas las horas a UTC, redondee al minuto más cercano y mapee los códigos de estado dispares a una taxonomía de llegada de 7 estados (planificado, ETA actualizado, en tránsito, llegado, atracado, en muelle, partido).

Utilice reglas de coincidencia deterministas: coincidencia exacta en vessel_imo + voyage_id si está disponible; de lo contrario, coincida con vessel_imo + ventana eta ±72 horas utilizando una función de puntuación que pondera la API de Eventos = 0.5, AIS = 0.3, mensajes de terminal = 0.2. Marque las discrepancias con una puntuación <0.6 para revisión humana. Defina un umbral de discrepancia de 60 minutos para ETA vs ATA; trate las brechas más grandes como excepciones operativas que pueden aumentar el uso de combustible y el tiempo de retención aduanera.

Integre el manejo de excepciones en las interfaces de usuario y las interfaces de máquina simultáneamente. Envíe excepciones de alta severidad a los equipos de operaciones de transportistas a través de notificaciones de API y a los planificadores de terminales a través de paneles de UI. Proporcione a los usuarios acciones correctivas sugeridas: redirigir a un muelle alternativo, solicitar un ajuste inmediato de combustible o preautorizar documentos aduaneros. Registre las decisiones del operador y el tiempo de resolución para análisis posteriores.

Mida el rendimiento con estos KPI y objetivos: discrepancy_rate (<5% dentro de los 6 meses), mean_time_to_align (<4 horas), SLA_adherence (≥98%), bunker_variance (±3% del informado a bordo), y economic_impact_estimate por llegada. Utilice los últimos tres meses como línea de base y ejecute una prueba piloto en octubre en un corredor principal Asia-Europa con 500 llegadas capturadas para validar los ahorros y la precisión del modelo.

Aplique reglas de transformación que reduzcan los eventos duplicados y mejoren la utilización de las interfaces del sistema: elimine duplicados dentro de los 2 minutos de la misma fuente, fusione eventos que comparten el mismo vessel_imo+event_origin+timestamp y almacene las cargas útiles sin procesar para el linaje. Anote los registros con una matriz events_history para que los analistas puedan comprender los patrones de tiempo que llevaron a discrepancias a lo largo del viaje.

Goberne los flujos de datos con contratos de API versionados, tokens OAuth2 por socio, límites de frecuencia ajustados a las operaciones pico (recomendado 1200 llamadas/min para suscripciones de eventos) y políticas de retención (sin procesar durante 12 meses, agregado durante 36 meses). Mantenga un registro de esquemas a nivel de la industria para que los socios puedan alinearse en la semántica de los campos y reducir los esfuerzos de mapeo más allá de la integración inicial.

API de DCSA	Campos clave capturados	Acción	SLA / Objetivo
API de Eventos	event_type, timestamp, location, vessel_imo, voyage_id	Captura en tiempo real, webhook primero, debounce 2 min	Entrega de Webhook <30s; reintentar dos veces
API de Viajes	voyage_id, eta_utc, planned_port_calls, cargo_manifest	Rellenar registro de viaje canónico, marcar discrepancias de manifiesto	Sincronizar cada 4 horas; actualizaciones dentro de 1 hora
API de Llamada a Puerto	port_call_id, berth, alongside_time, berthed_time, customs_status	Alinear estado del lado del puerto, presentar retenciones aduaneras	Actualizar <15 min después del evento local
API de Datos de Referencia	locations, terminals, carrier_codes	Resolver nombres/IDs, reducir errores de mapeo	Actualización semanal; correcciones urgentes dentro de 24h
Ubicación / AIS	lat, lon, sog, cog, timestamp	Complementar ETA/ATA, estimación de consumo de combustible	Latencia de transmisión <60s

Ejecute una prueba piloto de tres meses con estos pasos: implemente integraciones en un corredor principal en octubre, ingiera 500 llegadas pasadas y en vivo para entrenar el modelo de conciliación, itere las reglas para reducir los falsos positivos a <8% y mida el impacto económico mensualmente. Reporte los resultados a los socios aduaneros para acortar las ventanas de despacho y a los equipos de OPS para reducir el tiempo de espera que impulsa el consumo de combustible. Utilice las lecciones de la prueba piloto para expandirse a nivel de la industria y escalar las interfaces para que los usuarios vean llegadas alineadas más allá de los silos locales.

Identifique el conjunto crítico de puntos finales para la alineación de llegadas de buques: API y cargas útiles de DCSA requeridas

Implemente este conjunto mínimo de puntos finales para alinear las llegadas de buques: Llamada a Puerto (viaje/eta), Notificaciones de Eventos (webhook), Transporte/Movimiento, Reserva, Equipo/Contenedor, Interfaz de Terminal, Referencia/Ubicación y API de Partes.

Carga útil de Llamada a Puerto: incluya voyageId, vesselIMO, vesselName, voyageNumber, portCode (UN/LOCODE), scheduledArrival (ISO‑8601), estimatedArrival, scheduledDeparture, berthingWindowStart, berthingWindowEnd, berthCode, draftMeters, nextPortCode y sequenceVersion. Utilice campos numéricos para TEU y calado, y proporcione sourceSystem y lastUpdatedBy. Por ejemplo: scheduledArrival: "2026-03-10T14:00:00Z". Transmita una instantánea completa del viaje en la primera sincronización y delta después.

Carga útil de Notificaciones de Eventos: eventType, eventTimestamp, relatedId (voyageId, containerNumber, bookingReference), locationCode, statusCode, details, sequenceNumber y idempotencyKey. Envíe POSTs formateados como application/vnd.api+json JSON:API a los puntos finales del suscriptor con reintentos/backoff y ventanas exponenciales. Marque los eventos como automáticos o manuales e incluya eventProvenance para identificar el sistema que generó el evento.

Carga útil de Transporte/Movimiento: transportId (GUID), shipmentId, bookingReference, carrierBookingReference, billOfLadingNumber, originUNLOC, destinationUNLOC, mode, containers:[{containerNumber,sizeType,status}], cargoType, weightKg, loadedOnVoyageId y currentStatusTimestamp. Proporcione manifestReference y estimatedOnboardTime cuando estén disponibles para ayudar a la planificación de la terminal.

Carga útil de Reserva: bookingReference, shipperPartyId, consigneePartyId, commodities, totalTEU, containerRequirements, portCutoffTimes:{terminalCutoff,gateCutoff,docsCutoff} con zona horaria, requestedPickupDate y confirmedStatus. Utilice estos valores para impulsar los sistemas de ranura y citas de terminal; almacene bookingVersion para la conciliación.

Carga útil de Equipo/Contenedor: containerNumber, isoSizeType, tareKg, grossKg, currentLocationCode, lastFreeTime, containerStatus y sealInfo. Conecte estos registros a transportId y voyageId para que los sistemas de terminal y los clientes vean una única fuente de verdad.

Carga útil de Interfaz de Terminal: terminalCode, berthCode, availableCraneCount, plannedBerthStart, plannedBerthEnd, gateSlots (ventanas de tiempo), yardOccupancyPercent y serviceLevels. Diseñe el modelo para que las terminales puedan transmitir confirmaciones de muelle y asignaciones de ranuras de vuelta a los dominios de Llamada a Puerto y Reserva.

Cargas útiles de Referencia y Parte: partyId (transportista, terminal, expedidor, consignatario), nombres, roles, contactMethods y locationList. Proporcione UN/LOCODE y términos de rol estandarizados para promover una coincidencia consistente en la constelación de sistemas involucrados en el transporte marítimo.

Reglas de protocolo e implementación: adopte el tipo de contenido JSON:API, requiera marcas de tiempo RFC3339, imponga las claves obligatorias enumeradas anteriormente, admita PATCH para cambios delta y versión de los puntos finales. Utilice webhooks para la entrega automática de eventos y proporcione una API de consulta para la sincronización completa. Guía de límites de velocidad: permita 5 solicitudes/seg por cliente para los puntos finales de sincronización y 1000 eventos de webhook/min con backoff en respuestas 429.

Recomendaciones operativas: transmita actualizaciones de ETA con más frecuencia cuanto más cerca esté un buque: por ejemplo, cada 15 minutos cuando esté a más de 48 horas de distancia, cada 5 minutos dentro de las 6 horas, e inmediatamente al llegar/atracar. Incluya sequenceNumber y lastProcessedEvent en las respuestas para que los sistemas consumidores puedan reanudar sin duplicados y mantener la idempotencia.

Monitoreo y puesta en servicio: exponga métricas para deliverySuccessRate, averageLatencyMs y processingErrors por punto final. Ejecute una lista de verificación de puesta en servicio que incluya validación de esquemas, reintentos de webhook, autenticación (mTLS u OAuth2) y pruebas de extremo a extremo entre los sistemas del transportista, la terminal y el cliente. Asigne un equipo multifuncional para desarrollar y monitorear estos elementos durante el primer sprint.

Guía de mapeo y modelo de datos: mapee los campos locales a nombres canónicos (voyageId, portCode, scheduledArrival) en una capa de integración; conserve los identificadores de origen originales en una matriz sourceRef. Utilice un modelo changeLog que registre quién cambió qué y cuándo para impulsar la conciliación posterior y las notificaciones a los clientes.

Seguridad y gobernanza: requiera ámbitos de tokens por punto final y limite los datos devueltos por rol. Registre el consentimiento y los términos contractuales para compartir datos e incluya entradas de auditTrail para los eventos transmitidos para que los clientes y las terminales puedan verificar la procedencia.

Comience la implementación a partir de una lista de verificación priorizada: 1) Llamada a Puerto y webhooks de Eventos, 2) Sincronización de Transporte y Reserva, 3) Interfaz de Terminal y Equipo, 4) Consolidación de Referencia y Parte, 5) pruebas de monitoreo y puesta en servicio. Este orden reduce el trabajo de integración que los enfoques ad hoc y permite al equipo ofrecer una alineación de llegadas visible para los envíos en cuestión de semanas.

Traducir eventos de llamada a puerto a una línea de tiempo de llegada canónica: reglas de mapeo y precedencia de marcas de tiempo

Aplique un conjunto de cinco pasos de mapeo y precedencia de marcas de tiempo para generar una única línea de tiempo de llegada canónica para cada buque y envío: mapear eventos sin procesar a fases canónicas, seleccionar la marca de tiempo de mayor prioridad para cada fase, adjuntar la confianza de la fuente y marcar los conflictos para la revisión humana.

Defina las fases canónicas como: aproximación (buque a menos de 24 NM del puerto), pilotOnBoard, alongside/berth, startCargoOps (recepción del primer movimiento de contenedor), completeCargoOps y departed. Mapee los eventos de origen en estas fases: informes de posición AIS, manifiestos de autoridad portuaria/piloto, eventos de atraque del sistema operativo de terminal (TOS), mensajes operativos del transportista (SOC/COC), escaneos de entrada/salida de puerta de contenedor y entradas del diario de navegación del buque. Almacene una marca de tiempo canónica por fase y mantenga las listas de eventos originales para auditoría y conciliación.

Precedencia de marca de tiempo (de mayor a menor): 1 – Marcas de tiempo de la autoridad portuaria / piloto para autorizaciones de pilotOnBoard y atraque (autoritativas). 2 – Marcas de tiempo del sistema operativo de terminal para alongside/berth y startCargoOps. 3 – Escaneos de puerta de terminal/contenedor para recepción y movimientos de contenedores. 4 – Mensajes operativos del transportista (ETA/ATA, SOC/COC) para hitos planificados y confirmados por el operador. 5 – Marcas de tiempo derivadas de AIS (posición cruzando X-NM, detenido en el muelle) para detección automática. Normalice siempre a UTC ISO 8601 y adjunte el identificador de la fuente y la puntuación de confianza.

Resuelva conflictos con reglas deterministas: si existe una marca de tiempo de mayor prioridad, utilícela para la fase canónica. Si los datos de menor prioridad preceden a una marca de tiempo de mayor prioridad en más de un umbral T1 = 30 minutos para atraque/alongside o T2 = 120 minutos para aproximación/ETA, conserve ambas marcas de tiempo, marque la fase canónica como "sospechosa" y establezca sourceConfidence = baja. Si el AIS indica alongside antes que el TOS por <30 minutos, prefiera el TOS pero registre el AIS como evidencia de respaldo. Para datos faltantes de mayor prioridad, promueva la siguiente fuente disponible pero registre un promotionReason y expectedAccuracy (%) según el tipo de fuente.

Implemente controles de reloj y zona horaria: exija a todas las fuentes que envíen marcas de tiempo en UTC. Para desfases de reloj conocidos, aplique compensaciones específicas de la fuente calculadas a partir de comparaciones históricas (almacene last-offset y stdev). Rechace marcas de tiempo de más de 7 días para las fases de llegada, a menos que vayan acompañadas de un registro firmado de la autoridad portuaria. Aplique una corrección máxima de 60 minutos automáticamente; las correcciones más grandes requieren revisión manual.

Esquema de eventos canónicos recomendado (campos de ejemplo): eventType, canonicalTimestampUTC, sourceType, sourceId, sourceConfidence(0-1), rawTimestamps[listas], berthId, portUNLocode, vesselIMO, containerCount, affectedContainers[], phaseDurationMinutes. Utilice estos campos para generar resultados de KPI como la reducción de la varianza de ETA, notificaciones más tempranas a los clientes y una reducción medible del tiempo de movimiento por contenedor.

Guía operativa para adoptantes y alianzas: integre estas reglas en las API de transportistas y terminales para permitir mensajes consistentes a través de puntos finales alineados con DCSA. Comparta las reglas promovidas con expedidores y clientes para que los sistemas puedan expandir los flujos de trabajo automatizados y optimizar la planificación de muelles. Rastrear cinco métricas de adopción: porcentaje de fases con fuente autoritativa, frecuencia promedio de promoción, porcentaje de indicadores sospechosos resueltos dentro de las 24 horas, desviación media entre la ETA canónica y la del transportista, y reducción de notificaciones tempranas/tardías. La digitalización de estos mapeos aumentará la visibilidad en todas las industrias, ayudará a optimizar los movimientos de contenedores y moverá a la industria más allá de las marcas de tiempo fragmentadas para que los transportistas, terminales y expedidores reciban información de envío más temprana y confiable junto con los recibos y resultados a nivel de contenedor.

Validar identificadores de transportista y contenedor antes de la ingesta: dígitos de control, listas de códigos y manejo de rechazos

Valide los números de contenedor y los códigos de transportista en la puerta de enlace de la API utilizando la lógica de dígito de control ISO 6346 y las listas de códigos autoritativas antes de cualquier ingesta posterior.

• Formato exacto del contenedor y verificación del dígito de control

  • Acepte solo entradas ISO 6346 de 11 caracteres: código de propietario (3 letras) + categoría de equipo (1 letra, típicamente U/J/Z) + serie (6 dígitos) + dígito de control (1 dígito).
  • Calcule el dígito de control: mapee las letras a valores numéricos (A=10, B=12, C=13 ... Z=38 con saltos en 11, 22, 33), multiplique el valor de cada carácter por 2^posición (posición 0 para el primer carácter), sume, tome la suma mod 11; si el resto = 10, establezca el dígito de control = 0. Rechace inmediatamente ante una discrepancia.
  • Rechace entradas con longitud incorrecta, letras no ASCII, ceros iniciales en el código de propietario o series fuera de 000001–999999; registre el motivo exacto de la falla y la fuente (ID de llamada a la API o fila de hoja de cálculo).

• Validación de códigos de transportista y gestión de listas de códigos

  • Compare los identificadores de transportista con un registro autoritativo (BIC para propietarios, SCAC para operaciones de EE. UU. o su lista de transportistas acordada). Trate los códigos desconocidos como en cuarentena hasta que se resuelvan.
  • Implemente búsquedas en tiempo real cuando el acceso a Internet esté disponible; recurra a una instantánea en caché firmada y con marca de tiempo si está fuera de línea. Permita la validez en caché durante una ventana configurable (por defecto 24–72 horas) y registre la versión de la instantánea en cada evento.
  • Aplique mapeo para alianzas y socios operativos de buques: mantenga una tabla canónica de transportista a transportista operativo utilizada por APMS y sistemas posteriores; actualice el mapeo en cada cambio de alianza y capture quién aplicó la anulación.

• Verificaciones previas a la ingesta para hojas de cálculo y cargas masivas

  • Proporcione un validador del lado del cliente (macro de Excel o JS ligero) que marque las filas antes de la carga y devuelva un CSV de las filas rechazadas con códigos de error; esto reduce las correcciones manuales y acelera la digitalización de hojas de cálculo heredadas.
  • Para la ingesta masiva, ejecute un escaneo previo rápido que segregue las filas válidas, de fallo suave (transportista desconocido) y de fallo duro (discrepancia de dígito de control). Ingiesta solo las filas válidas; devuelva un archivo de rechazo estructurado que el remitente pueda volver a cargar después de las correcciones.

• Política de manejo de rechazos y taxonomía de errores

  1. Utilice códigos de error estandarizados para que las integraciones puedan actuar automáticamente:
     • ERR01 – FORMAT_INVALID (longitud/conjunto de caracteres)
     • ERR02 – CHECKDIGIT_MISMATCH
     • ERR03 – CARRIER_UNKNOWN
     • ERR04 – MAPPING_OVERRIDE_REQUIRED
  2. Defina acciones automáticas por código:
     • ERR02: rechazo duro, notificar al remitente, bloquear hasta que se corrija.
     • ERR03: cuarentena suave, intente buscar en servicios alternativos hasta por 24 horas, luego escale a operaciones del transportista si aún no se resuelve.
     • ERR04: acepte solo con anulación firmada por un usuario autorizado; registre el rastro de auditoría.

• Monitoreo, KPI y SLA

  • Rastree la tasa de rechazo, el tiempo medio de remediación (MTTR) y la fracción de registros en cuarentena resueltos dentro del SLA. Objetivos objetivo: tasa de rechazo <0.1% del volumen de ingesta y MTTR <4 horas para puertos/llegadas operativas.
  • Instrumente tableros que muestren tendencias y detección de picos para que las operaciones detecten cambios en las listas de transportistas o errores masivos en hojas de cálculo más rápido de lo que puede realizar una revisión manual.

• Puntos de integración y salvaguardias operativas

  • Valide antes de enviar datos a los sistemas de aduanas, APMS, combustible y bunkering. Las identificaciones incorrectas causan discrepancias en la facturación (combustible), retrasos aduaneros y llegadas mal dirigidas.
  • Cuando un sistema externo (APMS, sistema de terminal) envía actualizaciones, adjunte la versión de la instantánea de validación para que los receptores sepan qué lista de códigos produjo la decisión.
  • Utilice enlaces seguros por Internet o satelitales de banda L donde la conectividad en tierra no sea confiable; la validación sin conexión aún debe registrar el ID de la lista en caché hasta que se complete la sincronización de Internet.

• Gobernanza, actualizaciones y prácticas de desarrollo

  • Automatice las extracciones nocturnas de listas de códigos y permita la ejecución manual para cambios inmediatos; registre quién realizó las actualizaciones manuales y por qué. Notifique a los equipos posteriores de cualquier cambio que afecte las asignaciones o especificaciones del transportista.
  • Incluya pruebas unitarias para la lógica de dígitos de control en CI/CD y un repositorio de vectores de prueba del mundo real (números válidos e inválidos) utilizados durante el desarrollo y las pruebas de calidad.
  • Mantenga un registro de cambios público para que los socios sepan cuándo cambiaron sus reglas o listas de validación; vincule el ID del registro de cambios en los metadatos del evento para la trazabilidad (consulte el mapeo aquí para las últimas 30 actualizaciones).

• Ejemplos operativos

  • Escenario: una carga de hoja de cálculo de un agente envía actualmente 5000 filas. Ejecute un escaneo previo: 4990 válidas, 8 ERR02, 2 ERR03. Devuelva un CSV de rechazo con ID de fila, códigos de error y correcciones sugeridas; ingiera las 4990 inmediatamente para cumplir con los plazos de llegada.
  • Escenario: una alianza de transportistas cambia prefijos durante la noche. Aplique la anulación de mapeo, ejecute la conciliación con las llegadas capturadas de las últimas 48 horas y envíe un feed corregido a los sistemas de aduanas y eBOL para evitar discrepancias posteriores.

• Lista de verificación práctica para implementar hoy

  1. Implemente la validación de dígitos de control en el borde de la API.
  2. Integre un registro de códigos autoritativo con modos en tiempo real y en caché.
  3. Cree plantillas CSV de rechazo para usuarios de hojas de cálculo y automatice el escaneo previo en la UI de carga.
  4. Establezca alertas de KPI para picos de rechazo y conserve rastros de auditoría para todas las actualizaciones manuales de listas.

Seguir estos pasos reduce los falsos positivos, acelera el procesamiento de llegadas, alinea los datos con los flujos de aduanas y APMS, mejora la precisión del combustible/facturación y permite que sus equipos logren una ingesta consistente y auditable al tiempo que acomoda los cambios operativos reales y las asignaciones impulsadas por alianzas.

Autenticar y conectarse a los servicios de DCSA: flujos OAuth, claves API y pasos de sandbox a producción

Utilice credenciales de cliente de OAuth 2.0 para integraciones de máquina a máquina y Código de Autorización con PKCE para cualquier aplicación que actúe en nombre de un usuario; almacene secretos de cliente en un administrador de secretos y restrinja los ámbitos al mínimo requerido.

Exija TLS 1.2+ para todas las llamadas a través de Internet, valide certificados y aplique el anclaje TLS para aplicaciones móviles. Para clientes públicos, implemente PKCE y tokens de acceso de corta duración con tokens de actualización rotados en el primer uso; para clientes confidenciales, prefiera mTLS si el proveedor lo admite.

Registre cada aplicación en el portal de desarrolladores de DCSA con un client_id único y un secreto o clave específicos del entorno. Utilice credenciales de sandbox para desarrollo y pruebas, etiquete las pruebas que tocan ebls o flujos aduaneros, y documente qué versiones de API llama su integración para obtener claridad sobre los cambios disruptivos.

Cuando reciba tokens de sandbox, automatice el almacenamiento en caché y la renovación de tokens: solicite un nuevo token al 90% de la vida útil del token, reintente los intercambios de tokens fallidos con backoff exponencial y registre los errores de token en un flujo de auditoría seguro en lugar de imprimir secretos en la consola. Un proxy local inteligente que inyecta tokens y aplica límites de velocidad reduce la fricción de desarrollo.

Utilice claves API solo para telemetría de bajo riesgo o identificación de socios donde OAuth no esté disponible; nunca utilice claves API como sustituto de la autenticación de usuario. Trate las claves API como secretos, rótelos trimestralmente y bloquee las claves que muestren patrones de llamadas anómalos.

Siga esta lista de verificación de sandbox a producción: 1) complete el contrato y la incorporación de DCSA, 2) pase las pruebas de seguridad y conformidad de API en sandbox, 3) proporcione un contacto de soporte de producción y SLA, 4) presente registros de auditoría y un plan de reversión manual, 5) envíe los certificados mTLS si se requieren, y 6) programe una ventana de corte de producción con transportistas y socios. Si un transportista como hapag-lloyd o una puerta de enlace aduanera requiere una ventana de implementación en octubre, coordine con anticipación y confirme quién envía los recibos de confirmación finales.

Instrumente cada llamada de producción con IDs de correlación, rastree los tiempos de solicitud/respuesta y capture el estado HTTP y los recibos a nivel de negocio para flujos equivalentes a EDI, como ebls y confirmaciones de reserva. Etiquete los eventos por socio, expedidores, transportista y lugar operativo para que los equipos posteriores puedan filtrar por requisitos de aduanas, informes ambientales o seguimiento de combustible.

Mantenga los pasos manuales de migración al mínimo: automatice la carga de certificados, el registro de clientes y las aprobaciones de ámbitos cuando sea posible, y mantenga una lista de verificación que muestre qué socios están conectados y cuáles aún requieren incorporación manual. Una única prueba de humo automatizada que consulta una reserva y valida un recibo rastreado reduce el riesgo de corte.

Durante el desarrollo, emule el comportamiento del socio: cree un stub que envíe cargas útiles de webhook realistas y valide sus acuses de recibo, incluidos los mensajes de aceptación y recibo de ebls. Ejecute pruebas de carga contra el sandbox que simulen el tráfico operativo pico de transportistas, expedidores y puertas de enlace aduaneras para que pueda ajustar los reintentos y la concurrencia.

Monitoree el uso y los KPI de negocio después de la puesta en producción: rastree las tasas de intercambio de tokens, las llamadas de autenticación fallidas, la latencia promedio de las llamadas y el número de recibos no entregados a los socios. Utilice esas métricas para priorizar las correcciones que afectan directamente a los expedidores, transportistas e industrias que dependen de actualizaciones EDI/EBL oportunas e informes ambientales o de combustible.