Nyomkövetési szám regisztrálása API-n keresztül: kérésmezők, fuvarozói kódok és válaszok
Nyomkövetési szám API-n keresztüli regisztrálásához küldjön hitelesített regisztrációs kérést, amely tartalmazza a küldemény nyomkövetési számát, valamint szükség esetén a fuvarozó azonosítóját. Ezután minden beküldött küldemény esetében vizsgálja meg a választ — ne csak a HTTP-állapotot —, és mentse el, hogy a regisztráció sikeres, sikertelen vagy továbbra is bizonytalan-e. A regisztráció elindítja a nyomkövetési munkafolyamatot; nem bizonyítja, hogy a fuvarozó beszkennelte a csomagot, illetve hogy a nyomkövetési események már elérhetők.
Ez az útmutató azoknak a fejlesztőknek szól, akik rendeléskezelő rendszert, raktári alkalmazást vagy ecommerce-platformot kapcsolnak össze nyomkövetési API-val. Konkrét integrációs példaként a 17TRACK szolgáltatást használja, és bemutatja, hogy mely részleteket kell ellenőrizni a kiválasztott API-verzió dokumentációjában.
Mire szolgál a regisztráció — és mire nem
A regisztrációs kérés jelzi a nyomkövetési szolgáltatásnak, hogy melyik küldeményt szeretné nyomon követni. Ez különbözik a szállítási címke megvásárlásától, a felvétel lefoglalásától vagy attól, hogy a fuvarozót küldemény létrehozására kéri. Egy tipikus integrációban a szállítási munkafolyamat először létrehozza a nyomkövetési számot, majd az alkalmazás később regisztrálja azt.
Alkalmazásában tartsa külön ezt a három eseményt:
- Küldemény létrehozva: a szállítási rendszere hozzárendelt egy nyomkövetési számot.
- Regisztráció elfogadva: a nyomkövetési szolgáltatás elfogadta a küldeményt nyomkövetésre.
- Nyomkövetési információ érkezett: a fuvarozó eseményei elérhetővé váltak a nyomkövetési szolgáltatáson keresztül.
Ne állítsa a rendelés állapotát „szállítás alatt” értékre pusztán azért, mert a regisztráció sikeres volt. Előfordulhat, hogy egy újonnan létrehozott címkét még nem szkennelt be fizikailag a fuvarozó. Az ügyfeleknek megjelenített küldeményállapotnak a nyomkövetési eseményeken, azok állapotleképezési szabályok szerinti értelmezésén kell alapulnia, nem a regisztrációs válaszon.
A 17TRACK-integrációk esetében kezdje a Tracking API overview oldallal, és használja a hivatalos API-dokumentációt végső forrásként a végpontok, meződefiníciók, hitelesítés és válaszkódok tekintetében. Az alábbi példák a regisztrációra összpontosítanak, nem az eredmények lekérésének vagy a frissítések fogadásának különálló feladataira.
Készítse elő a kérés mezőit az API-hívás megírása előtt
A leghasznosabb előkészítés egy kis mezőszerződés létrehozása a szállítási rendszer és a nyomkövetési integráció között. Döntse el, honnan származik az egyes érték, hiányozhat-e, és hogyan lesz érvényesítve.
| Mező vagy érték | Cél | Megvalósítási szabály |
|---|---|---|
| Nyomkövetési szám | Azonosítja a követendő küldeményt. | Karakterláncként tárolja és továbbítsa; őrizze meg a kezdő nullákat. |
| Fuvarozó azonosítója | Azonosítja a fuvarozót a nyomkövetési szolgáltató rendszerében. | A szolgáltató által dokumentált azonosítót használja, ne belső raktári kódot. |
| Belső hivatkozás | Összekapcsolja a regisztrációt a küldeményrekorddal. | Ha elérhető, használjon támogatott hivatkozási mezőt; ettől függetlenül őrizze meg saját adatbázis-leképezését. |
| További azonosítási adatok | Segíthetnek a küldemény azonosításában, ha a fuvarozónak a nyomkövetési számnál többre van szüksége. | Csak az adott integrációhoz és fuvarozóhoz dokumentált mezőket küldje el. |
| API-hitelesítő adat | Hitelesíti a hívó fiókot. | A szerveren tartsa, és zárja ki az alkalmazásnaplókból. |
A nyomkövetési számot azonosítóként kezelje
Soha ne alakítsa a nyomkövetési számot egész számmá. A numerikus átalakítás eltávolíthatja a kezdő nullákat, és nagy értékek egyes programozási környezetekben pontosságot veszíthetnek. Távolítsa el a véletlenül megmaradt környező szóközöket, de ne törölje az írásjeleket, és ne módosítsa a kis- és nagybetűket, kivéve, ha ezt a vonatkozó dokumentáció vagy a fuvarozó formátuma támogatja.
Az API-hívás előtt ellenőrizze a nyilvánvaló beviteli hibákat: üres karakterláncokat, váratlan sortöréseket és a nyomkövetési szám mezőjébe másolt rendelési számot. Ne alkalmazzon minden fuvarozóra egységes hossz- vagy karakterkorlátozást. Az egyik fuvarozóhoz megfelelő érvényesítési szabály elutasíthatja egy másik fuvarozó érvényes számait.
A rendelési hivatkozásokat tartsa külön a küldeményazonosítóktól
Egy rendelés több csomagot is tartalmazhat, egy csereszállítmány pedig újabb nyomkövetési számot eredményezhet. A regisztrációt küldemény- vagy csomagszinten modellezze, és ne feltételezzen rendelésenként egyetlen nyomkövetési számot.
Ha szolgáltató által támogatott címke- vagy hivatkozási mezőt használ, inkább átláthatatlan küldeményhivatkozást válasszon az ügyfél e-mail-címe vagy postacíme helyett. Saját adatbázisának kell maradnia a rendelések, küldemények, nyomkövetési számok és fuvarozó-leképezések közötti kapcsolat hiteles forrásának.
Válassza ki a megfelelő fuvarozói kódot
A fuvarozói kód nem feltétlenül univerzális iparági azonosító. A nyomkövetési platform által felismert érték eltérhet a szállítási szoftverben tárolt fuvarozónévtől. Még két, numerikus kódokat használó rendszer is különböző számokat rendelhet ugyanahhoz a fuvarozóhoz.
Tartson fenn explicit leképezést a szállítási szolgáltatása és a nyomkövetési szolgáltató fuvarozói azonosítója között. Szükség esetén különböztesse meg a fuvarozó regionális működését vagy szolgáltatását az átfogó márkától. A kizárólag megjelenített névre épülő leképezés kétértelművé válhat, ha a szállítási rendszerek aliasokat használnak.
- Ha a fuvarozó ismert: használja a dokumentált fuvarozói azonosítót, ha támogatott, különösen ott, ahol a nyomkövetési számformátumok átfednek.
- Ha a fuvarozó ismeretlen: automatikus felismerést csak a dokumentált mechanizmuson keresztül használjon. Ne feltételezze, hogy a kihagyás, az üres karakterlánc, a nulla és a null ugyanazt jelenti.
- Ha az eredmény helytelennek tűnik: ellenőrizze az eredeti címkét, a szállítási szolgáltatást és a leképezést, mielőtt ugyanazt a számot ismételten regisztrálná.
Az automatikus felismerés hasznos, de nem bizonyítja, hogy egy adott fuvarozó fizikailag birtokolja a küldeményt. Hasonlóképpen, az érvényes fuvarozói kód nem garantálja, hogy a megadott nyomkövetési szám az adott fuvarozóhoz tartozik.
A fuvarozói leképezéseket tegye konfigurálhatóvá, ne szórja szét őket az alkalmazás kódjában. Jegyezze fel, mikor ellenőrizte utoljára az egyes leképezéseket, és minden módosításkor szerepeltessen ismert küldeményt a regressziós tesztekben.
Példa: 17TRACK-regisztrációs kérés beküldése
Az alábbi példa a 17TRACK v2.2 regisztrációs végpontját, a 17token hitelesítési fejlécet és egyetlen nyomkövetési számot tartalmazó tömböt mutat be. Élesítés előtt erősítse meg, hogy ez a verzió és annak kérési követelményei megfelelnek a fiókjának és a hivatalos dokumentációnak. A nyomkövetési szám helyőrző, amelyet valódi küldeményazonosítóra kell cserélni.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Ez a minimális példa nem mutatja be a fuvarozó kiválasztását vagy a fuvarozóspecifikus kiegészítő mezőket. A regisztrációs dokumentáció alapján határozza meg, hogyan működik a fuvarozó felismerése a fuvarozói mező kihagyásakor, és hogy a küldeményének szüksége van-e további adatokra. Ha fuvarozót ad meg, használja a dokumentált carrier mezőt és az adott API-verzió által elvárt azonosítót.
Ezt a kérést szerveroldali környezetből futtassa. Ne ágyazza a tokent nyilvános webáruházba, böngészőszkriptbe vagy ügyfeleknek terjesztett mobilalkalmazásba. Helyi példa esetén kényelmes a környezeti változó használata; éles telepítéseknél alkalmazza szervezete titokkezelési vezérlőit.
A forgalom növelése előtt teszteljen egy ismert küldeményt, és vizsgálja meg a teljes választ. Ezután teszteljen érvénytelen bemenetet, valamint érvényes és érvénytelen elemeket egyaránt tartalmazó köteget. Ezek az ellenőrzések megmutatják, hogy az integráció ténylegesen kezeli-e az elemszintű eredményeket, nem csupán felismeri a HTTP-sikeres választ.
A választ három szinten olvassa
A megbízható válaszkezelő három külön kérdésre ad választ: elérte-e a kérés a szolgáltatást, elfogadta-e a szolgáltatás a műveletet, és mi történt az egyes küldeményekkel?
1. HTTP- és átviteli eredmény
A kapcsolati időtúllépés, a TLS-hiba vagy a megszakadt válasz nem feltétlenül jelzi, hogy a szerver feldolgozta-e a kérést. Ezt az eredményt tekintse bizonytalannak, amíg nem tudja egyeztetni. A sikeres HTTP-állapot megerősíti a sikeres HTTP-kommunikációt, de továbbra is meg kell vizsgálnia az alkalmazás válaszát.
2. Kérés szintű eredmény
Vizsgálja meg az API dokumentált felső szintű eredmény- és hibamezőit. A hitelesítési hibák, a hibás JSON és a fiókkorlátozások eltérő műveleteket igényelnek. Mentse el a szolgáltató eredeti hibakódját és üzenetét, ahelyett hogy minden hibát „a nyomkövetés nem érhető el” értékre egyszerűsítene.
Ne feltételezze, hogy egy numerikus alkalmazáskód jelentése megegyezik egy HTTP-állapotkód jelentésével. Jelentésük különböző rétegekből származik, ezért külön kell értelmezni őket.
3. Küldemény szintű eredmény
Kötegelt regisztráció esetén számoljon el minden beküldött elemmel. A válasz különbséget tehet az elfogadott és elutasított küldemények között; az elemzőnek a kiválasztott verzióhoz dokumentált pontos sémát kell követnie. Ne jelölje az egész köteget regisztráltként pusztán azért, mert egy elem sikeres volt.
A szolgáltatói válaszokat alakítsa át saját stabil alkalmazásállapotokra. Adatbázisa például használhatja az accepted, rejected és uncertain értékeket. Ezek javasolt belső állapotok, nem szó szerinti 17TRACK-válaszértékek. Tartsa elérhetően az eredeti szolgáltatói választ a megfelelő megőrzési és hozzáférési szabályok szerint, hogy a fejlesztők kivizsgálhassák az eltéréseket.
Egy hasznos regisztrációs rekord tartalmazza a belső küldeményazonosítót, a beküldött számot, a fuvarozó kiválasztását, a kísérlet időpontját, az API-verziót, az eredményt és a szolgáltató hibájának részleteit. A regisztrációs állapotot tartsa külön a kézbesítési állapottól.
Kezelje az újrapróbálkozásokat végtelen ciklus létrehozása nélkül
Az újrapróbálkozási szabálynak a hibától kell függenie, nem egyszerűen attól, hogy történt-e kivétel.
- Érvénytelen bemenet: javítsa a mezőt az újrapróbálkozás előtt. A változatlanul hibás kérés ismételt elküldése valószínűleg nem segít.
- Hitelesítési hiba: ellenőrizze a hitelesítő adatokat és a fiókbeállításokat. Kerülje ugyanazon sikertelen köteg ismételt beküldését.
- Frekvenciakorlátozás: kövesse a dokumentált korlátokat és az alkalmazandó újrapróbálkozási utasításokat. Az azonnali párhuzamos újrapróbálkozások helyett korlátozott visszaléptetést használjon.
- Ideiglenes szolgáltatáshiba: egy meghatározott kísérlet- és időkereten belül próbálkozzon újra.
- Beküldés utáni időtúllépés: a küldemény regisztrációs állapotát a dokumentált API-viselkedés alapján egyeztesse, mielőtt az első kísérletet sikertelennek tekintené.
- Duplikációval kapcsolatos válasz: ellenőrizze, hogy a küldemény már regisztrálva van-e, és megfelelően kapcsolódik-e az alkalmazás rekordjához.
Ne feltételezze, hogy a regisztráció idempotens, kivéve, ha a dokumentáció ezt a viselkedést meghatározza. Az alkalmazásoldali duplikációszűrés csökkenti a véletlen ismételt beküldéseket, de nem határozza meg a szolgáltató duplikátumkezelési szabályát.
Használjon a küldeménymodelljének megfelelő belső egyediségszabályt. A nyomkövetési szám önmagában nem feltétlenül elegendő állandó kulcs a fuvarozók és a hosszú megőrzési időszakok között. Őrizze meg a fuvarozói kontextust és saját küldeményazonosítóját, és dokumentálja a cserék és javított számok kezelését.
A regisztrációt a nyomkövetési frissítésektől külön figyelje
Az API-monitorozásnak különbséget kell tennie az integrációs hiba és azon küldemény között, amelyhez egyszerűen nem érkezett új fuvarozói esemény. Ezekhez eltérő felelősök és eltérő javítások szükségesek.
A regisztráció esetében figyelje az elfogadási és elutasítási számokat, a hibakategóriákat, a bizonytalan eredményeket, az újrapróbálkozási hátralékot és a válaszidőt. A későbbi nyomkövetésnél külön figyelje a frissítések fogadásának vagy lekérésének hibáit. Kerülje a numerikus riasztási küszöbök megadását addig, amíg nem ismeri a normál forgalmat és a szolgáltató dokumentált működési korlátait.
Egy praktikus éles környezeti ellenőrzésnek a következőkre kell választ adnia:
- Minden, nyomkövetésre váró küldeményhez tartozik regisztrációs rekord?
- Minden elfogadott regisztráció visszakövethető a megfelelő csomaghoz?
- Az elutasított elemek olyan személyhez kerülnek, aki kijavíthatja a mögöttes adatokat?
- A bizonytalan kéréseket egyeztetik, nem hagyják magukra és nem próbálkoznak velük végtelen ideig újra?
- Az ügyfeleknek megjelenített állapotok a küldeményeseményekből származnak, nem a regisztráció elfogadásából?
- A hitelesítő adatok és a szükségtelen személyes adatok ki vannak zárva a naplókból?
Ecommerce-műveleteknél az operatív átadás ugyanolyan fontos, mint maga az API-hívás. A fejlesztőknek kell kezelniük az átviteli és elemzési hibákat; a szállítási vagy teljesítési csapatoknak pedig képesnek kell lenniük a hibás címkék, fuvarozói leképezések és hiányzó küldeményinformációk kivizsgálására.
GYIK
Regisztrálhatok nyomkövetési számot az első fuvarozói szkennelés előtt?
A regisztráció és a fuvarozói szkennelés külön események. A szolgáltatás elfogadhat egy számot azelőtt, hogy a nyomkövetési események elérhetővé válnának, a saját érvényesítési szabályaitól függően. Az elfogadást ne értelmezze annak bizonyítékaként, hogy a fuvarozó átvette a csomagot.
Mindig meg kell adnom fuvarozói kódot?
Ez az API dokumentált felismerési viselkedésétől és az érintett küldeménytől függ. Ha a fuvarozó ismert, az explicit, helyesen leképezett azonosító csökkentheti a kétértelműséget. Ha ismeretlen, használja a dokumentált automatikus felismerési módszert a fuvarozói érték kitalálása helyett.
Miért adott vissza az API HTTP-sikert, miközben egy küldemény sikertelen volt?
A HTTP-kérés sikeres lehet, miközben az alkalmazás elutasít egy egyedi elemet. Olvassa el a felső szintű alkalmazáseredményt és a küldeményszintű eredményeket. Ez a különbség különösen fontos kötegelt kéréseknél.
Mit tegyek, ha a regisztrációs kérés időtúllépést szenved?
Az eredményt tekintse bizonytalannak. Előfordulhat, hogy a szerver feldolgozta a kérést, mielőtt a kapcsolat megszakadt. Ellenőrizze a szolgáltató dokumentált duplikációs viselkedését és az elérhető regisztrációs vagy nyomkövetési lekérdezési módszereket, majd egyeztesse vagy próbálja újra korlátozott szabályzat szerint.
A regisztráció automatikusan beállítja a nyomkövetési értesítéseket?
Ne feltételezze, hogy igen. A regisztráció, a nyomkövetés lekérése és a webhook konfigurálása külön integrációs feladatok. Ellenőrizze a vonatkozó dokumentációt, és tesztelje a teljes frissítési útvonalat, mielőtt ügyfélértesítésekhez támaszkodna rá.
Források
- 17TRACK API documentation — a regisztrációs végpontok, hitelesítés, kérési mezők, fuvarozói azonosítók, válaszsémák és hibakezelés referenciaanyaga. A megvalósítás részleteit igazítsa az élesített API-verzióhoz.
- 17TRACK Tracking API overview — hivatalos kiindulópont a nyomkövetési API-termékhez és a fejlesztői integrációs erőforrásokhoz.


