DCSA API szabványok – Az adatok hozzáférhetővé tétele a globális hajózási iparágban

Vezesse be most a DCSA API-kat: előnyben részesítse a foglalási, esemény- és nyomkövetési végpontokat, és 12 héten belül fogadjon el szabványosított adatcsomagokat a manuális érintkezési pontok ~40%-os csökkentése és a felhasználók közel valós idejű frissítéseinek biztosítása érdekében.

Kezdje három gyakorlati lépéssel: térképezze fel a meglévő interfészeket, hozzon létre egy vékony API réteget az EDI-t még mindig használó örökölt rendszerek számára, és indítson be pilótaként műhold alapú pozíció-adatfolyamokat az eseményrekordok gazdagítására. Ez a megközelítés megőrzi a jelenlegi műveleteket, miközben zökkenőmentes utat teremt az automatizált értesítések és a várható érkezési idő (ETA) korrekciók számára.

Mérje az eredményeket az érték bizonyítására: kövesse nyomon a foglalás visszaigazolásának átlagos idejét, az e-mail szálak százalékos csökkenését, az utazásonkénti állapotfrissítések gyakoriságát és az API-hívások felhasználásonkénti kihasználtságát. Ezek a metrikák megmutatják, hogyan alakítja át az átalakulás a beszerzést és a műveleteket az egész ellátási láncban, és hogyan dolgoznak együtt a csapatok a kikötési idő csökkentése és a hajókon belüli hibás útvonalak elkerülése érdekében.

Kövesse a világos terveket: futtasson egy három részből álló pilótát egy fuvarozóval, két szállítmányozóval és egy terminállal; tegyen közzé SLA- és verziószabályokat; biztosítson SDK-kat és példaadatcsomagokat; és ütemezzen be heti integrációs ellenőrzőpontokat. Ezek a konkrét lépések ma megismételhető eredményeket hoznak, és szabványosított adatokat tesznek elérhetővé a downstream rendszerek, az analitika és a partnerintegrációk számára.

DCSA API szabványok: Adathozzáférhetővé tétel a globális hajózásban – Konténerhajó érkezések és platformtelepítés összehangolása a digitalizáció érdekében

Vezessen be DCSA API szabványokat 12 hónapon belül a hajó ETA közzétételének, a kikötőhely-allokációnak és a platformtelepítésnek a szinkronizálásához, a manuális átadások csökkentésével és az automatikus működési frissítések feloldásával.

Írja elő az API-k számára az ETA és az állapotfrissítések 15 perces időközönkénti közzétételét, és támogasson eseményvezérelt webhookokat a fuvarozók, terminálok és ügynökök közötti azonnali kommunikációhoz. Integrálja az AIS és műholdas adatfolyamokat, hogy a pozíciót és a sebességet az útvonal mentén rögzítse, és átadja a kikötői rendszerekbe; szabványosítsa az adatcsomagokat ISO 8601 időbélyegekkel és UN/LOCODE-okkal az átviteli hibák elkerülése érdekében. Tervezzen évente három fő kiadást szemantikus verziószámozással és világosan közzétett időszakokat a visszafelé kompatibilitás érdekében, hogy a felhasználók kiszámítható frissítési ciklusokat kapjanak.

Optimalizálja a kikötőhelyeket a terminálüzemi rendszerek és a fuvarozó tervezési rendszerei működési adatfolyamainak egyesítésével; a Maersk és a terminálpartnerekkel végzett pilóták akár 20%-os csökkenést mutatnak a kikötőhely-várakozási időben és magasabb kikötőhely-kihasználtsági arányt mutatnak a manuális ütemezéshez képest. Használjon automatikus kikötőhely-átrendezési szabályokat és értesítési kommunikációt a kikötőhelyek közötti tétlen percek csökkentésére a hajómozgások között, javítva a teljesítményt, mint amit az ad-hoc üzenetek elérhetnek.

Tartalmazzon környezeti metrikákat minden API adatcsomagban: üzemanyag-fogyasztás, segédmotor órák és műholdról származó kibocsátási becslések. Adja át ezeket a rögzített metrikákat a kikötői és fuvarozói irányítási irányítópultoknak a CO2 per TEU kvantifikálásához és mérhető célok kitűzéséhez a fenntartható fejlesztés érdekében. Ezek lehetővé teszik a kezelők számára az útvonal- és kikötőhely-választások kibocsátási és működési költségek szempontjából történő összehasonlítását, lehetővé téve stratégiai döntéseket, amelyek jobb fenntarthatósági eredményeket hoznak.

