DCSA API Standartları - Küresel Denizcilik Sektöründe Veriye Erişimi Kolaylaştırma

DCSA API'lerini Şimdi Uygulayın: Rezervasyon, olaylar ve takip uç noktalarına öncelik verin ve manuel işlem noktalarını yaklaşık %40 oranında azaltmak ve her kullanıcıya gerçek zamanlıya yakın güncellemeler sunmak için 12 hafta içinde standartlaştırılmış veri yüklerini benimseyin.

Üç pratik adımla başlayın: mevcut arayüzleri haritalayın, hala EDI kullanan eski sistemler için ince bir API katmanı oluşturun ve olay kayıtlarını zenginleştirmek için uydu tabanlı konum akışlarını pilot olarak uygulayın. Bu yaklaşım, mevcut operasyonları korurken otomatik bildirimler ve tahmini varış zamanı (ETA) düzeltmeleri için sorunsuz bir yol oluşturur.

Sonuçları ölçerek değere kanıt sunun: bir rezervasyonun onaylanma ortalama süresini, e-posta yazışmalarındaki azalma yüzdesini, sefer başına durum güncellemesi sıklığını ve müşteri başına API çağrı kullanımını izleyin. Bu metrikler, dönüşümün tedarik zinciri genelinde satın alma ve operasyonları nasıl dönüştürdüğünü ve ekiplerin limanda bekleme sürelerini ve yanlış yönlendirmeleri azaltmak için nasıl birlikte çalıştığını gösterir.

Net planları takip edin: bir taşıyıcı, iki nakliyeci ve bir terminal ile üç bölümlü bir pilot çalışma yürütün; hizmet seviyesi sözleşmesi (SLA) ve sürüm kurallarını yayınlayın; SDK'lar ve örnek veri yükleri sağlayın; ve haftalık entegrasyon kontrol noktaları planlayın. Bu somut adımlar bugün tekrarlanabilir sonuçlar üretir ve aşağı akış sistemleri, analizler ve ortak entegrasyonlar için standartlaştırılmış verileri kullanılabilir hale getirir.

DCSA API Standartları: Küresel Denizcilikte Veriye Erişimi Kolaylaştırmak – Konteyner Gemi Varışlarını ve Platform Dağıtımını Dijitalleşme İçin Hizalamak

Gemi ETA yayınını, yanaşma yeri tahsisini ve platform dağıtımını senkronize etmek, manuel elden teslimleri azaltmak ve otomatik operasyonel güncellemelerin kilidini açmak için 12 ay içinde DCSA API standartlarını uygulayın.

ETA ve durum güncellemelerini 15 dakikalık aralıklarla yayınlamak üzere API'ler gerektirin ve taşıyıcılar, terminaller ve acenteler arasındaki anında iletişim için olay odaklı web kancalarını destekleyin. Rota boyunca konum ve hızın yakalanması ve liman sistemlerine aktarılması için AIS ve uydu akışlarını entegre edin; aktarım sırasında eşleme hatalarını önlemek için veri yüklerini ISO 8601 zaman damgaları ve UN/LOCODE'lar ile standartlaştırın. Anlamı koruyan sürüm oluşturma ve geriye dönük uyumluluk için açıkça yayınlanan pencerelerle yılda üç büyük sürüm planlayın, böylece kullanıcılara öngörülebilir yükseltme döngüleri sunulur.

Terminal işletme sistemleri ve taşıyıcı planlama sistemlerinden gelen operasyonel akışları birleştirerek yanaşma yeri pencerelerini optimize edin; Maersk ve terminal ortaklarıyla yapılan pilotlar, yanaşma yeri bekleme süresinde %20'ye varan azalma ve manuel planlamaya göre daha yüksek yanaşma yeri kullanım oranı göstermektedir. Gemi hareketleri arasındaki yanaşma yeri boşta kalma sürelerini azaltmak için otomatik yanaşma yeri yeniden atama kurallarını ve bildirim iletişimlerini kullanın, bu da yapılandırılmamış mesajlaşmanın başarabileceğinden daha fazla verim artışı sağlar.

Her API veri yüküne çevresel metrikler ekleyin: yakıt tüketimi, yardımcı motor saatleri ve uydu tabanlı emisyon tahminleri. Kaydedilen bu metrikleri liman ve taşıyıcı yönetim panolarına besleyerek TEU başına CO2'yi ölçün ve sürdürülebilir kalkınma için ölçülebilir hedefler belirleyin. Operatörlerin rotalama ve yanaşma yeri seçimlerini emisyonlar ve işletme maliyeti açısından karşılaştırmalarına olanak tanıyarak daha iyi sürdürülebilirlik sonuçları sağlayan stratejik seçimler yapmalarını sağlarlar.

