Skip to main content
AcasăBlogGhiduriTestarea unei integrări cu Tracking API în dezvoltare: Sandbox, numere de testare, webhook-uri simulate

Testarea unei integrări cu Tracking API în dezvoltare: Sandbox, numere de testare, webhook-uri simulate

17TRACK

Pentru a testa o integrare API de urmărire în dezvoltare, utilizați trei metode complementare: un sandbox al furnizorului sau numere de test documentate pentru comportamentul API, fixture-uri locale pentru scenarii de expediere repetabile și webhook-uri simulate pentru endpointul de recepție. Apoi efectuați o verificare live controlată pentru a valida componentele pe care simulările nu le pot demonstra, inclusiv acreditările, configurarea abonamentului și livrarea efectivă a evenimentelor.

Testarea unei integrări API de urmărire în dezvoltare, sandbox și numere de test

Acest ghid este destinat dezvoltatorilor care conectează urmărirea expedierilor la o platformă de comerț electronic, un sistem de gestionare a comenzilor, un ERP sau un serviciu de notificare a clienților. Scopul nu este doar să primiți un răspuns API reușit. Trebuie să demonstrați că actualizările de urmărire produc starea corectă a comenzii fără mesaje duplicate, evenimente pierdute sau contactarea accidentală a clienților reali.

Separați comportamentul furnizorului de comportamentul aplicației

O integrare de urmărire are cel puțin două granițe: solicitările trimise de aplicația dvs. furnizorului și actualizările pe care aplicația dvs. le primește sau le preia ulterior. O solicitare reușită la prima graniță nu demonstrează că a doua graniță funcționează.

Construiți planul de testare în jurul acestor granițe, în loc să vă așteptați ca un singur număr de urmărire de test să verifice întregul sistem.

Metodă de testareCe poate validaCe nu poate demonstra singură
Sandbox al furnizoruluiFormatele de solicitare acceptate, autentificarea și comportamentul simulat descris de furnizorDisponibilitatea datelor transportatorilor din producție sau comportamentul livrării în producție
Numere de test documentateScenariile specifice atribuite acelor numereAlte stări, transportatori sau secvențe de webhook-uri
Fixture-uri locale și mock-uri APIParserul, regulile de mapare, persistența și gestionarea erorilorDacă furnizorul real acceptă solicitările sau emite aceeași structură de date
Solicitări webhook simulateGestionarea endpointului, validarea, deduplicarea și efectele ulterioareConfigurarea callback-ului la nivelul furnizorului sau reîncercările reale de livrare
Test live controlatConectivitatea reală și fluxul observat al expedieriiFiecare eroare rară, excepție sau secvență de livrare

Abordare recomandată: faceți testele locale deterministe, utilizați testarea acceptată de furnizor acolo unde este disponibilă și rezervați expedierile live pentru confirmarea conexiunii dintre sisteme.

Confirmați contractul furnizorului înainte de a scrie fixture-uri

Începeți cu documentația oficială pentru versiunea API pe care intenționați să o utilizați. Confirmați URL-ul de bază, metoda de autentificare, cerințele de înregistrare, schema răspunsului, configurarea webhook-ului și orice facilități de testare documentate. Nu presupuneți că există un sandbox separat doar pentru că furnizorul oferă un API.

Pentru o integrare 17TRACK, utilizați pagina 17TRACK Tracking API și documentația oficială API ca puncte de pornire. Verificați acolo specificațiile aplicabile pentru solicitări și callback-uri înainte de a construi exemple specifice furnizorului. Exemplele de mai jos sunt în mod deliberat fixture-uri gestionate de aplicație, nu reprezentări ale schemei API 17TRACK.

Clarificați aceste întrebări înainte de a conecta codul de dezvoltare la un cont extern:

  • Sunt acreditările pentru dezvoltare și producție separate și la ce mediu oferă acces fiecare acreditare?
  • Un sandbox acceptă callback-uri sau doar testarea solicitare-răspuns?
  • Sunt numerele de test documentate și ce rezultate exacte produc?
  • Înregistrările sau alte solicitări de test pot consuma cota contului sau crea înregistrări persistente?
  • Ce reguli documentate există pentru autentificarea callback-ului, confirmare, timeout și reîncercare?
  • Ce identificatori conectează o înregistrare de urmărire, o expediere, un transportator și un eveniment callback?

