DCSA 글로벌 해운 데이터 액세스를 위한 API 표준

DCSA API 표준: 글로벌 해운 산업에서 데이터 접근성 향상

지금 DCSA API를 구현하십시오: 예약, 이벤트 및 추적 엔드포인트를 우선적으로 적용하고 12주 이내에 표준화된 페이로드를 채택하여 수동 작업량을 약 40% 줄이고 사용자에게 실시간에 가까운 업데이트를 제공하십시오.

세 가지 실용적인 단계부터 시작하십시오. 기존 인터페이스를 매핑하고, EDI를 여전히 사용하는 레거시 시스템을 위한 얇은 API 계층을 노출하며, 이벤트 기록을 풍부하게 하기 위해 위성 기반 위치 피드를 시범 실행하십시오. 이 접근 방식은 현재 운영을 보존하면서 자동화된 알림 및 ETA 수정을 위한 원활한 경로를 만듭니다.

결과를 측정하여 가치를 증명하십시오. 예약의 평균 확인 시간, 이메일 스레드 감소율, 항해당 상태 업데이트 빈도, 고객당 API 호출 활용률을 추적하십시오. 이러한 지표는 변환이 공급망 전체에서 조달 및 운영을 어떻게 변환하고 있으며, 팀이 어떻게 협력하여 선박 체류 및 잘못된 라우팅을 줄이는지 보여줍니다.

명확한 계획을 따르십시오. 한 운송업체, 두 명의 선적업체 및 한 개의 터미널과 함께 3부 파일럿을 실행하십시오. SLA 및 버전 규칙을 게시하십시오. SDK 및 샘플 페이로드를 제공하십시오. 그리고 주간 통합 체크포인트를 예약하십시오. 이러한 구체적인 단계는 오늘날 반복 가능한 결과를 생성하고 다운스트림 시스템, 분석 및 파트너 통합을 위해 표준화된 데이터를 사용할 수 있도록 합니다.

DCSA API 표준: 글로벌 해운에서 데이터 접근성 향상 – 컨테이너 선박 도착 및 플랫폼 배포를 디지털화를 위해 조정

12개월 이내에 DCSA API 표준을 구현하여 선박 ETA 게시, 정박 할당 및 플랫폼 배포를 동기화하고 수동 인계를 줄이며 자동 운영 업데이트를 잠금 해제하십시오.

ETA 및 상태 업데이트를 15분 간격으로 게시하고 운송업체, 터미널 및 대리점 간의 즉각적인 통신을 위한 이벤트 기반 웹훅을 지원하도록 API를 요구하십시오. AIS 및 위성 피드를 통합하여 경로를 따라 위치 및 속도를 캡처하고 항구 시스템으로 전송하십시오. 전송 중 매핑 오류를 피하기 위해 ISO 8601 타임스탬프 및 UN/LOCODE로 페이로드를 표준화하십시오. 의미론적 버전 관리를 통해 연간 3번의 주요 릴리스를 계획하고, 사용자가 예측 가능한 업그레이드 주기를 제공하기 위해 이전 호환성을 위한 명확하게 게시된 창을 제공하십시오.

터미널 운영 시스템 및 운송업체 계획 시스템의 운영 피드를 결합하여 정박 창을 최적화하십시오. Maersk 및 터미널 파트너와의 파일럿은 정박 대기 시간을 최대 20%까지 줄이고 수동 일정에 비해 정박 활용률을 높였습니다. 자동 정박 재할당 규칙 및 알림 통신을 사용하여 선박 이동 간의 정박 유휴 시간을 줄여 임시 메시징보다 처리량을 향상시키십시오.

모든 API 페이로드에 환경 지표를 포함하십시오. 연료 소비, 보조 엔진 시간 및 위성에서 파생 된 배출량 추정치. 이러한 캡처 된 지표를 항구 및 운송업체 관리 대시보드에 공급하여 TEU당 CO2를 정량화하고 지속 가능한 개발을 위한 측정 가능한 목표를 설정하십시오. 이를 통해 운영자는 배출량 및 운영 비용 측면에서 라우팅 및 정박 선택을 비교할 수 있으므로 더 나은 지속 가능성 결과를 제공하는 전략적 선택을 할 수 있습니다.