Standart uyumluluğu sözleşmesel SLA'lara bağlayan, iletişim protokollerini açıklayan ve veri kalitesinden sorumlu olan yönetişimi oluşturun. Geliştirme ve yeni kullanıcıların katılımını hızlandırmak için geliştirici araç kitlerini, test ortamlarını ve açık belgeleri teşvik edin. Anahtar performans göstergelerini (KPI'lar) – varış zamanı doğruluğu, otomatik aktarım başarı oranı ve manuel müdahalelerin azalması – izleyin ve paydaşların ilerlemeyi ölçebilmeleri ve daha fazla entegrasyon planlayabilmeleri için üç aylık raporlar yayınlayın.

Operasyonel Plan: Gemi Varış Verilerini Hizalamak İçin DCSA API'lerinin Uygulanması

Taşıyıcılar, limanlar ve terminaller arasındaki gemi varışlarını hizalamak için 24 saatlik bir SLA ile DCSA Olay, Sefer ve Liman Çağrısı API'lerini kullanarak standartlaştırılmış bir varış durumu uzlaştırma süreci uygulayın.

Varış verilerini üç ana kaynaktan yakalayın: DCSA Sefer API aracılığıyla taşıyıcı manifestoları, Liman Çağrısı API aracılığıyla terminal sistemleri ve AIS akışları. Hızlı güncellemeler için Olay API web kancalarını kullanın ve web kancaları başarısız olduğunda 5 dakikalık aralıklarla periyodik yoklamaya geri dönün. Kökeni korumak ve denetim izlerini desteklemek için her kaydı bir KAYNAK (source) alanı ve bir yakalama_zaman damgası ile etiketleyin.

Gelen veri yüklerini aşağıdaki özel kanonik alanlarla tek bir operasyonel modele normalleştirin: gemi_imo, sefer_id, eta_utc, ata_utc, yanaşma_yeri, durum_kodu, bunker_onboard_mt, estimated_fuel_burn_mt, customs_status ve event_origin. Tüm zamanları UTC'ye dönüştürün, en yakın dakikaya yuvarlayın ve aktarım sırasında eşleme hatalarını önlemek için farklı durum kodlarını 7 durumlu bir varış terminolojisine (planlanan, ETA güncellendi, yolda, varıldı, yanaşıldı, yanaşıldı, ayrıldı) eşleyin.

Deterministik eşleştirme kuralları kullanın: mümkünse gemi_imo + sefer_id üzerinde tam eşleştirme; aksi takdirde Olay API = 0,5, AIS = 0,3, terminal mesajları = 0,2 ağırlıklandıran bir puanlama fonksiyonu kullanarak gemi_imo + eta penceresi ±72 saat üzerinde eşleştirin. 0,6'dan düşük puanlı eşleşmeleri insan incelemesi için tutarsızlıklar olarak işaretleyin. ETA - ATA için 60 dakikalık bir tutarsızlık eşiği tanımlayın; daha büyük boşlukları, yakıt kullanımını ve gümrük sorgusunda bekleme süresini artırabilecek operasyonel istisnalar olarak ele alın.

Kullanıcı arayüzlerine ve makine arayüzlerine eşzamanlı olarak istisna işleme yeteneği ekleyin. Yüksek öncelikli istisnaları API bildirimleri aracılığıyla taşıyıcı operasyon ekiplerine ve UI panoları aracılığıyla terminal planlayıcılarına gönderin. Kullanıcılara önerilen düzeltici eylemleri sunun: alternatif yanaşma yerine yönlendirme, acil bunker ayarlaması talebi veya gümrük belgelerinin ön onaylanması. Operatör kararlarını ve çözüm süresini daha sonra analiz için kaydedin.

Aşağıdaki KPI'lar ve hedeflerle performansı ölçün: tutarsızlık_oranı (<6 ay içinde <%5), ortalama_hizalama_süresi (<4 saat), SLA_uyumluluk (≥%98), bunker_varyansı (bildirilen gemidekilerin ±%3'ü) ve varış başına ekonomik_etki_tahmini. Son üç ayı temel olarak kullanın ve tasarrufları doğrulamak ve doğruluk modelini oluşturmak için ekim ayında önde gelen bir Asya-Avrupa rotasında 500 yakalanan varışla bir pilot çalışma yapın.

Tekrarlanan olayları azaltan ve sistem arayüzü kullanımını iyileştiren dönüştürme kuralları uygulayın: aynı kaynaktan 2 dakikadan kısa süre içindeki kopyaları atın, aynı gemi_imo+event_origin+timestamp'i paylaşan olayları birleştirin ve soy izi için ham veri yüklerini saklayın. Analistlerin yolculuk boyunca ortaya çıkan tutarsızlıklara yol açan zamanlama örüntülerini anlamalarına yardımcı olmak için kayıtları events_history dizisiyle açıklayın.