Hozzon létre egy irányítási rendszert, amely a szabványkonformitást a szerződéses SLA-khoz köti, tisztázza a kommunikációs protokollokat, és kinevezi a felelősséget az adatminőségért. Támogassa a fejlesztői eszközöket, a homokozó környezeteket és a nyílt dokumentációt a fejlesztés és az új felhasználók bevezetésének felgyorsítása érdekében. Kövesse nyomon a KPI-kat – az érkezési idő pontossága, az automatikus átvitel sikességi aránya és a kézi beavatkozások csökkenése – és tegyen közzé negyedéves jelentéseket, hogy az érintettek mérni tudják a haladást és további integrációt tervezhessenek.

Működési Blueprint: A DCSA API-k alkalmazása a hajó érkezési adatok összehangolására

Implementáljon egy szabványosított érkezési állapot-egyeztetési folyamatot a DCSA Event, Voyage és Port Call API-k használatával, egy 24 órás SLA-val a hajóérkezések összehangolásához a fuvarozók, kikötők és terminálok között.

Három fő forrásból rögzítse az érkezési adatokat: fuvarozói manifesztumok a DCSA Voyage API-n keresztül, terminálrendszerek a Port Call API-n keresztül, és AIS adatfolyamok. Használja az Event API webhookjait a gyors frissítésekhez, és térjen vissza az 5 perces időközönkénti időszakos lekérdezéshez, ha a webhookok meghibásodnak. Címkézzön meg minden rekordot egy SOURCE (forrás) mezővel és egy capture_timestamp-tal az eredet megőrzése és az audit trail támogatása érdekében.

Normalizálja a bejövő adatcsomagokat egyetlen működési modellre a következő kanonikus mezőkkel: vessel_imo, voyage_id, eta_utc, ata_utc, berth, status_code, bunker_onboard_mt, estimated_fuel_burn_mt, customs_status és event_origin. Konvertáljon minden időt UTC-re, kerekítse a legközelebbi percre, és térképezze fel a különböző állapotkódokat egy 7-állapotú érkezési taxonómiára (tervezett, ETA frissítve, úton, megérkezett, mellett, kikötött, elindult).

Használjon determinisztikus illesztési szabályokat: pontos egyezés vessel_imo + voyage_id esetén, ha rendelkezésre áll; egyébként egyezés vessel_imo + eta ablak ±72 órán belül, egy pontozási funkcióval, amely súlyozza az Event API = 0,5, AIS = 0,3, termináli üzenetek = 0,2. Jelöljön meg egyezés hiányokat <0,6 pontszámmal emberi felülvizsgálatra. Határozzon meg egy eltérési küszöböt 60 percben az ETA és az ATA között; a nagyobb eltéréseket működési kivételként kezelje, amelyek növelhetik az üzemanyag-felhasználást és a vámkezelési várakozási időt.

Integrálja a kivételkezelést a felhasználói és a gépi interfészekbe egyidejűleg. Küldje el a magas súlyosságú kivételeket a fuvarozói működési csapatoknak API értesítéseken keresztül, és a termináltervezőknek UI irányítópultokon keresztül. Adjon meg a felhasználóknak javasolt korrekciós intézkedéseket: átirányítás alternatív kikötőhelyre, azonnali üzemanyag-kiigazítás kérése, vagy vámokmányok előzetes tisztázása. Rögzítse a kezelői döntéseket és a feloldás idejét későbbi elemzés céljából.

Mérje a teljesítményt ezekkel a KPI-kkal és célokkal: eltérés_arány (<5% 6 hónapon belül), átlagos összehangolási idő (<4 óra), SLA betartás (≥98%), üzemanyag-eltérés (a jelentett fedélzeti üzemanyag ±3%-a), és becsült gazdasági hatás érkezésenként. Használja az elmúlt három hónapot alapvonalnak, és futtasson egy októberi pilótát egy vezető ázsia-európai vonalon 500 rögzített érkezéssel a megtakarítások és a modell pontosságának érvényesítésére.

Alkalmazzon olyan átalakítási szabályokat, amelyek csökkentik az ismétlődő eseményeket és javítják a rendszerinterfészek kihasználtságát: dobja el az ismétlődéseket 2 percen belül ugyanattól a forrásból, egyesítse az azonos vessel_imo+event_origin+timestamp azonosítókat megosztó eseményeket, és tárolja a nyers adatcsomagokat az eredet nyomon követése érdekében. Dokumentáljon minden rekordot egy events_history tömbbel, hogy az elemzők megérthessék az utazás során az eltérésekhez vezető időzítési mintákat.