표준 준수를 계약 SLA에 연결하고, 통신 프로토콜을 명확히 하며, 데이터 품질 책임을 할당하는 거버넌스를 수립하십시오. 개발자 툴킷, 샌드박스 환경 및 개방형 문서를 홍보하여 개발 및 신규 사용자 온보딩을 가속화하십시오. KPI – 도착 시간 정확도, 자동 전송 성공률, 수동 개입 감소 –를 모니터링하고 분기별 보고서를 게시하여 이해 관계자가 진행 상황을 측정하고 추가 통합을 계획할 수 있도록 하십시오.

운영 청사진: 선박 도착 데이터를 조정하기 위한 DCSA API 적용

DCSA 이벤트, 항해 및 항만 통화 API를 24시간 SLA와 함께 사용하여 표준화된 도착 상태 조정 프로세스를 구현하여 운송업체, 항구 및 터미널 간의 선박 도착을 조정하십시오.

세 가지 주요 소스에서 도착 데이터를 캡처하십시오. DCSA 항해 API를 통한 운송업체 명세서, 항만 통화 API를 통한 터미널 시스템, AIS 피드. 이벤트 API 웹훅을 사용하여 신속하게 업데이트하고 웹훅이 실패할 경우 5분 간격으로 주기적인 폴링으로 대체하십시오. 출처 및 캡처 타임스탬프를 각 레코드에 태그하여 출처를 보존하고 감사 추적을 지원하십시오.

다음 특정 표준 필드를 사용하여 수신 페이로드를 단일 운영 모델로 정규화하십시오. vessel_imo, voyage_id, eta_utc, ata_utc, berth, status_code, bunker_onboard_mt, estimated_fuel_burn_mt, customs_status, event_origin. 모든 시간을 UTC로 변환하고 가장 가까운 분으로 반올림하며, 전송 중 매핑 오류를 피하기 위해 다양한 상태 코드를 7단계 도착 분류(계획됨, ETA 업데이트됨, 항해 중, 도착함, 접안함, 정박함, 출발함)로 매핑합니다.

결정론적 매칭 규칙 사용: vessel_imo + voyage_id가 사용 가능한 경우 정확히 일치합니다. 그렇지 않으면 이벤트 API = 0.5, AIS = 0.3, 터미널 메시지 = 0.2의 가중치를 갖는 점수 함수를 사용하여 vessel_imo + eta 창 ±72시간으로 일치합니다. 점수 <0.6인 불일치를 사람 검토를 위해 불일치로 표시합니다. ETA 대 ATA의 경우 60분 불일치 임계값으로 처리합니다. 더 큰 격차는 연료 사용량 및 세관 보류 시간을 증가시킬 수 있는 운영 예외로 처리합니다.

사용자 인터페이스 및 기계 인터페이스 모두에 예외 처리를 통합하십시오. 고심각도 예외를 API 알림을 통해 운송업체 운영 팀에, UI 대시보드를 통해 터미널 계획가에게 푸시하십시오. 사용자에게 제안된 수정 조치를 제공하십시오. 대체 정박지로 재라우팅, 즉각적인 벙커 조정 요청 또는 세관 서류 사전 통관. 운영자의 결정 및 해결 시간 기록을 나중에 분석할 수 있습니다.

다음 KPI 및 목표로 성능을 측정하십시오. discrepancy_rate (<6개월 이내 5%), mean_time_to_align (<4시간), SLA_adherence (≥98%), bunker_variance (보고된 선내의 ±3%), arrival당 economic_impact_estimate. 지난 3개월을 기준으로 삼고, 500개의 캡처된 도착으로 선도적인 아시아-유럽 항로에 대한 10월 파일럿을 실행하여 절감액 및 모델 정확도를 검증하십시오.

중복 이벤트를 줄이고 시스템 인터페이스 활용도를 향상시키는 변환 규칙 적용: 동일한 출처에서 2분 이내의 중복 제거, 동일한 vessel_imo+event_origin+timestamp를 공유하는 이벤트 병합, 계보를 위해 원시 페이로드를 저장합니다. 분석가가 항해 중 불일치를 초래한 타이밍 패턴을 이해할 수 있도록 events_history 배열로 레코드를 주석 처리합니다.