Sürüm oluşturulmuş API sözleşmeleri, ortak başına OAuth2 belirteçleri, yoğun operasyonlara göre ayarlanmış hız sınırları (Olay abonelikleri için önerilen 1.200 çağrı/dakika) ve saklama politikaları (ham veriler 12 ay, toplu veriler 36 ay) ile veri akışlarını yönetin. Ortakların alan anlambiliminde uyum sağlamaları ve başlangıç entegrasyonunun ötesindeki eşleme çabalarını azaltmaları için endüstri çapında bir şema kayıt defteri (schema registry) oluşturun.

DCSA API	Yakalanan Ana Alanlar	Eylem	SLA / Hedef
Olay API'si (Event API)	olay_türü, zaman damgası, konum, gemi_imo, sefer_id	Gerçek zamanlı yakalama, önce webhook, 2 dk gecikme	Webhook teslimatı <30s; iki kez yeniden dene
Sefer API'si (Voyage API)	sefer_id, eta_utc, planlanan_liman_çağrıları, kargo_manifestosu	Kanonik sefer kaydını doldur, manifesto tutarsızlıklarını işaretle	Her 4 saatte bir senkronize et; 1 saat içinde güncellemeler
Liman Çağrısı API'si (Port Call API)	liman_çağrısı_id, yanaşma_yeri, yanaşma_zamanı, yanaşma_tamamlandı_zamanı, gümrük_durumu	Liman tarafı durumunu hizala, gümrük gecikmelerini yüzeye çıkar	Yerel olaydan sonra <15 dk içinde güncelle
Referans Veri API'si (Reference Data API)	konumlar, terminaller, taşıyıcı_kodları	İsimleri/kimlikleri çözümle, eşleme hatalarını azalt	Haftalık yenileme; 24 saat içinde acil düzeltmeler
Konum / AIS	lat, lon, sog, cog, zaman damgası	ETA/ATA'yı destekle, yakıt tüketimi tahmini	Akış gecikmesi <60s

Bu adımlarla üç aylık bir pilot çalışma yapın: ekim ayında önde gelen bir rotada entegrasyonları dağıtın, uzlaştırma modelini eğitmek için 500 geçmiş ve canlı varışı alın, yanlış pozitifleri <%8'e indirmek için kuralları yineleyin ve aylık ekonomik etkiyi ölçün. Sonuçları gümrük ortaklarına bilgi vermek için raporlayın, böylece işlem süreleri kısalır ve operasyon ekiplerine yakıt tüketimini artıran bekleme sürelerini azaltmaları için bilgi verin. Pilot çalışmadan elde edilen dersleri endüstri çapında genişletmek ve kullanıcıların yerel siloların ötesinde hizalanmış varış verilerini görmelerini sağlamak için arayüzleri ölçeklendirmek için kullanın.

Gemi varış hizalaması için kritik uç nokta setini belirleyin: gerekli DCSA API'leri ve veri yükleri

Gemi varışlarını hizalamak için bu minimum uç nokta setini uygulayın: Liman Çağrısı (sefer/eta), Olay Bildirimleri (webhook), Taşıma/Hareket, Rezervasyon, Ekipman/Konteyner, Terminal Arayüzü, Referans/Konum ve Taraf API'leri.

Liman Çağrısı veri yükü: seferId, vesselIMO, vesselName, voyageNumber, portCode (UN/LOCODE), scheduledArrival (ISO‑8601), estimatedArrival, scheduledDeparture, berthingWindowStart, berthingWindowEnd, berthCode, draftMeters, nextPortCode ve sequenceVersion'ı içerir. TEU ve draft için sayısal alanlar kullanın ve sourceSystem ve lastUpdatedBy alanlarını sağlayın. Örneğin: scheduledArrival: "2026-03-10T14:00:00Z". İlk senkronizasyonda tam sefer anlık görüntüsünü ve sonraki veri delta'larını iletin.

Olay Bildirimleri veri yükü: eventType, eventTimestamp, relatedId (voyageId, containerNumber, bookingReference), locationCode, statusCode, details, sequenceNumber ve idempotencyKey. Abone uç noktalarına yeniden deneme/geri çekilme (retry/backoff) ve üssel pencerelerle (exponential windows) RFC JSON:API formatında POST'lar gönderin. Olayları otomatik veya manuel olarak işaretleyin ve olayı oluşturan sistemi tanımlamak için eventProvenance'ı ekleyin.

Taşıma/Hareket veri yükü: transportId (GUID), shipmentId, bookingReference, carrierBookingReference, billOfLadingNumber, originUNLOC, destinationUNLOC, mode, containers:[{containerNumber,sizeType,status}], cargoType, weightKg, loadedOnVoyageId ve currentStatusTimestamp. Terminal planlamasına yardımcı olmak için manifestReference ve estimatedOnboardTime'ı mümkün olduğunda sağlayın.