Kormányozza az adatfolyamokat verziós API szerződésekkel, partnerenkénti OAuth2 tokenekkel, csúcsüzemekhez igazított sebességkorlátokkal (Event előfizetésekhez ajánlott 1200 hívás/perc), és megőrzési szabályzatokkal (nyers adatok 12 hónapig, összesített adatok 36 hónapig). Fenntartson egy iparágszintű sémaregisztert, hogy a partnerek megegyezhessenek a mező szemantikában, és csökkenthessék a leképezési erőfeszítéseket a kezdeti integráción túl.

DCSA API	Rögzített kulcsmezők	Művelet	SLA / Cél
Event API	event_type, timestamp, location, vessel_imo, voyage_id	Valós idejű rögzítés, először webhook, 2 perces letapogatás	Webhook kézbesítés <30 másodperc; kétszer próbálkozás
Voyage API	voyage_id, eta_utc, planned_port_calls, cargo_manifest	Kanóikus utazási rekord feltöltése, manifesztum-eltérések jelzése	Szinkronizálás 4 óránként; frissítések 1 órán belül
Port Call API	port_call_id, berth, alongside_time, berthed_time, customs_status	Kikötői oldali állapot összehangolása, vámkényszerek megjelentetése	Frissítés <15 perccel a helyi esemény után
Reference Data API	locations, terminals, carrier_codes	Nevek/azonosítók feloldása, leképezési hibák csökkentése	Heti frissítés; forró javítások 24 órán belül
Location / AIS	lat, lon, sog, cog, timestamp	ETA/ATA kiegészítése, üzemanyag-fogyasztás becslése	Streaming késleltetés <60 másodperc

Futtasson egy három hónapos pilótát a következő lépésekkel: integrációk telepítése egy vezető vonalon októberben, 500 múltbeli és élő érkezés adatainak befogadása az egyeztetési modell képzéséhez, szabályok iterálása az álpozitívumok <8%-ra csökkentése érdekében, és a gazdasági hatás havi mérése. Jelentse az eredményeket a vámpartnereknek a tisztázási ablakok rövidítésére, és az OPS csapatoknak a kikötési idő csökkentésére, amely üzemanyag-fogyasztást eredményez. Használja a pilótából származó tanulságokat az iparágon keresztüli terjesztéshez és az interfészek skálázásához, hogy a felhasználók az egyes szilin túli összehangolt érkezési adatokat lássanak.

Azonosítsa a kritikus végpontkészletet a hajóérkezés összehangolásához: szükséges DCSA API-k és adatcsomagok

Implementálja ezt a minimális végpontkészletet a hajóérkezések összehangolásához: Port Call (voyage/eta), Event Notifications (webhook), Transport/Movement, Booking, Equipment/Container, Terminal Interface, Reference/Location és Party API-k.

Port Call adatcsomag: tartalmazza a voyageId, vesselIMO, vesselName, voyageNumber, portCode (UN/LOCODE), scheduledArrival (ISO-8601), estimatedArrival, scheduledDeparture, berthingWindowStart, berthingWindowEnd, berthCode, draftMeters, nextPortCode és sequenceVersion mezőket. Használjon numerikus mezőket a TEU és a merülés számára, és biztosítson sourceSystem és lastUpdatedBy mezőket. Például: scheduledArrival: "2026-03-10T14:00:00Z". Az első szinkronizáláskor küldjön teljes utazási pillanatfelvételt, utána pedig inkrementális változásokat.

Event Notifications adatcsomag: eventType, eventTimestamp, relatedId (voyageId, containerNumber, bookingReference), locationCode, statusCode, details, sequenceNumber, és idempotencyKey. Küldjön application/vnd.api+json JSON:API formátumú POST kéréseket a előfizető végpontokra, próbálkozásokkal/visszaeséssel és exponenciális ablakokkal. Jelölje meg az eseményeket automatikusnak vagy manuálisnak, és tartalmazza az eventProvenance mezőt az eseményt generáló rendszer azonosításához.

Transport/Movement adatcsomag: transportId (GUID), shipmentId, bookingReference, carrierBookingReference, billOfLadingNumber, originUNLOC, destinationUNLOC, mode, containers:[{containerNumber,sizeType,status}], cargoType, weightKg, loadedOnVoyageId, és currentStatusTimestamp. Adja meg a manifestReference és estimatedOnboardTime mezőket, ha rendelkezésre állnak, a terminál tervezésének segítése érdekében.

Booking adatcsomag: bookingReference, shipperPartyId, consigneePartyId, commodities, totalTEU, containerRequirements, portCutoffTimes:{terminalCutoff,gateCutoff,docsCutoff} időzónával, requestedPickupDate, és confirmedStatus. Használja ezeket az értékeket a terminál foglalások és a kinevezések vezérlésére; tárolja a bookingVersion értéket az egyeztetéshez.