버전 관리된 API 계약, 파트너당 OAuth2 토큰, 피크 운영에 맞춰 조정된 속도 제한(이벤트 구독에 권장 1,200 호출/분) 및 보존 정책(원시 12개월, 집계 36개월)으로 데이터 흐름을 관리합니다. 파트너가 필드 의미론에 동의하고 초기 통합 이상의 매핑 노력을 줄일 수 있도록 업계 전체 스키마 레지스트리를 유지합니다.

DCSA API	핵심 캡처 필드	작업	SLA / 목표
이벤트 API	event_type, timestamp, location, vessel_imo, voyage_id	실시간 캡처, 웹훅 우선, 디바운스 2분	웹훅 전달 <30초; 2회 재시도
항해 API	voyage_id, eta_utc, planned_port_calls, cargo_manifest	표준 항해 레코드 채우기, 명세서 불일치 플래그 지정	4시간마다 동기화; 1시간 이내 업데이트
항만 통화 API	port_call_id, berth, alongside_time, berthed_time, customs_status	항만 측 상태 조정, 세관 보류 표면화	지역 이벤트 후 15분 이내 업데이트
참조 데이터 API	locations, terminals, carrier_codes	이름/ID 확인, 매핑 오류 줄이기	주간 새로 고침; 24시간 이내 핫픽스
위치 / AIS	lat, lon, sog, cog, timestamp	ETA/ATA, 연료 소모량 추정치 보충	스트림 지연 <60초

3개월 파일럿 실행: 10월에 선도적인 항로에 통합 배포, 500개의 과거 및 실시간 도착 수집하여 조정 모델 학습, 잘못된 양성 반응 <8%로 줄이기 위해 규칙 반복, 경제적 영향 매월 측정. 세관 파트너에게 결과 보고하여 통관 기간 단축, OPS 팀에 벙커 소비를 유발하는 대기 시간 줄이기. 파일럿의 교훈을 사용하여 업계 전반으로 확장하고 인터페이스를 확장하여 사용자가 지역 사일로를 넘어 조정된 도착 데이터를 볼 수 있도록 함.

선박 도착 정렬을 위한 중요 엔드포인트 세트 식별: 필수 DCSA API 및 페이로드

선박 도착을 정렬하기 위해 이 최소 엔드포인트 세트를 구현하십시오. 항만 통화(항해/eta), 이벤트 알림(웹훅), 운송/이동, 예약, 장비/컨테이너, 터미널 인터페이스, 참조/위치 및 당사자 API.

항만 통화 페이로드: voyageId, vesselIMO, vesselName, voyageNumber, portCode (UN/LOCODE), scheduledArrival (ISO‑8601), estimatedArrival, scheduledDeparture, berthingWindowStart, berthingWindowEnd, berthCode, draftMeters, nextPortCode, sequenceVersion 포함. TEU 및 흘수에 대해 숫자 필드를 사용하고 sourceSystem 및 lastUpdatedBy를 제공하십시오. 예: scheduledArrival: "2026-03-10T14:00:00Z". 첫 동기화 시 전체 항해 스냅샷 전송, 이후 델타 전송.

이벤트 알림 페이로드: eventType, eventTimestamp, relatedId (voyageId, containerNumber, bookingReference), locationCode, statusCode, details, sequenceNumber, idempotencyKey. 가입자 엔드포인트에 재시도/백오프 및 지수 창이 있는 application/vnd.api+json JSON:API 형식 POST 전송. 이벤트를 자동 또는 수동으로 표시하고 이벤트 출처를 생성한 시스템을 식별하기 위해 eventProvenance 포함.

운송/이동 페이로드: transportId (GUID), shipmentId, bookingReference, carrierBookingReference, billOfLadingNumber, originUNLOC, destinationUNLOC, mode, containers:[{containerNumber,sizeType,status}], cargoType, weightKg, loadedOnVoyageId, currentStatusTimestamp. 터미널 계획에 도움이 되도록 사용 가능한 경우 manifestReference 및 estimatedOnboardTime 제공.