Dacă comportamentul de testare nu este documentat clar, solicitați furnizorului să îl confirme. Între timp, continuați să testați logica proprie de procesare cu mock-uri. O capacitate de sandbox neconfirmată reprezintă o incertitudine de planificare, nu o dovadă că furnizorul nu dispune de acea capacitate.

Construiți un mediu de dezvoltare izolat

Utilizați o bază de date separată sau un tenant izolat, secrete separate și comenzi sintetice. Direcționați e-mailurile, mesajele SMS și alte notificări către destinații de test sau către un sistem de captare a notificărilor. O expediere marcată ca livrată într-un fixture nu trebuie să declanșeze un mesaj către un cumpărător real.

Adăugați un marcator explicit de mediu în înregistrările și jurnalele interne. Păstrați acreditările furnizorului pe server, în afara controlului versiunilor, și eliminați secretele din capturile solicitărilor. Dacă este necesar acces public temporar pentru callback-uri, expuneți doar ruta de dezvoltare prevăzută și păstrați controalele de autentificare.

Creați un set mic de comenzi cunoscute înainte de a trimite evenimente. Includeți două expedieri atașate unei singure comenzi și, dacă aplicația dvs. acceptă acest lucru, aceeași secvență de număr de urmărire în contexte diferite de transportator. Aceste cazuri scot la iveală presupunerea că un număr de urmărire identifică întotdeauna singur o înregistrare comercială unică.

Definiți în avans efectul așteptat al fiecărui test: starea expedierii, asocierea comenzii, intrările din cronologie, numărul notificărilor și înregistrarea de audit. Astfel, o demonstrație devine o aserțiune care poate reuși sau eșua.

Utilizați numerele de test numai în scopul documentat

Un număr de urmărire are două roluri distincte în testare. Poate fi o intrare utilizată pentru validarea înregistrării și poate identifica o expediere care produce evenimente de urmărire. Un număr care trece validarea formatului nu oferă neapărat un istoric util al evenimentelor.

Când sunt disponibile numere oficiale de test

Notați scenariul indicat de furnizor alături de fiecare număr. Un număr documentat pentru o expediere livrată nu trebuie presupus că simulează o excepție, o returnare sau o tentativă de livrare eșuată. Verificați și dacă rezultatul este fix, se schimbă în timp sau necesită selectarea unui anumit transportator.

Păstrați aceste numere într-o configurație dedicată testelor de integrare. Nu le împrăștiați în testele unitare, unde schimbarea comportamentului extern ar putea face nesigure testele altfel deterministe.

Când numerele oficiale de test nu sunt confirmate

Utilizați identificatori sintetici în propria aplicație și simulați granița furnizorului. Nu inventați niciodată un număr cu aspect plauzibil presupunând că este rezervat testării: acesta ar putea corespunde unei expedieri reale.

Pentru validarea live, utilizați expedieri pe care le controlați și pe care sunteți autorizat să le accesați. Evitați copierea numerelor de urmărire din capturi de ecran publice sau conversații cu clienții. Tratați istoricul expedierilor ca fiind potențial sensibil, deoarece poate conține locații, marcaje temporale și informații despre livrare.

O expediere mai veche, livrată, poate ajuta la validarea parsării, dar este o dependență slabă pentru integrarea continuă. Disponibilitatea datelor istorice și răspunsul extern se pot schimba. Păstrați un fixture igienizat pentru testele repetabile și separați verificarea live.

Creați fixture-uri în jurul tranzițiilor semnificative ale expedierii

Construiți fixture-uri din schema documentată și, atunci când sunt disponibile, din răspunsuri reale igienizate. Păstrați fixture-urile cu payload-uri ale furnizorului separate de modelul intern normalizat al evenimentelor. Testați adaptorul dintre acestea, astfel încât un mock intern să nu ascundă un parser defect al furnizorului.

Un set inițial util acoperă aceste scenarii:

  • Încă nu există evenimente de urmărire: păstrați expedierea fără a afirma că este în mișcare sau livrată.
  • În tranzit: actualizați cronologia și păstrați asocierea corectă a comenzii.
  • În curs de livrare: aplicați politica de notificare fără a trata livrarea ca fiind finalizată.
  • Livrat: înregistrați finalizarea și emiteți acțiunea comercială prevăzută o singură dată.
  • Excepție sau tentativă de livrare: păstrați distincția față de o livrare finalizată.
  • Retur: evitați interpretarea fiecărei scanări ulterioare ca progres către destinatarul inițial.
  • Stare necunoscută: păstrați suficiente informații pentru diagnostic fără a inventa o mapare a stării.