Rezervasyon veri yükü: bookingReference, shipperPartyId, consigneePartyId, commodities, totalTEU, containerRequirements, portCutoffTimes:{terminalCutoff,gateCutoff,docsCutoff} (saat dilimi ile), requestedPickupDate ve confirmedStatus. Bu değerleri terminal yuvalama ve randevu sistemlerini yönlendirmek için kullanın; uzlaştırma için bookingVersion'ı saklayın.

Ekipman/Konteyner veri yükü: containerNumber, isoSizeType, tareKg, grossKg, currentLocationCode, lastFreeTime, containerStatus ve sealInfo. Bu kayıtları transportId ve voyageId'ye bağlayarak terminal sistemlerinin ve müşterilerin tek bir doğruluk kaynağı görmesini sağlayın.

Terminal Arayüzü veri yükü: terminalCode, berthCode, availableCraneCount, plannedBerthStart, plannedBerthEnd, gateSlots (zaman aralıkları), yardOccupancyPercent ve serviceLevels. Terminal terminallerin yanaşma yeri teyitlerini ve yuva atamalarını Liman Çağrısı ve Rezervasyon alanlarına geri aktarabilmeleri için modeli tasarlayın.

Referans ve Taraf veri yükleri: partyId (taşıyıcı, terminal, nakliyeci, alıcı), isimler, roller, iletişim yöntemleri ve locationList. Denizcilikle ilgili sistemlerin kümesinde tutarlı eşleştirmeyi teşvik etmek için UN/LOCODE ve standartlaştırılmış rol terimleri sağlayın.

Protokol ve uygulama kuralları: JSON:API içerik türünü benimseyin, RFC3339 zaman damgaları gerektirin, yukarıda listelenen zorunlu anahtarları uygulayın, delta değişiklikleri için PATCH'i destekleyin ve uç noktaları sürümlendirin. Otomatik olay teslimatı için web kancalarını kullanın ve tam senkronizasyon için bir çekme API'si (pull API) sağlayın. Hız sınırı önerisi: senkronizasyon uç noktaları için istemci başına 5 istek/sn ve 429 yanıtlarında geri çekilme (backoff) ile 1.000 webhook olayı/dakika izni verin.

Operasyonel öneriler: bir gemi yaklaştıkça ETA güncellemelerini daha sık iletin – örneğin, 48 saatten fazla uzaktayken her 15 dakikada bir, 6 saat içinde her 5 dakikada bir ve gerçek varış/yanaşma anında hemen. Tüketen sistemlerin yinelenenler olmadan devam etmelerini ve tekil bilgiyi (idempotency) korumalarını sağlamak için yanıtlarla sequenceNumber ve lastProcessedEvent'i ekleyin.

İzleme ve devreye alma: her uç nokta için teslimat başarı oranı (deliverySuccessRate), ortalama gecikme süresi (averageLatencyMs) ve işlem hataları metriklerini gösterin. Şema doğrulama, webhook yeniden denemeleri, kimlik doğrulama (mTLS veya OAuth2) ve taşıyıcı, terminal ve müşteri sistemleri arasındaki uçtan uca testleri içeren bir devreye alma kontrol listesi çalıştırın. İlk sprint sırasında bu öğeleri geliştirmek ve izlemek üzere fonksiyonlar arası bir ekip atayın.

Eşleme ve veri modelleme rehberliği: yerel alanları bir entegrasyon katmanında kanonik adlara (voyageId, portCode, scheduledArrival) eşleyin; orijinal kaynak tanımlayıcılarını bir sourceRef dizisinde saklayın. Aşağı akış uzlaştırmayı ve müşteri bildirimlerini yönlendirmek için kimin neyi ne zaman değiştirdiğini kaydeden bir changeLog modeli kullanın.

Güvenlik ve yönetişim: uç nokta başına belirteç kapsamları (token scopes) gerektirin ve role göre döndürülen verileri sınırlayın. Veri paylaşımı için onayları ve sözleşme şartlarını kaydedin ve müşterilerin ve terminallerin kökeni doğrulayabilmeleri için iletilen olaylar için auditTrail girişlerini ekleyin.

Uygulamaya öncelikli bir kontrol listesinden başlayın: 1) Liman Çağrısı ve Olay web kancaları, 2) Taşıma ve Rezervasyon senkronizasyonu, 3) Terminal arayüzü ve Ekipman, 4) Referans ve Taraf konsolidasyonu, 5) izleme ve devreye alma testleri. Bu sıralama, rastgele yaklaşımlardan daha az entegrasyon işi gerektirir ve ekibin haftalar içinde görünür gemi varış hizalaması sunmasına olanak tanır.

Liman çağrısı olaylarını kanonik bir varış zaman çizelgesine çevirin: eşleme kuralları ve zaman damgası önceliği