예약 페이로드: bookingReference, shipperPartyId, consigneePartyId, commodities, totalTEU, containerRequirements, portCutoffTimes:{terminalCutoff,gateCutoff,docsCutoff} (시간대 포함), requestedPickupDate, confirmedStatus. 이러한 값을 사용하여 터미널 슬롯팅 및 약속 시스템을 구동하십시오. 조정용 bookingVersion 저장.

장비/컨테이너 페이로드: containerNumber, isoSizeType, tareKg, grossKg, currentLocationCode, lastFreeTime, containerStatus, sealInfo. 이러한 레코드를 transportId 및 voyageId에 연결하여 터미널 시스템과 고객이 단일 진실 공급원을 보도록 합니다.

터미널 인터페이스 페이로드: terminalCode, berthCode, availableCraneCount, plannedBerthStart, plannedBerthEnd, gateSlots (타임스탬프 창), yardOccupancyPercent, serviceLevels. 터미널이 정박 확인 및 슬롯 할당을 항만 통화 및 예약 도메인으로 다시 전송할 수 있도록 모델을 설계하십시오.

참조 및 당사자 페이로드: partyId (운송업체, 터미널, 선적업체, 수하인), 이름, 역할, 연락처 방법, locationList. UN/LOCODE 및 표준화된 역할 용어를 공급하여 해운에 관련된 시스템 구성 요소 전체에서 일관된 매칭을 촉진합니다.

프로토콜 및 구현 규칙: JSON:API 콘텐츠 유형 채택, RFC3339 타임스탬프 요구, 위에 나열된 필수 키 강제 적용, 델타 변경에 PATCH 지원, 엔드포인트 버전 관리. 자동 이벤트 전달을 위해 웹훅 사용 및 전체 동기화를 위한 풀 API 제공. 속도 제한 지침: 동기화 엔드포인트당 클라이언트당 5 요청/초 및 429 응답 시 백오프가 있는 1,000개의 웹훅 이벤트/분 허용.

운영 권장 사항: 선박이 가까워질수록 ETA 업데이트를 더 자주 전송하십시오. 예를 들어, 48시간 이상 떨어진 경우 15분마다, 6시간 이내에는 5분마다, 실제 도착/정박 시 즉시 전송합니다. 수신 시스템이 중복 없이 재개하고 멱등성을 유지할 수 있도록 sequenceNumber 및 lastProcessedEvent를 응답에 포함합니다.

모니터링 및 위임: 엔드포인트별 deliverySuccessRate, averageLatencyMs, processingErrors에 대한 지표 노출. 스키마 유효성 검사, 웹훅 재시도, 인증(mTLS 또는 OAuth2), 운송업체, 터미널 및 고객 시스템 간의 엔드투엔드 테스트를 포함하는 위임 체크리스트 실행. 첫 번째 스프린트 동안 이러한 항목을 개발하고 모니터링할 교차 기능 팀 할당.

매핑 및 데이터 모델 지침: 통합 계층에서 로컬 필드를 표준 이름(voyageId, portCode, scheduledArrival)에 매핑합니다. sourceRef 배열에 원본 출처 식별자 저장. 다운스트림 조정 및 고객 알림을 구동하기 위해 누가 무엇을 언제 변경했는지 기록하는 changeLog 모델 사용.

보안 및 거버넌스: 엔드포인트별 토큰 범위 요구 및 역할별 반환 데이터 제한. 데이터 공유에 대한 동의 및 계약 조건 기록 및 감사 추적 항목을 전송된 이벤트에 포함하여 고객과 터미널이 출처를 확인할 수 있도록 합니다.

우선 순위가 지정된 체크리스트부터 구현 시작: 1) 항만 통화 및 이벤트 웹훅, 2) 운송 및 예약 동기화, 3) 터미널 인터페이스 및 장비, 4) 참조 및 당사자 통합, 5) 모니터링 및 위임 테스트. 이 순서는 임시 접근 방식보다 통합 작업을 줄이고 팀이 몇 주 내에 가시적인 도착 조정을 제공할 수 있도록 합니다.

항만 통화 이벤트를 표준 도착 타임라인으로 변환: 매핑 규칙 및 타임스탬프 우선 순위