Equipment/Container adatcsomag: containerNumber, isoSizeType, tareKg, grossKg, currentLocationCode, lastFreeTime, containerStatus, és sealInfo. Csatlakoztassa ezeket a rekordokat a transportId és voyageId mezőkhöz, hogy a terminálrendszerek és az ügyfelek egyetlen igazságforrást lássanak.

Terminal Interface adatcsomag: terminalCode, berthCode, availableCraneCount, plannedBerthStart, plannedBerthEnd, gateSlots (időbélyeg ablakok), yardOccupancyPercent, és serviceLevels. Tervezze meg a modellt úgy, hogy a terminálok visszaküldhessék a kikötőhely-megerősítéseket és a foglalásokat a Port Call és a Booking tartományokba.

Reference és Party adatcsomagok: partyId (fuvarozó, terminál, szállító, rendeltetési hely), names, roles, contactMethods, és locationList. Adjon meg UN/LOCODE-ot és szabványosított szerepkör-kifejezéseket a hajózásban részt vevő rendszerek halmaza feletti következetes illesztés támogatása érdekében.

Protokoll és implementációs szabályok: fogadjon el application/json:API tartalomtípust, követeljen RFC3339 időbélyegeket, kényszerítse a kötelező kulcsokat, amelyek fent felsoroltak, támogassa a PATCH-et az inkrementális változásokhoz, és verziózza a végpontokat. Használjon webhookokat az automatikus eseménykézbesítéshez, és biztosítson pull API-t a teljes szinkronizáláshoz. Sebességkorlátozási útmutatás: 5 kérés/mp/kliens a szinkronizálási végpontokhoz és 1000 webhook esemény/perc 429 válaszokra történő visszaeséssel.

Működési ajánlások: gyakrabban küldjön ETA frissítéseket, ahogy a hajó közelebb ér – például 15 percenként, ha >48 órán belül van, 5 percenként 6 órán belül, és azonnal a tényleges érkezéskor/kikötéskor. Tartalmazzon egy sequenceNumber és lastProcessedEvent mezőt a válaszokban, hogy a fogyasztó rendszerek ismétlődések nélkül folytathassák és fenntarthassák az idempotenciát.

Monitorozás és átvétel: tegyen közzé metrikákat a deliverySuccessRate, averageLatencyMs, és processingErrors pontokra végpontonként. Futtasson egy átvételi ellenőrzőlistát, amely magában foglalja a séma validálást, a webhook próbálkozásokat, az autentikációt (mTLS vagy OAuth2), és a vége-végig teszteket a fuvarozó, terminál és ügyfél rendszerek között. Kinevezzen egy keresztfunkcionális csapatot ezeknek a tételeknek a fejlesztésére és monitorozására az első sprint során.

Leképezési és adatmodell útmutatás: a helyi mezőket kanonikus nevekre (voyageId, portCode, scheduledArrival) képezze le egy integrációs rétegben; őrizze meg az eredeti forrásazonosítókat egy sourceRef tömbben. Használjon egy changeLog modellt, amely rögzíti, hogy ki mit és mikor változtatott meg, hogy vezérelje a downstream egyeztetést és az ügyfél értesítéseket.

Biztonság és irányítás: követeljen jogkör tokent végpontonként, és korlátozza a szerepkör által visszaküldött adatokat. Rögzítse a beleegyezési és szerződéses feltételeket az adatmegosztáshoz, és tartalmazzon auditTrail bejegyzéseket a továbbított eseményekhez, hogy az ügyfelek és a terminálok igazolni tudják az eredetet.

Kezdje az implementációt egy priorizált ellenőrzőlistáról: 1) Port Call és Event webhookok, 2) Transport és Booking szinkron, 3) Terminal interface és Equipment, 4) Reference és Party konszolidáció, 5) monitorozás és átvételi tesztek. Ez a sorrend csökkenti az integrációs munkát, mint az ad-hoc megközelítések, és lehetővé teszi a csapat számára, hogy heteken belül megvalósítsa a látható érkezési összehangolást a szállítmányokhoz.

A kikötői események kanonikus érkezési idővonalba való fordítása: a leképezési szabályok és az időbélyeg precedencia

Alkalmazzon egy ötlépéses leképezési és időbélyeg precedencia szabálykészletet egyetlen kanonikus érkezési idővonal generálásához hajónként és szállítmányonként: leképezze a nyers eseményeket kanonikus fázisokra, válassza ki minden fázishoz a legmagasabb prioritású időbélyeget, csatoljon forrásbizalmat, és jelölje meg az emberi felülvizsgálatra váró konfliktusokat.