Utilizați propriile denumiri normalizate pentru aceste scenarii, apoi mapați explicit valorile documentate ale furnizorului către acestea. Nu presupuneți că API-uri diferite folosesc aceleași etichete de stare sau că o etichetă are aceeași semnificație comercială peste tot.

Variați și forma datelor: o listă de evenimente goală, câmpuri opționale lipsă, câmpuri necunoscute suplimentare, nume de locații Unicode, marcaje temporale cu decalaje de fus orar și valori obligatorii malformate. Parserul trebuie să tolereze adăugările compatibile, respingând în același timp datele care nu pot fi procesate în siguranță.

Trimiteți webhook-uri simulate prin calea reală de recepție

Un webhook simulat trebuie să verifice ruta de recepție, middleware-ul de autentificare, validarea, stocarea și procesarea de către worker, nu doar să apeleze funcția finală de actualizare a stării.

Payload-ul următor reprezintă un eveniment intern sintetic. Numele câmpurilor, ID-ul evenimentului și starea sunt ilustrative; nu reprezintă un contract de callback al furnizorului.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Salvați-l ca tracking-event.json și trimiteți-l către un receptor local de test:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

Această comandă validează doar rutarea și gestionarea locală. Nu demonstrează autentificarea furnizorului. Păstrați o rută destinată exclusiv dezvoltării inaccesibilă în producție sau testați receptorul de producție folosind metoda de autentificare documentată de furnizor și un secret de test separat.

Testați autentificarea fără a slăbi controalele de producție

Dacă furnizorul specifică callback-uri semnate, implementați exact schema respectivă în loc să alegeți un antet de semnătură sau un algoritm arbitrar. Pentru schemele care semnează octeții solicitării, păstrați corpul original pentru verificare; parsarea și re-serializarea JSON-ului poate modifica acei octeți.

Testați autentificarea validă, acreditările lipsă, corpurile modificate și semnăturile incorecte, după caz. Dacă schema documentată include marcaje temporale sau protecție împotriva reluării, testați și aceste reguli. HMAC este o construcție standardizată pentru autentificarea mesajelor, dar existența sa nu demonstrează că un anumit furnizor de urmărire îl utilizează.

Testați duplicatele, ordinea și recuperarea

Procesarea expedierilor trebuie să rămână corectă atunci când aceeași actualizare sosește repetat sau evenimentele sosesc într-o ordine neașteptată. Acestea sunt scenarii de testare defensivă, nu afirmații despre garanția de livrare a unui anumit furnizor.

TestComportamentul așteptat al aplicației
Trimiteți același eveniment de două oriPăstrați un singur eveniment logic și evitați notificările duplicate către clienți.
Trimiteți o scanare de tranzit mai veche după livrarePăstrați istoricul util fără a inversa automat starea livrată.
Trimiteți actualizări simultaneAplicați tranziții de stare consecvente în ciuda worker-ilor concurenți.
Opriți procesarea după recepția durabilăRecuperați și procesați evenimentul stocat fără a necesita un callback nou.
Eșuați stocarea înainte ca recepția să fie durabilăNu confirmați în mod fals acceptarea cu succes.
Trimiteți o expediere necunoscutăUrmați o politică definită de carantină sau respingere; nu ghiciți niciodată asocierea comenzii.

Preferați un identificator stabil și documentat al evenimentului pentru deduplicare, atunci când este furnizat. În caz contrar, definiți o identitate atent delimitată din câmpurile relevante și testați coliziunile. Un număr de urmărire singur nu reprezintă identitatea unui eveniment, deoarece o expediere poate genera multe actualizări legitime.

Separați istoricul evenimentelor de proiecția curentă a expedierii. Păstrarea scanărilor istorice nu impune ca fiecare scanare sosită cu întârziere să suprascrie starea afișată. Nici regula „utilizați cel mai nou marcaj temporal” nu este completă: corecțiile, fluxurile de retur și semnificațiile diferite ale marcajelor temporale necesită gestionare explicită.