각 선박 및 선적에 대한 단일 표준 도착 타임라인을 생성하기 위해 5단계 매핑 및 타임스탬프 우선 순위 규칙 집합을 적용하십시오. 원시 이벤트를 표준 단계로 매핑하고, 각 단계에 대한 가장 높은 우선 순위 타임스탬프를 선택하고, 출처 신뢰도를 첨부하고, 인간 검토를 위해 충돌을 플래그 지정하십시오.

표준 단계 정의: 접근(항구에서 24 NM 이내의 선박), pilotOnBoard, alongside/berth, startCargoOps(첫 컨테이너 이동 수신), completeCargoOps, departed. 스테이지 매핑 소스 이벤트: AIS 위치 보고서, 파일럿/항만 당국 명세서, 터미널 운영 시스템(TOS) 정박 이벤트, 운송업체 운영 메시지(SOC/COC), 게이트인/게이트아웃 컨테이너 스캔, 선박 로그북 항목. 단계당 하나의 표준 타임스탬프 저장 및 감사 및 조정을 위해 원래 이벤트 목록 유지.

타임스탬프 우선 순위(높음에서 낮음): 1 – pilotOnBoard 및 정박 승인을 위한 항만 당국/파일럿 타임스탬프(권위 있는). 2 – alongside/berth 및 startCargoOps를 위한 터미널 운영 시스템 타임스탬프. 3 – 수신 및 컨테이너 이동을 위한 터미널/컨테이너 게이트 스캔. 4 – 예정 및 운영자 확인 마일스톤에 대한 운송업체 운영 메시지(ETA/ATA, SOC/COC). 5 – 자동 감지를 위한 AIS 기반 타임스탬프(X-NM 교차 위치, 정박지에 정지). 항상 UTC ISO 8601로 정규화하고 출처 식별자 및 신뢰도 점수 첨부.

결정론적 규칙으로 충돌 해결: 더 높은 우선 순위 타임스탬프가 있으면 해당 단계를 위해 사용합니다. 낮은 우선 순위 데이터가 임계값 T1 = 30분(정박/접안) 또는 T2 = 120분(접근/ETA)을 초과하여 높은 우선 순위 타임스탬프보다 앞에 오는 경우 두 타임스탬프 모두를 유지하고, 표준 단계를 "의심스러움"으로 표시하고, sourceConfidence = 낮음으로 설정합니다. AIS가 TOS보다 30분 미만으로 먼저 접안을 나타내는 경우 TOS를 선호하지만 AIS를 지원 증거로 기록합니다. 높은 우선 순위 데이터가 누락된 경우 다음 사용 가능한 소스를 승격하지만, 소스 유형에 따라 promotionReason 및 expectedAccuracy(%)를 기록합니다.

시계 및 시간대 제어 구현: 모든 소스가 UTC로 타임스탬프 제출하도록 요구합니다. 알려진 시계 편차의 경우, 과거 비교에서 계산된 소스별 오프셋 적용(last-offset 및 stdev 저장). 도착 단계에 대한 7일보다 오래된 타임스탬프는 서명된 항만 당국 기록과 함께 제공되지 않는 한 거부합니다. 최대 60분의 보정을 자동으로 적용합니다. 더 큰 보정은 수동 검토가 필요합니다.

권장 표준 이벤트 스키마(예시 필드): eventType, canonicalTimestampUTC, sourceType, sourceId, sourceConfidence(0-1), rawTimestamps[목록], berthId, portUNLocode, vesselIMO, containerCount, affectedContainers[], phaseDurationMinutes. 이러한 필드를 사용하여 ETA 편차 감소, 조기 고객 알림, 컨테이너당 측정 가능한 이동 시간 감소와 같은 KPI 결과를 생성합니다.

채택자 및 얼라이언스에 대한 운영 지침: 운송업체 및 터미널 API에 이러한 규칙을 통합하여 DCSA와 정렬된 엔드포인트를 통해 일관된 메시지를 전달합니다. 시스템이 자동화된 워크플로우를 확장하고 정박 계획을 최적화할 수 있도록 규칙을 선적업체 및 고객과 공유합니다. 5가지 채택 지표 추적: 권위 있는 출처가 있는 단계의 비율, 평균 승격 빈도, 24시간 이내에 해결된 의심 플래그의 비율, 표준 ETA와 운송업체 ETA 간의 평균 편차, 조기/지연 알림 감소. 이러한 매핑을 디지털화하면 업계 전반의 가시성이 향상되고 컨테이너 이동 최적화에 도움이 되며, 운송업체, 터미널 및 선적업체가 컨테이너 수준 수신 및 결과와 함께 조기에 더 신뢰할 수 있는 선적 정보를 받을 수 있도록 파편화된 타임스탬프를 넘어 산업을 발전시킬 것입니다.