Határozza meg a kanonikus fázisokat a következőként: megközelítés (hajó 24 NM-en belül a kikötőtől), pilotOnBoard, alongside/berth, startCargoOps (első konténer mozgás fogadása), completeCargoOps, és departed. Képezze le a forráseseményeket ezekbe a fázisokba: AIS pozíció jelentések, pilóta/kikötői hatósági manifesztumok, terminál üzemeltetési rendszer (TOS) kikötőhely események, fuvarozói műveleti üzenetek (SOC/COC), kapu be/ki konténer szkennelések, és hajónapló bejegyzések. Tároljon egy kanonikus időbélyeget fázisonként, és őrizze meg az eredeti eseménylistákat az audit és az egyeztetés céljából.

Időbélyeg precedencia (legmagasabból a legalacsonyabbba): 1 – Kikötői hatóság / pilóta időbélyegek a pilotOnBoard és a kikötői engedélyekhez (hiteles). 2 – Terminál üzemeltetési rendszer időbélyegek az alongside/berth és a startCargoOps számára. 3 – Terminál/konténer kapu szkennelések a fogadás és a konténer mozgások számára. 4 – Fuvarozói működési üzenetek (ETA/ATA, SOC/COC) a tervezett és kezelő által megerősített mérföldkövekhez. 5 – AIS-ből származó időbélyegek (pozíció átlépése X-NM-en, kikötőben megállva) az automatikus észleléshez. Mindig normalizáljon UTC ISO 8601 formátumra, és csatoljon forrásazonosítót és bizalmi pontszámot.

Konfliktusok feloldása determinisztikus szabályokkal: ha magasabb prioritású időbélyeg létezik, használja azt a kanonikus fázishoz. Ha az alacsonyabb prioritású adatok egy magasabb prioritású időbélyeget megelőznek a T1 = 30 perc küszöbön túl kikötéshez/mellett vagy T2 = 120 perc küszöbön túl megközelítéshez/ETA esetén, tartsa meg mindkét időbélyeget, jelölje meg a kanonikus fázist "gyanúsnak", és állítsa be a sourceConfidence értéket = low. Ha az AIS korábban jelzi a kikötő melletti tartózkodást, mint a TOS, kevesebb mint 30 perccel, részesítse előnyben a TOS-t, de rögzítse az AIS-t támasztó bizonyítékként. Hiányzó magasabb prioritású adatok esetén emelje fel a következő elérhető forrást, de rögzítse a promotionReason és az expectedAccuracy (%) értéket a forrás típusa alapján.

Óra- és időzóna-szabályozás implementálása: követelje meg minden forrástól az időbélyegek UTC-ben történő küldését. Ismert óraeltérés esetén alkalmazzon forrás-specifikus eltolásokat, amelyeket történelmi összehasonlításokból számítottak ki (tárolja az utolsó eltolást és szórásnégyzetet). Helyezze érvénytelennek a 7 napnál régebbi időbélyegeket az érkezési fázisokhoz, kivéve, ha aláírt kikötői hatósági rekord kíséri őket. Alkalmazzon automatikusan legfeljebb 60 perc korrekciót; a nagyobb korrekciók manuális felülvizsgálatot igényelnek.

Ajánlott kanonikus eseményséma (példa mezők): eventType, canonicalTimestampUTC, sourceType, sourceId, sourceConfidence(0-1), rawTimestamps[lists], berthId, portUNLocode, vesselIMO, containerCount, affectedContainers[], phaseDurationMinutes. Használja ezeket a mezőket KPI eredmények előállításához, mint például az ETA-eltérés csökkenése, korábbi ügyfélértesítések és mérhető mozgásidő csökkenés konténerenként.

Működési útmutató a felhasználók és szövetségek számára: integrálják ezeket a szabályokat a fuvarozói és terminál API-kba, hogy következetes üzeneteket lehessen küldeni a DCSA-hoz igazított végpontokon keresztül. Osszák meg az átfogalmazott szabályokat a szállítmányozókkal és az ügyfelekkel, hogy a rendszerek automatizált munkafolyamatokat bővíthessenek és optimalizálhassák a kikötőhely tervezést. Kövessen nyomon öt bevezetési metrikát: a kanonikus forrással rendelkező fázisok százaléka, az átlagos emelési gyakoriság, a gyanús jelzések 24 órán belüli feloldásának százaléka, a kanonikus és a fuvarozó ETA közötti átlagos eltérés, valamint a korai/késői értesítések csökkenése. Ezen leképezések digitalizálása növeli az iparágak közötti láthatóságot, segít optimalizálni a konténer mozgásokat, és túlmutat a töredezett időbélyegeken, így a fuvarozók, terminálok és szállítmányozók korábbi, megbízhatóbb szállítási információkat kapnak a konténer szintű átvételek és eredmények mellett.

