Cum să utilizați API-urile de urmărire a expedierilor pentru a trimite notificări proactive privind livrarea
Pentru a trimite notificări proactive privind livrarea cu ajutorul unui API de urmărire a expedierilor, conectați fiecare colet la comanda sa, preluați actualizările de urmărire, traduceți aceste actualizări în evenimente relevante pentru clienți și declanșați mesajele prin serviciul dvs. de e-mail, SMS sau notificări din aplicație. Plasați o coadă durabilă și verificări pentru duplicate între datele de urmărire primite și mesajele trimise, astfel încât actualizările repetate sau întârziate să nu genereze alerte confuze.
Acest ghid se adresează dezvoltatorilor și echipelor de operațiuni ecommerce care construiesc acest flux de lucru. Scopul nu este să redirecționați fiecare scanare a transportatorului, ci să le spuneți clienților când se schimbă ceva important, ce înseamnă schimbarea respectivă și dacă trebuie să acționeze.
Proiectați fluxul de notificare înainte de conectarea API-ului
Un API de urmărire a expedierilor furnizează informații despre urmărire; aplicația dvs. decide cum să le utilizeze. Tratați vizibilitatea expedierii și comunicarea cu clientul ca responsabilități separate, chiar dacă serviciul ales le oferă pe ambele.
O arhitectură practică are șase etape:
- Asocierea comenzii: conectați numărul de urmărire și identificatorul transportatorului, atunci când este necesar, la o înregistrare internă a expedierii.
- Înregistrarea urmăririi: trimiteți sau înregistrați expedierea conform cerințelor de integrare ale furnizorului.
- Preluarea actualizărilor: primiți apeluri webhook, preluați actualizările prin solicitări API sau combinați ambele abordări.
- Procesarea evenimentelor: validați, normalizați, eliminați duplicatele și evaluați evenimentele primite.
- Decizia privind notificarea: alegeți dacă să trimiteți o notificare, pe cine să contactați și ce canal și șablon să utilizați.
- Livrarea mesajului: trimiteți notificarea și înregistrați răspunsul serviciului de mesagerie.
Păstrați informațiile de contact ale clienților în propriul sistem de comenzi sau de mesagerie, cu excepția cazului în care integrarea necesită în mod real partajarea acestora. În general, un serviciu de urmărire nu are nevoie de adresa de e-mail a clientului doar pentru ca aplicația dvs. să asocieze un eveniment de urmărire cu o comandă.
1. Confirmați contractul de integrare
Înainte de a scrie receptorul, verificați în documentația furnizorului autentificarea, înregistrarea expedierii, identificarea transportatorului, metodele de actualizare acceptate, formatele răspunsurilor, limitele solicitărilor și gestionarea erorilor. Pentru integrările webhook, verificați și modul în care sunt autentificate apelurile, ce răspuns confirmă primirea și cum sunt gestionate livrările nereușite.
Pentru o implementare 17TRACK, începeți cu pagina API de urmărire 17TRACK și documentația oficială API. Utilizați contractul documentat pentru integrare, în loc să tratați denumirile ilustrative ale câmpurilor din acest ghid drept câmpuri de solicitare sau răspuns 17TRACK. Confirmați configurarea apelurilor, cerințele de securitate și limitele specifice contului înainte de implementare.
Alegeți metoda de actualizare conform contractului de integrare:
- Webhooks: utilizați apelurile atunci când sunt acceptate și potrivite pentru infrastructura dvs. Acestea permit aplicației să proceseze actualizările atunci când furnizorul le trimite, fără să solicite repetat aceeași expediere.
- Interogare periodică: preluați informațiile de urmărire conform unui program atunci când apelurile nu sunt disponibile sau nu sunt potrivite. Respectați limitele documentate ale solicitărilor.
- Abordare combinată: utilizați apelurile pentru procesarea normală și preluarea selectivă prin API pentru reconcilierea expedierilor ale căror actualizări par învechite, dacă furnizorul acceptă acest flux.
Nu promiteți clienților notificări instantanee doar pentru că utilizați webhooks. Aplicația dvs. nu poate raporta un eveniment al transportatorului înainte ca datele de urmărire din amonte să îl facă disponibil.
2. Construiți o înregistrare a expedierii care rezistă comenzilor reale
Utilizați un ID intern al expedierii ca referință principală, nu doar numărul de urmărire. O comandă poate conține mai multe colete, iar numerele de urmărire nu trebuie presupuse ca fiind unice la nivel global pentru totdeauna.
O înregistrare internă utilă include:
- ID-ul intern al comenzii și al expedierii.
- Numărul de urmărire și identificatorul transportatorului, atunci când sunt cunoscute.
- Referința expedierii furnizată de furnizor, dacă există.
- Starea normalizată curentă și cel mai recent eveniment important.
- Momentul evenimentului transportatorului, inclusiv fusul orar sau decalajul, atunci când sunt disponibile.
- Momentul la care sistemul dvs. a primit actualizarea.
- O referință la preferințele de comunicare ale clientului.
- Istoricul notificărilor și orice flux activ pentru excepții.
Păstrați separat momentul evenimentului și momentul primirii. O scanare efectuată mai devreme poate ajunge după o scanare mai nouă. Dacă aplicația sortează doar după ordinea sosirii, poate schimba în mod eronat o expediere livrată înapoi la starea „în tranzit”.
Pentru comenzile împărțite, conectați notificările la coletul afectat. „Un colet din comanda dvs. a sosit” este mai exact decât „Comanda dvs. a sosit” atunci când un alt colet este încă în tranzit.
3. Asociați evenimentele de urmărire cu deciziile clientului
Descrierile transportatorului sunt date operaționale, nu mesaje gata de trimis clienților. Construiți un nivel de normalizare care păstrează evenimentul original, atribuindu-i în același timp o categorie internă pe care regulile de notificare o pot înțelege.
Următoarele categorii sunt concepte de aplicație sugerate, nu un vocabular universal de stări API:
| Categorie internă | Decizia privind notificarea | Limită de comunicare |
|---|---|---|
| Informațiile despre expediere au fost primite | Trimiteți o actualizare privind pregătirea doar dacă este utilă. | Nu sugerați că transportatorul deține fizic coletul doar pe baza creării etichetei. |
| În tranzit | Luați în considerare notificarea la prima deplasare importantă. | Suprimați scanările obișnuite din centre dacă nu schimbă următorul pas al clientului. |
| În curs de livrare | Notificați atunci când un eveniment acceptat indică această stare. | Nu transformați starea într-o oră garantată de sosire. |
| Încercare de livrare sau ridicare necesară | Trimiteți o notificare care indică acțiunea necesară. | Includeți termene sau instrucțiuni de ridicare doar atunci când sunt verificate. |
| Excepție de livrare | Evaluați cauza și dacă clientul trebuie să acționeze. | Nu descrieți fiecare excepție ca pe un colet pierdut. |
| Livrat | Trimiteți o confirmare la nivel de colet. | Nu inventați destinatarul, locul livrării sau dovada livrării. |
Păstrați incertitudinea. Un eveniment nerecunoscut trebuie să intre într-un flux de revizuire sau de rezervă, nu să fie forțat în cea mai apropiată categorie cunoscută. Păstrați descrierea brută disponibilă pentru personalul de asistență, în scopul depanării.
4. Primiți actualizări fără să pierdeți sau să duplicați activitatea
Endpointul webhook trebuie să valideze solicitarea, să salveze durabil actualizarea acceptată și să returneze confirmarea necesară de către furnizor. Generați mesajele asincron, nu așteptați un serviciu de e-mail sau SMS în timpul solicitării de apel.
Implementați metoda documentată de verificare a apelurilor furnizorului. Nu inventați un antet de semnătură și nu presupuneți că fiecare furnizor utilizează aceeași schemă de autentificare. Impuneți, de asemenea, HTTPS, limite pentru dimensiunea solicitării, validarea încărcăturii utile și controale de acces adecvate.
Un flux simplificat de procesare arată astfel. Acestea sunt operațiuni la nivel de aplicație, nu un exemplu funcțional de SDK:
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriate
Pașii atomici sunt importanți. Dacă aplicația salvează o modificare de stare, dar se blochează înainte de a crea sarcina de notificare, este posibil ca clientul să nu primească niciodată alerta. Un outbox tranzacțional este o opțiune de proiectare: salvați modificarea de stare și sarcina în așteptare în aceeași tranzacție a bazei de date, apoi permiteți unui worker să trimită sarcina.
Gestionați explicit referințele necunoscute ale expedierilor. Izolați-le pentru investigare sau reconciliere, în loc să ghiciți ce client ar trebui să primească o notificare.
5. Adăugați protecție împotriva duplicatelor și verificări cronologice
Proiectați receptorul pentru a tolera apelurile repetate și reîncercările workerilor. Preferați un identificator stabil al evenimentului furnizorului atunci când este documentat. În caz contrar, creați o amprentă deterministă a evenimentului din câmpuri adecvate, precum ID-ul intern al expedierii, codul evenimentului, momentul evenimentului și locația. Testați această amprentă pe încărcături utile reale înainte de a vă baza pe ea.
Eliminarea duplicatelor evenimentelor și suprimarea notificărilor rezolvă probleme diferite. Eliminarea duplicatelor împiedică procesarea aceluiași eveniment de două ori. Suprimarea împiedică mai multe scanări distincte să genereze practic același mesaj pentru client.
Definiți identitatea unei notificări în jurul evenimentului de afaceri. O confirmare de livrare ar putea utiliza ID-ul expedierii și etapa livrată. O încercare de livrare poate necesita o identitate specifică încercării, deoarece o încercare ulterioară poate fi un eveniment cu adevărat nou.
Pentru actualizările sosite în ordine greșită, comparați marcajele temporale ale evenimentelor și evaluați tranzițiile de stare permise. Nu presupuneți că un apel conține doar o scanare nouă; verificați dacă structura documentată reprezintă un eveniment individual, un instantaneu sau un istoric. Direcționați actualizările contradictorii către reconciliere, în loc să eliminați în tăcere toate corecțiile.
6. Scrieți mesaje care explică ce urmează
Fiecare notificare trebuie să precizeze coletul relevant, schimbarea confirmată și următorul pas al clientului. Includeți un link securizat de urmărire și o referință de comandă recognoscibilă. Evitați expunerea adreselor complete sau a informațiilor personale inutile în mesajele SMS și în previzualizările de pe ecranul blocat.
De exemplu:
- În curs de livrare: „Coletul dvs. pentru comanda {order_reference} este în curs de livrare. Urmăriți-i progresul aici: {tracking_link}.”
- Livrare încercată: „Transportatorul a raportat o încercare de livrare pentru coletul dvs. Consultați pagina de urmărire pentru pașii următori disponibili: {tracking_link}.”
- Livrat: „Transportatorul a marcat coletul dvs. pentru comanda {order_reference} ca fiind livrat. Consultați detaliile disponibile ale livrării: {tracking_link}.”
Randați substituenții numai din date validate. Dacă este disponibilă și potrivită pentru afișare o estimare a livrării, marcați-o ca estimare. Dacă lipsește, omiteți-o în loc să inventați o dată.
Pentru excepții, diferențiați o problemă a expedierii de o sarcină a clientului. O perturbare poate necesita doar o explicație; o problemă verificată a adresei poate necesita acțiune. Nu direcționați clienții către o pagină de plată sau de încărcare a documentelor bazându-vă exclusiv pe conținutul de urmărire în text liber și neverificat.
Alegeți canalele în funcție de preferințele clientului, permisiunile canalului, urgență și regulile aplicabile. Verificați cerințele privind consimțământul, renunțarea și orele de liniște pentru jurisdicțiile și canalele de mesagerie utilizate. Păstrați notificările privind livrarea separate de campaniile promoționale, în loc să presupuneți că aceleași permisiuni le acoperă pe ambele.
7. Definiți ce se întâmplă când urmărirea încetează
Comunicarea proactivă trebuie să acopere atât lipsa progresului, cât și evenimentele noi, însă tăcerea singură nu dovedește că o expediere este întârziată sau pierdută.
Creați o regulă pentru urmărirea învechită folosind nivelul serviciului, ruta, ultimul eveniment important și orice estimare de livrare acceptată. Stabiliți pragurile pe baza datelor operaționale și a procesului de asistență, nu aplicați o singură perioadă universală de așteptare tuturor expedierilor.
Când regula este declanșată, verificați procesarea ratată, reconciliați cu sursa de urmărire acolo unde este acceptat și decideți dacă trebuie deschisă o sarcină internă de asistență. Dacă notificați clientul, utilizați formulări care reflectă ceea ce știți: „Nu am primit o nouă actualizare de urmărire” este diferit de „Coletul dvs. este pierdut”.
Desemnați un responsabil pentru excepțiile nerezolvate. Un sistem de notificare care anunță în mod repetat o problemă fără a crea o cale către rezolvare poate crește frustrarea clienților.
8. Testați întregul flux înainte de activarea trimiterilor automate
Rulați mai întâi fluxul în modul shadow: preluați evenimente reale sau de test aprobate, generați notificări propuse și inspectați rezultatele fără a contacta clienții.
- Re redați un apel identic și confirmați că nu creează un alt mesaj.
- Procesați un eveniment de tranzit mai vechi după un eveniment de livrare și inspectați starea rezultată.
- Testați marcaje temporale lipsă, stări necunoscute și încărcături utile malformate.
- Simulați o defecțiune a bazei de date înainte de confirmare și o defecțiune a workerului după persistență.
- Testați timeout-urile de mesagerie, inclusiv un răspuns incert în care este posibil ca serviciul să fi acceptat deja mesajul.
- Confirmați că expedierile împărțite produc formulări specifice coletelor.
- Verificați destinatarii care au renunțat, datele de contact invalide și gestionarea orelor de liniște.
- Verificați că linkurile de urmărire nu expun informațiile despre comanda altui client.
Monitorizați apelurile acceptate, erorile de procesare, vechimea cozii, sarcinile de notificare, suprimarea duplicatelor și rezultatele mesageriei. Măsurați separat latența procesării de la momentul primirii de către sistemul dvs. față de vechimea evenimentului transportatorului. Această distincție ajută la identificarea situației în care o notificare lentă a fost cauzată de disponibilitatea datelor din amonte sau de propriul flux.
Începeți cu un set mic de etape bine înțelese. Extindeți regulile doar după ce echipele de asistență și operațiuni sunt de acord că mesajele sunt exacte, utile și merită primite.
Întrebări frecvente
Un API de urmărire a expedierilor trimite automat e-mailuri sau mesaje SMS?
Nu neapărat. Accesul la datele de urmărire și mesageria către clienți sunt capabilități separate. Verificați domeniul documentat al serviciului. Într-o integrare personalizată, aplicația dvs. poate procesa actualizările de urmărire și trimite notificări printr-un serviciu de mesagerie separat.
Ar trebui să notific clienții despre fiecare scanare de urmărire?
De obicei, nu. Prioritizați etapele importante și evenimentele care necesită acțiune. Mai multe scanări în centre pot reprezenta un tranzit normal fără a schimba ceea ce clientul trebuie să știe. Păstrați istoricul detaliat pe pagina de urmărire.
Pot garanta notificări de livrare în timp real?
Puteți stabili și monitoriza un obiectiv de procesare după ce sistemul dvs. primește o actualizare. Nu puteți garanta momentul în care un transportator va înregistra sau publica o scanare. Descrieți serviciul în termeni care reflectă această dependență.
Cum pot preveni mesajele duplicate privind livrarea?
Utilizați eliminarea persistentă a duplicatelor evenimentelor, o identitate separată a notificării pentru fiecare etapă de afaceri și crearea tranzacțională a sarcinilor. Dacă serviciul de mesagerie acceptă idempotența, utilizați-o ca măsură suplimentară de protecție. O verificare a duplicatelor doar în memorie nu va supraviețui repornirilor sau mai multor workeri.
Ce ar trebui să se întâmple dacă transportatorul corectează o stare „livrat”?
Păstrați ambele evenimente și reconciliați starea expedierii. Dacă modificarea afectează în mod semnificativ clientul, trimiteți o corecție clară sau direcționați cazul către asistență, conform politicii dvs. Nu faceți starea „livrat” permanent ireversibilă doar pentru a simplifica codul.
Surse
Următoarele resurse oficiale reprezintă referințele de implementare pentru integrarea 17TRACK discutată mai sus. Schema internă, regulile de notificare și fluxul de procesare din acest ghid sunt recomandări de arhitectură, nu contracte API citate.
- API de urmărire 17TRACK — punctul oficial de pornire pentru evaluarea integrării API.
- Documentația API 17TRACK — referință pentru formatele de solicitare specifice furnizorului, autentificare, operațiuni de urmărire și cerințe de integrare.