수집 전에 운송업체 및 컨테이너 식별자 확인: 체크섬, 코드 목록 및 거부 처리

다운스트림 수집 전에 API 게이트웨이에서 ISO 6346 체크섬 논리 및 권위 있는 코드 목록을 사용하여 컨테이너 번호와 운송업체 코드를 확인합니다.

정확한 컨테이너 형식 및 체크섬 확인
- 소유자 코드(3글자) + 장비 범주(1글자, 일반적으로 U/J/Z) + 일련 번호(6자리) + 체크섬(1자리)인 11자리 ISO 6346 항목만 허용합니다.
- 체크섬 계산: 문자를 숫자 값으로 매핑(A=10, B=12, C=13 ... Z=38, 11, 22, 33 건너뜀), 각 문자 값을 2^위치로 곱함(첫 번째 문자의 경우 위치 0), 합계, 합계 mod 11; 나머지 = 10이면 체크섬 = 0으로 설정합니다. 불일치 시 즉시 거부합니다.
- 잘못된 길이, ASCII가 아닌 문자, 소유자 코드의 선행 0 또는 000001–999999 범위를 벗어난 일련 번호가 있는 항목을 거부합니다. 정확한 실패 이유와 출처(API 호출 ID 또는 스프레드시트 행)를 기록합니다.
운송업체 코드 검증 및 코드 목록 관리
- 권위 있는 레지스트리(소유자의 경우 BIC, 미국 운영의 경우 SCAC 또는 합의된 운송업체 목록)에 대해 운송업체 식별자를 매칭합니다. 알려지지 않은 코드는 해결될 때까지 격리된 것으로 처리합니다.
- 인터넷 액세스가 가능한 경우 실시간 조회를 구현합니다. 오프라인의 경우 서명되고 타임스탬프가 찍힌 캐시된 스냅샷으로 대체합니다. 구성 가능한 창(기본 24–72시간)에 대해 캐시된 유효성을 허용하고 각 이벤트에 스냅샷 버전을 기록합니다.
- 얼라이언스 및 선박 운영 파트너 매핑 적용: APMS 및 다운스트림 시스템에서 사용하는 표준 운송업체-운영 운송업체 테이블 유지 관리. 모든 얼라이언스 변경 시 매핑 업데이트 및 누가 재정의를 적용했는지 캡처합니다.
스프레드시트 및 대량 로드에 대한 수집 전 확인
- 업로드하기 전에 행을 플래그 지정하고 거부된 행의 CSV를 오류 코드로 반환하는 클라이언트 측 유효성 검사기(Excel 매크로 또는 경량 JS) 제공. 이는 수동 수정 줄이고 레거시 스프레드시트의 디지털화 속도를 높입니다.
- 대량 수집의 경우 유효, 소프트 실패(알 수 없는 운송업체), 하드 실패(체크섬 불일치) 행을 분리하는 빠른 사전 스캔 실행. 유효한 행만 수집하고, 제출자가 수정 후 다시 업로드할 수 있는 구조화된 거부 파일 반환.
거부 처리 정책 및 오류 분류
1. 통합이 자동으로 작동할 수 있도록 표준화된 오류 코드 사용:
  - ERR01 – FORMAT_INVALID (길이/문자셋)
  - ERR02 – CHECKDIGIT_MISMATCH
  - ERR03 – CARRIER_UNKNOWN
  - ERR04 – MAPPING_OVERRIDE_REQUIRED
2. 코드별 자동 작업 정의:
  - ERR02: 하드 거부, 송신자에게 알림, 수정될 때까지 차단.
  - ERR03: 소프트 격리, 최대 24시간 동안 대체 서비스에서 조회 시도, 여전히 해결되지 않으면 운송업체 운영으로 에스컬레이션.
  - ERR04: 승인된 사용자의 서명된 재정의와 함께만 수락. 감사 추적 기록.