Érvényesítse a fuvarozói és konténerazonosítókat az adatok befogadása előtt: ellenőrző számjegyek, kódlisták és elutasítási kezelés

Érvényesítse a konténerszámokat és a fuvarozói kódokat az API átjárónál az ISO 6346 ellenőrző számjegy logikája és a hiteles kódlisták használatával, mielőtt bármilyen downstream befogadásra kerülne.

• Pontos konténer formátum és ellenőrző számjegy ellenőrzés

  • Csak 11 karakteres ISO 6346 bejegyzéseket fogadjon el: tulajdonos kód (3 betű) + berendezés kategória (1 betű, általában U/J/Z) + sorozatszám (6 számjegy) + ellenőrző számjegy (1 számjegy).
  • Számítsa ki az ellenőrző számjegyet: képezze le a betűket numerikus értékekre (A=10, B=12, C=13 ... Z=38, 11, 22, 33 kihagyásokkal), szorozza meg az egyes karakterértékeket 2^pozícióval (a pozíció 0 az első karakterre vonatkozik), összegezze, vegye a maradékot 11-vel; ha a maradék = 10, akkor az ellenőrző számjegy = 0. Hiba esetén azonnal utasítsa el.
  • Utasítson el a hibás hosszúságú, nem ASCII betűket, a tulajdonosi kódban vezető nullákat, vagy a 000001–999999 tartományon kívüli sorozatszámokat tartalmazó bejegyzéseket; naplózza a pontos hiba okát és forrását (API hívásazonosító vagy táblázat sor).

• Fuvarozói kód validálás és kódlista kezelés

  • Hasonlítsa össze a fuvarozói azonosítókat egy hiteles nyilvántartással (BIC a tulajdonosoknak, SCAC az USA műveleteknek vagy az Ön által elfogadott fuvarozói listával). Ismeretlen kódokat karanténba helyezzen, amíg fel nem oldják őket.
  • Valós idejű lekérdezést implementáljon, ha elérhető az internetkapcsolat; vészhelyzet esetén használjon aláírt, időbélyeggel ellátott gyorsítótárazott pillanatfelvételt, ha offline. Engedélyezze a gyorsítótár érvényességét egy konfigurálható ablakban (alapértelmezett 24-72 óra), és minden eseményben rögzítse a pillanatfelvétel verzióját.
  • Alkalmazzon leképezést szövetségek és hajót üzemeltető partnerek számára: tartson fenn egy kanonikus fuvarozó-üzemeltető fuvarozó táblát, amelyet az APMS és a downstream rendszerek használnak; frissítse a leképezést minden szövetség változásakor, és rögzítse, ki alkalmazta a felülírást.

• Előzetes befogadási ellenőrzések táblázatokhoz és kötegelt betöltésekhez

  • Biztosítson egy kliens-oldali validátort (Excel makró vagy könnyűsúlyú JS), amely feltöltés előtt jelöli a sorokat, és visszaad egy CSV-t a hibás sorokról hiba kódokkal; ez csökkenti a manuális javításokat és felgyorsítja a régi táblázatok digitalizálását.
  • Kötegelt befogadáshoz futtasson egy gyors előszűrést, amely elválasztja az érvényes, lágy hiba (ismeretlen fuvarozó) és a kemény hiba (ellenőrző számjegy eltérés) sorokat. Csak az érvényes sorokat fogadjon be; adjon vissza egy strukturált elutasítási fájlt, amelyet a beküldő javítások után újra feltölthet.

• Elutasítási kezelési irányelv és hiba taxonómia

  1. Használjon szabványosított hiba kódokat, hogy az integrációk automatikusan tudjanak intézkedni:
     • ERR01 – FORMAT_INVALID (hosszúság/karakterkészlet)
     • ERR02 – CHECKDIGIT_MISMATCH
     • ERR03 – CARRIER_UNKNOWN
     • ERR04 – MAPPING_OVERRIDE_REQUIRED
  2. Határozzon meg automatikus műveleteket kódonként:
     • ERR02: kemény elutasítás, értesítse a küldőt, blokkolja a javításig.
     • ERR03: lágy karantén, próbálkozzon lekérdezni másodlagos szolgáltatásokból legfeljebb 24 órán keresztül, majd escaláljon a fuvarozó műveletekhez, ha még mindig nincs megoldva.
     • ERR04: csak aláírt felülírással fogadjon el jogosult felhasználótól; naplózza az audit trail-t.