Her gemi ve sevkiyat için tek bir kanonik varış zaman çizelgesi oluşturmak üzere beş adımlı bir eşleme ve zaman damgası önceliği kural seti uygulayın: ham olayları kanonik fazlara eşleyin, her faz için en yüksek öncelikli zaman damgasını seçin, kaynak güvenilirliğini ekleyin ve insan incelemesi için çakışmaları işaretleyin.

Kanonik fazları şu şekilde tanımlayın: yaklaşma (gemi limana 24 deniz mili içinde), pilot_gemide, yanaşıldı/yanaşma, kargo_operasyonlarına_başla (ilk konteyner hareketinin alınması), kargo_operasyonları_tamamlandı ve ayrıldı. Kaynak olaylarını bu fazlara eşleyin: AIS konum raporları, pilot/liman otoritesi manifestoları, terminal işletme sistemi (TOS) yanaşma yeri olayları, taşıyıcı operasyon mesajları (SOC/COC), kapı-giriş/kapı-çıkış konteyner taramaları ve gemi kayıt defteri girişleri. Faz başına bir kanonik zaman damgası saklayın ve denetim ve uzlaştırma için orijinal olay listelerini saklayın.

Zaman damgası önceliği (en yüksekten en düşüğe): 1 – Pilot ve yanaşma yeri yetkilendirmeleri için Liman otoritesi / pilot zaman damgaları (yetkili). 2 – Yanaşma yeri/yanaşma ve kargo operasyonlarının başlaması için terminal işletme sistemi zaman damgaları. 3 – Konteyner alımı ve hareketleri için terminal/konteyner kapı taramaları. 4 – Planlanan ve operatör tarafından onaylanan dönüm noktaları için taşıyıcı operasyonel mesajları (ETA/ATA, SOC/COC). 5 – Otomatik algılama için AIS'den türetilen zaman damgaları (X deniz mili geçişi, yanaşma yerinde durdu). Daima UTC ISO 8601'e normalleştirin ve kaynak tanımlayıcısını ve güvenilirlik puanını ekleyin.

Çakışmaları deterministik kurallarla çözün: daha yüksek öncelikli bir zaman damgası varsa, bunu kanonik faz için kullanın. Düşük öncelikli veriler, daha yüksek öncelikli zaman damgasından daha fazla T1 = yanaşma/yanaşma için 30 dakika veya T2 = yaklaşma/ETA için 120 dakika ile önce gelirse, her iki zaman damgasını da saklayın, kanonik fazı "şüpheli" olarak işaretleyin ve sourceConfidence = düşük olarak ayarlayın. AIS, TOS'dan <30 dakika önce yanaşıldığını gösteriyorsa, TOS'u tercih edin ancak AIS'yi destekleyici kanıt olarak kaydedin. Kayıp daha yüksek öncelikli veriler için, bir sonraki mevcut kaynağı yükseltin ancak kaynak türüne göre bir promotionReason ve expectedAccuracy (%) kaydedin.

Saat ve saat dilimi kontrollerini uygulayın: tüm kaynaklardan zaman damgalarını UTC'de göndermelerini isteyin. Bilinen saat sapmaları için, geçmiş karşılaştırmalardan hesaplanan kaynaklara özel ofsetleri uygulayın (son ofset ve stdev saklayın). Varış fazları için 7 günden eski zaman damgalarını, imzalı bir liman otoritesi kaydı eşlik etmedikçe reddedin. Otomatik olarak maksimum 60 dakikalık bir düzeltme uygulayın; daha büyük düzeltmeler manuel inceleme gerektirir.

Önerilen kanonik olay şeması (örnek alanlar): eventType, canonicalTimestampUTC, sourceType, sourceId, sourceConfidence(0-1), rawTimestamps[listeler], berthId, portUNLocode, vesselIMO, containerCount, affectedContainers[], phaseDurationMinutes. Bu alanları, ETA varyansının azaltılması, daha erken müşteri bildirimleri ve konteyner başına ölçülebilir taşıma süresi azalması gibi KPI sonuçları üretmek için kullanın.

Kullanıcılar ve ittifaklar için operasyonel rehberlik: tutarlı mesajları DCSA uyumlu uç noktalar aracılığıyla etkinleştirmek için bu kuralları taşıyıcı ve terminal API'lerine entegre edin. Sistemlerin otomatik iş akışlarını genişletebilmesi ve yanaşma yeri planlamasını optimize edebilmesi için tanıttığımız kuralları nakliyeciler ve müşterilerle paylaşın. Beş benimseme metriğini izleyin: yetkili kaynağa sahip fazların yüzdesi, ortalama promosyon sıklığı, 24 saat içinde çözülen şüpheli bayrakların yüzdesi, kanonik ve taşıyıcı ETA arasındaki ortalama sapma ve erken/geç bildirimlerin azalması. Bu eşlemeleri dijitalleştirmek, sektörler arası görünürlüğü artıracak, konteyner hareketlerini optimize etmeye yardımcı olacak ve endüstriyi parçalanmış zaman damgalarının ötesine taşıyacak, böylece taşıyıcılar, terminaller ve nakliyeciler, konteyner düzeyinde makbuzlar ve sonuçların yanı sıra daha erken, daha güvenilir sevkiyat bilgileri alacaktır.