모니터링, KPI 및 SLA
- 거부율, 평균 수정 시간(MTTR), SLA 내에서 해결된 격리된 레코드 비율 추적. 목표: 수집 볼륨의 0.1% 미만 거부율 및 운영 항구/도착에 대한 MTTR 4시간 미만.
- 동향 및 스파이크 감지를 보여주는 대시보드 계측으로 운영자가 수동 검토보다 빠르게 운송업체 목록 또는 대량 스프레드시트 오류의 변경 사항을 파악할 수 있도록 함.
통합 지점 및 운영 안전 장치
- 세관, APMS, 연료 및 벙커 시스템으로 데이터를 보내기 전에 확인합니다. 잘못된 ID는 청구 불일치(연료), 세관 지연 및 잘못된 라우팅 도착을 유발합니다.
- 외부 시스템(APMS, 터미널 시스템)이 업데이트를 보낼 때, 수신자가 어떤 코드 목록이 결정을 내렸는지 알 수 있도록 유효성 검사 스냅샷 버전 첨부.
- 해안 연결이 신뢰할 수 없는 곳에서는 보안 인터넷 또는 L-밴드 위성 링크 사용. 오프라인 유효성 검사도 인터넷 동기화가 완료될 때까지 캐시된 목록 ID를 기록해야 합니다.
거버넌스, 업데이트 및 개발 관행
- 야간 코드 목록 가져오기 자동화 및 즉각적인 변경을 위한 수동 강제 허용. 수동 업데이트를 수행한 사람과 이유를 기록합니다. 운송업체 매핑 또는 사양에 영향을 미치는 모든 변경 사항에 대해 다운스트림 팀에 알립니다.
- CI/CD에 체크섬 논리에 대한 단위 테스트 및 개발 및 QA 중에 사용되는 실제 테스트 벡터(유효 및 무효 번호) 저장소 포함.
- 파트너가 언제 유효성 검사 규칙이나 목록이 변경되었는지 알 수 있도록 공개 변경 로그 유지. 추적성을 위해 이벤트 메타데이터에 변경 로그 ID 연결(마지막 30개 업데이트에 대한 매핑은 여기 참조).
운영 예시
- 시나리오: 에이전트의 스프레드시트 업로드에서 현재 5,000개 행을 보냅니다. 사전 스캔 실행: 4,990개 유효, 8개 ERR02, 2개 ERR03. 행 ID, 오류 코드 및 제안된 수정 사항이 포함된 거부 CSV 반환. 도착 마감 시간을 충족하기 위해 4,990개 즉시 수집.
- 시나리오: 운송업체 얼라이언스가 밤새 접두사를 변경합니다. 매핑 재정의 적용, 지난 48시간 동안 캡처된 도착에 대한 조정 실행, 다운스트림 불일치를 피하기 위해 세관 및 eBOL 시스템으로 수정된 피드 롤아웃.
오늘 구현하기 위한 실용적인 체크리스트
1. API 에지에서 체크섬 유효성 검사 배포.
2. 실시간 및 캐시 모드를 갖춘 하나의 권위 있는 코드 레지스트리 통합.
3. 스프레드시트 사용자를 위한 거부 CSV 템플릿 생성 및 업로드 UI에서 사전 스캔 자동화.
4. 거부 스파이크에 대한 KPI 경고 설정 및 모든 수동 목록 업데이트에 대한 감사 추적 유지.

이러한 단계를 따르면 허위 양성 결과가 줄어들고, 도착 처리 속도가 빨라지며, 세관 및 APMS 흐름과 데이터가 정렬되고, 연료/청구 정확도가 향상되며, 팀이 실제 운영 변경 및 얼라이언스 주도 매핑을 수용하면서 일관되고 감사 가능한 수집을 달성할 수 있습니다.

DCSA 서비스 인증 및 연결: OAuth 흐름, API 키 및 샌드박스-프로덕션 단계

머신 간 통합에는 OAuth 2.0 클라이언트 자격 증명을 사용하고, 사용자를 대신하여 작동하는 애플리케이션에는 PKCE가 있는 인증 코드 흐름을 사용하십시오. 클라이언트 비밀은 비밀 관리자에 저장하고 필요한 최소한의 범위로 제한하십시오.