• Monitorozás, KPI-k és SLA-k

  • Kövesse nyomon az elutasítási arányt, az átlagos javítási időt (MTTR) és a karanténba helyezett rekordok SLA-n belüli feloldásának hányadát. Célok: elutasítási arány <0,1% a befogadott mennyiséghez képest, és MTTR <4 óra az operatív kikötőkhöz/érkezésekhez.
  • Műszerezzen irányítópultokat, amelyekTrendeket és tüskék észlelését mutatják, így a műveletek gyorsabban észlelik a fuvarozói listák változásait vagy a tömeges táblázathibákat, mint a manuális felülvizsgálat.

• Integrációs pontok és működési biztosítékok

  • Ellenőrizze az adatokat a vám-, APMS-, üzemanyag- és üzemanyag-rendszereknek történő küldés előtt. A helytelen azonosítók számlázási eltéréseket (üzemanyag), vámkésedelmeket és hibásan útvonalra küldött érkezéseket okoznak.
  • Ha egy külső rendszer (APMS, terminálrendszer) frissítéseket küld, csatolja a validálási pillanatfelvétel verzióját, hogy a fogadók tudják, melyik kódlista állította elő a döntést.
  • Használjon biztonságos internetes vagy L-sávos műholdas kapcsolatokat, ahol a parti kapcsolat megbízhatatlan; az offline érvényesítésnek továbbra is rögzítenie kell a gyorsítótár kódlistájának azonosítóját, amíg az internet szinkron be nem fejeződik.

• Irányítás, frissítések és fejlesztési gyakorlatok

  • Automatizálja az éjszakai kódlista-húzásokat, és engedélyezze a manuális kényszerítést a azonnali változásokhoz; naplózza, hogy ki végezte a manuális frissítéseket és miért. Értesítse a downstream csapatokat minden olyan változásról, amely befolyásolja a fuvarozói leképezéseket vagy specifikációkat.
  • Tartalmazzon egységteszteket az ellenőrző számjegy logikájához a CI/CD-ben, és egy tárat valós világú teszt vektorokkal (érvényes és érvénytelen számok) a fejlesztés és a QA során.
  • Tartson fenn egy nyilvános változásnaplót, hogy a partnerek tudják, mikor változtak a validálási szabályai vagy listái; linkelje a változásnapló azonosítóját az esemény metaadataiba az áttekinthetőség érdekében (lásd a leképezést itt a legutóbbi 30 frissítéshez).

• Működési példák

  • Forgatókönyv: Egy ügynöktől származó táblázat feltöltése jelenleg 5000 sort küld. Futtasson előszűrést: 4990 érvényes, 8 ERR02, 2 ERR03. Adjon vissza egy elutasítási CSV-t sor azonosítókkal, hiba kódokkal és javasolt javításokkal; azonnal fogadja be a 4990 sort az érkezési határidők betartása érdekében.
  • Forgatókönyv: Egy fuvarozói szövetség éjjel változtatja meg az előtagokat. Alkalmazzon leképezési felülírást, futtasson egyeztetést az elmúlt 48 óra rögzített érkezései ellen, és futtasson egy korrigált adatfolyamot a vám- és eBOL rendszereknek a downstream eltérések elkerülése érdekében.

• Gyakorlati ellenőrzőlista a mai implementációhoz

  1. Telepítse az ellenőrző számjegy validálást az API peremén.
  2. Integráljon egy hiteles kódregisztert valós idejű és gyorsított módokban.
  3. Hozzon létre elutasítási CSV sablonokat táblázat felhasználók számára, és automatizálja az előszűrést a feltöltés UI-ban.
  4. Állítson be KPI riasztásokat az elutasítási tüskékre, és őrizze meg az audit trail-t minden manuális list modificación.

Ezeknek a lépéseknek a követése csökkenti az álpozitívumokat, felgyorsítja az érkezések feldolgozását, összehangolja az adatokat a vám- és APMS-áramokkal, javítja az üzemanyag/számlázás pontosságát, és lehetővé teszi a csapatok számára a következetes, auditálható befogadást, miközben továbbra is figyelembe veszi a valós működési változásokat és a szövetség által vezérelt leképezéseket.

Hitelesítés és csatlakozás a DCSA szolgáltatásokhoz: OAuth folyamatok, API kulcsok és homokozó-tól-éles környezetig lépések

Használjon OAuth 2.0 kliens hitelesítő adatokat gépek közötti integrációkhoz és Authorization Code PKCE-vel minden olyan alkalmazáshoz, amely felhasználó nevében jár el; tárolja az ügyfél titkait egy titkos kulcs kezelőben, és korlátozza a jogköröket a minimálisan szükségesre.