Pentru procesarea asincronă, confirmați numai după ce evenimentul ajunge la un punct de predare durabil, precum o înregistrare inbox confirmată sau o coadă durabilă, în funcție de arhitectură. Respectați cerințele documentate ale furnizorului privind confirmarea. HTTP definește semantica codurilor de stare, dar programul de reîncercare al unui anumit expeditor trebuie să provină din propriul său contract.

Efectuați o verificare live controlată și stabiliți criteriile de lansare

După ce testele deterministe trec, înregistrați o expediere autorizată prin integrarea reală și confirmați întregul traseu. Verificați dacă furnizorul a acceptat înregistrarea prevăzută, dacă configurația callback-ului indică mediul corect și dacă datele primite sunt mapate la expedierea așteptată.

Nu solicitați ca fiecare stare a expedierii să apară în timpul verificării live. Expedierile reale nu sunt fixture-uri controlabile. Utilizați rularea live pentru a valida conectivitatea și compatibilitatea observată cu contractul; utilizați fixture-uri reexecutabile pentru scenarii rare sau distructive.

Înainte de lansare, solicitați următoarele rezultate:

  • Răspunsurile documentate de succes și de eroare sunt gestionate, inclusiv erorile la nivel de element dacă API-ul acceptă operațiuni în lot.
  • Timeout-urile nu declanșează reîncercări oarbe de creare atunci când prima solicitare este posibil să fi reușit deja.
  • Evenimentele duplicate nu pot crea acțiuni comerciale duplicate.
  • Callback-urile invalide nu pot modifica starea expedierii.
  • Erorile worker-ului lasă evenimente recuperabile, în loc să le piardă în tăcere.
  • Traficul de dezvoltare nu poate notifica clienți reali sau modifica comenzi din producție.
  • Jurnalele conectează solicitările, evenimentele primite, rezultatele procesării și încercările de notificare fără a expune secrete.

O lansare este pregătită atunci când puteți explica atât fluxul normal, cât și modul în care sistemul se recuperează după o solicitare incertă, un callback repetat sau un worker întrerupt. O singură căutare de urmărire reușită nu este suficientă.

Întrebări frecvente

Pot testa o integrare de urmărire fără sandbox?

Da. Simulați granița API-ului de ieșire, redați fixture-urile documentate ale callback-urilor și testați local normalizarea și regulile comerciale. Apoi utilizați o expediere live autorizată pentru a confirma conectivitatea reală. Aceasta oferă o acoperire substanțială, dar nu reproduce comportamentul nedocumentat al furnizorului.

De ce solicitarea mea de urmărire reușește, dar nu returnează evenimente?

Acceptarea solicitării și disponibilitatea datelor de urmărire sunt rezultate diferite. Verificați detaliile răspunsului furnizorului, cerințele de înregistrare, regulile de identificare a transportatorului și comportamentul documentat pentru expedierile fără evenimente. Nu fabricați informații despre mișcare sau livrare pentru a umple o cronologie goală.

Un webhook simulat reușit demonstrează că vor sosi webhook-urile reale?

Nu. Demonstrează doar calea verificată de mock. Livrarea reală depinde și de configurarea furnizorului, accesibilitatea publică, TLS, autentificare și contractul efectiv al callback-ului. Validați-le printr-o livrare de test acceptată de furnizor sau printr-un flux live autorizat.

Ar trebui să returnez HTTP 200 înainte de finalizarea procesării?

Urmați contractul documentat al furnizorului privind confirmarea. Într-un design asincron, confirmați după acceptarea durabilă, apoi procesați într-un worker. Returnarea succesului înainte de acceptarea durabilă poate pierde un eveniment dacă procesul eșuează imediat după aceea.

Cum ar trebui să testez notificările către clienți?

Trimiteți toate notificările de dezvoltare către un sistem controlat de captare. Verificați destinația, șablonul, tranziția declanșatoare și numărul de trimiteri. Redați același eveniment și simulați reîncercările worker-ului pentru a verifica faptul că o actualizare a expedierii nu generează mesaje repetate către clienți.

Surse

  • 17TRACK Tracking API — punct de pornire oficial pentru produsul API de urmărire.
  • 17TRACK API documentation — referință pentru contractul de integrare specific furnizorului; confirmați aici cerințele aplicabile de testare și callback.
  • RFC 9110: HTTP Semantics — semantica răspunsurilor HTTP și aspecte privind reîncercarea solicitărilor.
  • RFC 2104: HMAC — construcția standardizată de autentificare a mesajelor discutată în recomandările privind securitatea callback-urilor.