인터넷을 통한 모든 호출에 대해 TLS 1.2+ 요구, 인증서 유효성 검사, 모바일 앱의 경우 TLS 고정 강제 적용. 공개 클라이언트의 경우 PKCE 및 짧은 수명 액세스 토큰과 첫 사용 시 회전되는 새로 고침 토큰 구현. 기밀 클라이언트의 경우 제공자가 지원하는 경우 상호 TLS 선호.

각 애플리케이션을 고유한 client_id 및 환경별 비밀 또는 키로 DCSA 개발자 포털에 등록합니다. 개발 및 테스트에 샌드박스 자격 증명 사용, ebl 또는 세관 흐름을 다루는 테스트 태그 지정, 통합이 호출하는 API 버전을 문서화하여 중단 변경 사항에 대한 명확성을 얻습니다.

샌드박스 토큰을 받은 경우 토큰 캐싱 및 갱신 자동화: 토큰 수명의 90%에서 새 토큰 요청, 지수 백오프로 실패한 토큰 교환 재시도, 비밀을 콘솔에 인쇄하는 대신 보안 감사 스트림에 토큰 오류 로깅. 토큰을 삽입하고 속도 제한을 강제하는 스마트 로컬 프록시는 개발 마찰을 줄입니다.

API 키는 OAuth를 사용할 수 없는 저위험 원격 측정 또는 파트너 식별에만 사용합니다. 사용자 인증을 대체하기 위해 API 키를 절대 사용하지 않습니다. API 키를 비밀로 취급하고 분기별로 회전하며 이상한 호출 패턴을 보이는 키를 차단합니다.

이 샌드박스-프로덕션 체크리스트를 따르십시오. 1) 계약 및 DCSA 온보딩 완료, 2) 샌드박스에서 보안 및 API 적합성 테스트 통과, 3) 프로덕션 지원 연락처 및 SLA 제공, 4) 감사 로그 및 수동 롤백 계획 제출, 5) 필요한 경우 mTLS 인증서 제출, 6) 운송업체 및 파트너와 프로덕션 전환 창 예약. Hapag-Lloyd 또는 세관 게이트웨이와 같은 운송업체가 10월 배포 창을 요구하는 경우 조기에 조정하고 최종 확인 영수증을 보내는 사람 확인.

모든 프로덕션 호출에 상관 ID 계측, 요청/응답 시간 추적, HTTP 상태 및 EDI 등가 흐름(ebl 및 예약 확인 등)에 대한 비즈니스 수준 영수증 캡처. 이벤트를 파트너, 선적업체, 운송업체 및 운영 장소별로 태그하여 다운스트림 팀이 세관, 환경 보고 또는 연료 추적 요구 사항별로 필터링할 수 있도록 합니다.

마이그레이션 수동 단계 최소화: 인증서 업로드, 클라이언트 등록, 범위 승인 자동화 가능하면 그리고 어떤 파트너가 연결되었고 어떤 파트너가 여전히 수동 온보딩이 필요한지 보여주는 체크리스트 유지. 예약 쿼리 및 추적 영수증 확인을 수행하는 단일 자동 스모크 테스트는 전환 위험을 줄입니다.

개발 중에는 파트너 동작 에뮬레이션: 현실적인 웹훅 페이로드를 보내고 ebl 수락 및 수신 메시지를 포함한 확인을 확인하는 stub 구축. 캐리어, 선적업체 및 세관 게이트웨이의 피크 운영 트래픽을 시뮬레이션하는 샌드박스에 대한 로드 테스트 실행하여 재시도 및 동시성 조정.

프로덕션으로 전환 후 사용량 및 비즈니스 KPI 모니터링: 토큰 교환율, 실패한 인증 호출, 평균 호출 지연 시간, 파트너에게 전달되지 않은 영수증 수 추적. 이러한 지표를 사용하여 선적업체, 운송업체 및 시기적절한 EDI/EBL 업데이트와 환경 또는 연료 보고에 의존하는 산업에 직접적인 영향을 미치는 수정 사항 우선 순위 지정.