Követeljen TLS 1.2+-t minden internetes híváshoz, érvényesítse az igazolásokat, és kényszerítse a TLS rögzítést mobil alkalmazásokhoz. Nyilvános ügyfelek esetén implementálja a PKCE-t és a rövid életciklusú hozzáférési tokeneket frissítő tokenekkel, amelyek első használatkor megújulnak; bizalmas ügyfelek esetén részesítse előnyben a kölcsönös TLS-t, ha a szolgáltató támogatja.

Regisztráljon minden alkalmazást a DCSA fejlesztői portálon egy egyedi client_id és egy környezet-specifikus titok vagy kulcs segítségével. Használjon homokozó hitelesítő adatokat a fejlesztéshez és teszteléshez, jelölje meg azokat a teszteket, amelyek ebl-eket vagy vámfolyamatokat érintenek, és dokumentálja, hogy mely API verziókat használja az integrációja, hogy tisztán lássa a törő változásokat.

Amikor homokozó tokeneket kap, automatizálja a token gyorsítótárazást és megújítást: kérjen új tokent a token élettartamának 90%-ánál, próbálkozzon újra a sikertelen token cserékkel exponenciális visszaeséssel, és naplózza a token hibákat egy biztonságos audit streambe a titkok konzolra nyomtatása helyett. Egy okos helyi proxy, amely beilleszti a tokeneket és kényszeríti a sebességkorlátokat, csökkenti a fejlesztési súrlódást.

Használjon API kulcsokat csak alacsony kockázatú telemetriához vagy partnerazonosításhoz, ahol az OAuth nem áll rendelkezésre; soha ne használjon API kulcsokat a felhasználói hitelesítés helyettesítésére. Kezelje az API kulcsokat titokként, forgassa negyedévente, és blokkolja azokat a kulcsokat, amelyek rendellenes hívási mintákat mutatnak.

Kövesse ezt a homokozó-tól-éles környezetig terjedő ellenőrzőlistát: 1) szerződés és DCSA bevezetés befejezése, 2) biztonsági és API megfelelőségi tesztek teljesítése homokozóban, 3) éles támogatási kapcsolattartó és SLA biztosítása, 4) audit logok és manuális visszaállítási terv bemutatása, 5) mTLS tanúsítványok benyújtása, ha szükséges, és 6) éles átviteli ablak ütemezése fuvarozókkal és partnerekkel. Ha egy fuvarozó, mint a Hapag-Lloyd, vagy egy vámkapu októberi bevezetési ablakot kér, koordináljon időben, és erősítse meg, ki küldi a végleges visszaigazolási bizonylatokat.

Műszerezzen minden éles hívást korrelációs azonosítókkal, kövesse a kérés/válasz időket, és rögzítse a HTTP állapotot és az üzleti szintű bizonylatokat az EDI-vel egyenértékű folyamatokhoz, mint például az ebl-ek és a foglalási megerősítések. Címkézze az eseményeket partner, szállítmányozó, fuvarozó és működési hely szerint, hogy a downstream csapatok tudjanak szűrni a vám-, környezetvédelmi jelentési vagy üzemanyag-követési követelmények szerint.

Tartsa minimálisan a migrációs manuális lépéseket: automatizálja az igazolás feltöltést, az ügyfél regisztrációt és a jogkör jóváhagyásokat, ahol lehetséges, és tartson fenn egy ellenőrzőlistát, amely megmutatja, hogy mely partnerek vannak csatlakoztatva, és melyek igényelnek még manuális bevezetést. Egyetlen automatizált füstteszt, amely lekérdez egy foglalást és érvényesít egy nyomon követett bizonylatot, csökkenti az átviteli kockázatot.

A fejlesztés során emulálja a partner viselkedést: építsen egy stub-ot, amely valósághű webhook adatcsomagokat küld, és érvényesíti az Ön nyugtáit, beleértve az ebl elfogadásokat és a fogadási üzeneteket. Futtasson terhelési teszteket a homokozón, amelyek szimulálják a csúcs működési forgalmat fuvarozóktól, szállítmányozóktól és vámszolgáltatóktól, hogy beállíthassa az újrapróbálkozásokat és a párhuzamosságot.

Monitorozza a használatot és az üzleti KPI-kat az éles go-live után: kövesse nyomon a token csere arányokat, a sikertelen hitelesítési hívásokat, az átlagos hívási késést és a partnereknek nem kézbesített nyugták számát. Használja ezeket a metrikákat a szállítmányozókat, fuvarozókat és az időben történő EDI/EBL frissítésekre, valamint a környezeti vagy üzemanyag-jelentésekre támaszkodó iparágakat közvetlenül érintő javítások priorizálásához.