Veri alımından önce taşıyıcı ve konteyner tanımlayıcılarını doğrulayın: kontrol basamakları, kod listeleri ve reddetme işlemleri

Herhangi bir aşağı akış veri alımından önce API ağ geçidinde konteyner numaralarını ve taşıyıcı kodlarını ISO 6346 kontrol basamağı mantığı ve yetkili kod listeleri kullanarak doğrulayın.

• Kesin konteyner biçimi ve kontrol basamağı doğrulaması

  • Yalnızca 11 karakterli ISO 6346 girişlerini kabul edin: sahip kodu (3 harf) + ekipman kategorisi (1 harf, genellikle U/J/Z) + seri (6 rakam) + kontrol basamağı (1 rakam).
  • Kontrol basamağını hesaplayın: harfleri sayısal değerlere eşleyin (A=10, B=12, C=13 ... Z=38, 11, 22, 33'te boşluklar ile), her karakter değerini 2^konum ile çarpın (ilk karakter için konum 0), toplayın, toplamı 11'e bölün; kalan 10 ise kontrol basamağını 0 olarak ayarlayın. Eşleşme durumunda hemen reddedin.
  • Yanlış uzunluktaki, ASCII olmayan harfleri, sahip kodunda baştaki sıfırları veya 000001–999999 dışındaki seri numaralarını reddedin; tam hata nedenini ve kaynağını (API çağrı kimliği veya elektronik tablo satırı) günlüğe kaydedin.

• Taşıyıcı kodu doğrulama ve kod listesi yönetimi

  • Taşıyıcı tanımlayıcılarını yetkili bir kayıt defteriyle (sahipler için BIC, ABD operasyonları için SCAC veya sizin anlaştığınız taşıyıcı listesi) eşleştirin. Bilinmeyen kodları çözülene kadar karantinaya alınmış olarak kabul edin.
  • İnternet erişimi mevcut olduğunda gerçek zamanlı arama yapın; çevrimdışıysa imzalı, zaman damgalı önbelleğe alınmış bir anlık görüntüye geri dönün. Yapılandırılabilir bir pencere (varsayılan 24–72 saat) için önbellek geçerliliğine izin verin ve her olayda anlık görüntü sürümünü kaydedin.
  • İttifaklar ve gemi işleten ortaklar için eşleme uygulayın: APMS ve aşağı akış sistemleri tarafından kullanılan bir kanonik taşıyıcıdan operasyonel taşıyıcıya tabloyu koruyun; her ittifak değişikliğinde eşlemeyi güncelleyin ve geçersiz kılmayı kimin uyguladığını yakalayın.

• Elektronik tablolar ve toplu yüklemeler için alım öncesi kontroller

  • Yüklemeden önce satırları işaretleyen ve reddedilen satırların hata kodlarıyla birlikte bir CSV dosyası döndüren bir istemci tarafı doğrulayıcı (Excel makrosu veya hafif JS) sağlayın; bu, manuel düzeltmeleri azaltır ve eski elektronik tabloların dijitalleştirilmesini hızlandırır.
  • Toplu veri alımı için geçerli, yumuşak hatalı (bilinmeyen taşıyıcı) ve sert hatalı (kontrol basamağı hatası) satırları ayıran hızlı bir ön tarama yapın. Yalnızca geçerli satırları alın; gönderenin düzeltmelerden sonra yeniden yükleyebileceği yapılandırılmış bir reddetme dosyası döndürün.

• Reddetme işleme politikası ve hata taksonomisi

  1. Entegrasyonların otomatik olarak işlem yapabilmesi için standartlaştırılmış hata kodları kullanın:
     • ERR01 – FORMAT_INVALID (uzunluk/karakter seti)
     • ERR02 – CHECKDIGIT_MISMATCH (kontrol basamağı hatası)
     • ERR03 – CARRIER_UNKNOWN (taşıyıcı bilinmiyor)
     • ERR04 – MAPPING_OVERRIDE_REQUIRED (eşleme geçersiz kılma gerekli)
  2. Kod başına otomatik eylemler tanımlayın:
     • ERR02: sert reddet, göndericiyi bilgilendir, düzeltilene kadar engelle.
     • ERR03: yumuşak karantinaya al, 24 saate kadar alternatif hizmetlerden arama yapmaya çalış, ardından hala çözülmezse taşıyıcı operasyonlarına yükselt.
     • ERR04: yalnızca yetkili kullanıcıdan imzalı geçersiz kılma ile kabul et; denetim izini kaydet.

• İzleme, KPI'lar ve SLA'lar

  • Reddetme oranı, düzeltme için ortalama süre (MTTR) ve SLA kapsamında çözülen karantinaya alınmış kayıtların oranını izleyin. Hedeflenen amaçlar: reddetme oranı
  • Eğilimleri ve ani yükseliş tespitlerini gösteren panoları donatın, böylece operasyonlar taşıyıcı listelerindeki değişiklikleri veya toplu elektronik tablo hatalarını manuel incelemenin başarabileceğinden daha hızlı tespit edebilir.

  • Entegrasyon noktaları ve operasyonel güvenceler

    • Gümrük, APMS, yakıt ve bunker sistemlerine veri göndermeden önce doğrulayın. Yanlış kimlikler faturalandırma tutarsızlıklarına (yakıt), gümrük gecikmelerine ve hatalı yönlendirilmiş varışlara neden olur.
    • Harici bir sistem (APMS, terminal sistemi) güncelleme gönderdiğinde, alıcıların hangi kod listesinin kararı ürettiğini bilmeleri için doğrulama anlık görüntüsü sürümünü ekleyin.
    • Kıyı bağlantısının güvenilirsiz olduğu yerlerde güvenli internet veya L-band uydu bağlantılarını kullanın; çevrimdışı doğrulama, internet senkronizasyonu tamamlanana kadar önbelleğe alınmış liste kimliğini kaydetmelidir.

  • Yönetişim, güncellemeler ve geliştirme uygulamaları

    • Gecelik kod listesi çekmelerini otomatikleştirin ve anında değişiklikler için manuel zorlamaya izin verin; manuel güncellemeleri kimin gerçekleştirdiğini ve nedenini günlüğe kaydedin. Taşıyıcı eşleştirmelerini veya özelliklerini etkileyen herhangi bir değişiklik hakkında aşağı akış ekiplerini bilgilendirin.
    • CI/CD'ye kontrol basamağı mantığı için birim testlerini ve geliştirme ve QA sırasında kullanılan gerçek dünya test vektörleri (geçerli ve geçersiz numaralar) deposunu ekleyin.
    • Ortakların doğrulama kurallarınızın veya listelerinizin ne zaman değiştiğini bilmeleri için herkese açık bir değişiklik günlüğü (changelog) tutun; izlenebilirlik için değişiklik günlüğü kimliğini olay meta verilerine bağlayın (son 30 güncelleme için eşlemeye buradan bakın).

  • Operasyonel örnekler

    • Senaryo: bir acenteden gelen bir elektronik tablo yüklemesi şu anda 5.000 satır gönderiyor. Ön tarama yapın: 4.990 geçerli, 8 ERR02, 2 ERR03. Satır kimlikleri, hata kodları ve önerilen düzeltmelerle bir reddetme CSV'si döndürün; varış tarihlerine uymak için 4.990'ı hemen alın.
    • Senaryo: bir taşıyıcı ittifakı ön ekleri gece yarısı değiştirir. Eşleme geçersiz kılmasını uygulayın, son 48 saatteki yakalanan varışlara karşı uzlaştırma çalıştırın ve aşağı akış tutarsızlıklarını önlemek için düzeltilmiş bir akışı gümrük ve eBOL sistemlerine yayınlayın.

  • Bugün uygulamak için pratik kontrol listesi

    1. API kenarında kontrol basamağı doğrulamaları konuşlandırın.
    2. Gerçek zamanlı ve önbelleğe alınmış modlara sahip tek bir yetkili kod kayıt defteri entegre edin.
    3. Elektronik tablo kullanıcıları için reddetme CSV şablonları oluşturun ve yükleme UI'sinde ön taramayı otomatikleştirin.
    4. Reddetme ani yükselişleri için KPI uyarıları ayarlayın ve tüm manuel liste güncellemeleri için denetim izlerini saklayın.

  Bu adımları izlemek yanlış pozitifleri azaltır, varışların işlenmesini hızlandırır, verileri gümrük ve APMS akışlarıyla hizalar, yakıt/faturalandırma doğruluğunu artırır ve ekiplerinizin gerçek operasyonel değişiklikleri ve ittifak odaklı eşleştirmeleri karşılayarak tutarlı, denetlenebilir veri alımı sağlamasına olanak tanır.

  DCSA hizmetlerine kimlik doğrulama ve bağlantı: OAuth akışları, API anahtarları ve sandbox'tan üretime adımlar

  Makineden makineye entegrasyonlar için OAuth 2.0 istemci kimlik bilgilerini ve bir kullanıcının adına hareket eden herhangi bir uygulama için PKCE ile Yetkilendirme Kodu'nu kullanın; istemci sırlarını bir sır yöneticisinde (secrets manager) saklayın ve kapsamları gerekli minimum düzeyle sınırlayın.

  İnternet üzerinden yapılan tüm aramalar için TLS 1.2+'yı zorunlu kılın, sertifikaları doğrulayın ve mobil uygulamalar için TLS sabitlemeyi (pinning) uygulayın. Genel istemciler için PKCE ve ilk kullanımda yenilenen yenileme belirteçleriyle kısa ömürlü erişim belirteçleri uygulayın; gizli istemciler için sağlayıcı destekliyorsa karşılıklı TLS'yi (mutual TLS) tercih edin.

  Her uygulamayı DCSA geliştirici portalında benzersiz bir istemci kimliği (client_id) ve ortama özel bir sır veya anahtarla kaydedin. Geliştirme ve test için sandbox kimlik bilgilerini kullanın, e-poliçe veya gümrük akışlarını etkileyen testleri etiketleyin ve hangi API sürümlerinin entegrasyonunuz tarafından çağrıldığını belgeleyin, böylece kırıcı değişiklikler hakkında netlik kazanabilirsiniz.

  Sandbox belirteçlerini aldığınızda belirteç önbellekleme ve yenilemeyi otomatikleştirin: belirteç ömrünün %90'ında yeni bir belirteç isteyin, başarısız belirteç değişimlerini üssel bir geri çekilme ile yeniden deneyin ve belirteç hatalarını sırları konsola yazdırmak yerine güvenli bir denetim akışına (audit stream) kaydedin. Belirteçleri ekleyen ve hız sınırlarını uygulayan akıllı bir yerel proxy, geliştirme sürtünmesini azaltır.

  API anahtarlarını yalnızca OAuth'un mevcut olmadığı düşük riskli telemetri veya ortak kimliği için kullanın; API anahtarlarını asla kullanıcı kimlik doğrulaması yerine kullanmayın. API anahtarlarını sır gibi muamele edin, bunları üç ayda bir yenileyin ve anormal çağrı desenleri gösteren anahtarları engelleyin.

  Bu sandbox'tan üretime geçiş kontrol listesini izleyin: 1) sözleşmeyi ve DCSA katılımını tamamlayın, 2) sandbox'ta güvenlik ve API uyumluluk testlerini geçin, 3) bir üretim destek kişisi ve SLA sağlayın, 4) denetim günlüklerini ve manuel geri alma planını sunun, 5) gerekirse mTLS sertifikalarını gönderin ve 6) taşıyıcılar ve ortaklarla bir üretim geçiş penceresi planlayın. Hapag-Lloyd gibi bir taşıyıcı veya bir gümrük ağ geçidi ekim dağıtım penceresi gerektiriyorsa, erken koordine olun ve son onay makbuzlarını kimin gönderdiğini onaylayın.

  Her üretim çağrısını korelasyon kimlikleriyle (correlation IDs) izleyin, istek/yanıt sürelerini izleyin ve EDI eşdeğeri akışlar (örneğin e-poliçeler ve rezervasyon onayları) için HTTP durumunu ve iş düzeyi makbuzlarını yakalayın. Olayları ortaklara, nakliyecilere, taşıyıcıya ve operasyonel mekâna göre etiketleyin, böylece aşağı akış ekipleri gümrük, çevresel raporlama veya yakıt takibi gereksinimlerine göre filtreleme yapabilir.

  Göç manuel adımlarını en aza indirin: sertifika yüklemeyi, istemci kaydını ve kapsam onaylarını mümkün olduğunca otomatikleştirin ve hangi ortakların bağlı olduğunu ve hangilerinin hala manuel katılım gerektirdiğini gösteren bir kontrol listesi tutun. Tek bir otomatik duman testi (smoke test) bir rezervasyonu sorgulayarak ve takip edilen bir makbuzu doğrulayarak geçiş riskini azaltır.

  Geliştirme sırasında, ortak davranışlarını taklit edin: gerçekçi webhook veri yükleri gönderen ve e-poliçe kabulü ve makbuz mesajları dahil olmak üzere onaylarınızı doğrulayan bir stub (taklitçi) oluşturun. Taşıyıcılar, nakliyeciler ve gümrük ağ geçitlerinden gelen yoğun operasyonel trafiği simüle eden yük testlerini sandbox üzerinde çalıştırın, böylece yeniden denemeleri ve eşzamanlılığı ayarlayabilirsiniz.

  Üretim ortamına geçtikten sonra kullanımı ve iş KPI'larını izleyin: belirteç değişim oranlarını, başarısız kimlik doğrulama çağrılarını, ortalama çağrı gecikmesini ve ortaklara teslim edilmeyen makbuz sayısını izleyin. Bu metrikleri, nakliyecileri, taşıyıcıları ve zamanında EDI/EBL güncellemeleri ile çevresel veya yakıt raporlamasına dayanan sektörleri doğrudan etkileyen düzeltmelere öncelik vermek için kullanın.