Orice magazin online care expediază colete ajunge într-o zi la aceeași decizie: să își integreze curierii, ca AWB-urile să se genereze automat, statusurile coletelor să ajungă la client fără să scrie nimeni mesaje, iar rambursul și lockerele să meargă fără introducere manuală. Pe hârtie e simplu: trimiți datele comenzii, primești un AWB. În practică, fiecare curier îi cere datele într-un alt format, îi validează altfel adresa și îți răspunde în alt fel când ceva nu e în regulă.
Am construit Ordova, platforma noastră de expedieri care conectează FAN Courier, Cargus, Sameday, DPD și GLS la magazine online, așa că ghidul de mai jos nu e o parafrază a documentațiilor oficiale, ci ce am învățat integrând efectiv acei curieri: ce date cer, unde apar erorile și ce trebuie să pui în plan înainte să înfunci proiectul.
Pe scurt: toți curierii cer aceleași grupe de date (expeditor, destinatar, adresă structurată, colet, ramburs, serviciu), dar diferă prin autentificare, prin felul în care identifică localitatea sau codul poștal, prin lockere și prin retururi. Cele mai multe AWB-uri respinse vin din adresă și cod poștal, nu din apelul API. Salvează eticheta la creare și tratează separat un colet „negăsit” de o eroare de rețea.
Datele pe care le cer toți curierii
Înainte de diferențe, merită să vezi cât de mult se suprapun cerințele. Indiferent de curier, crearea unui AWB cere:
- Expeditorul sau punctul de ridicare: nume, telefon, adresă completă și, la unii curieri, un identificator al punctului de ridicare configurat în contul tău.
- Destinatarul: nume, telefon (aproape întotdeauna obligatoriu), email, uneori opțional.
- Adresa de livrare structurată: județ, localitate, stradă, număr și cod poștal.
- Coletul: greutate, număr de colete, dimensiuni când serviciul le cere.
- Serviciul: standard, expres, livrare în locker, livrare în punct de ridicare.
- Rambursul: suma, moneda și, la unii curieri, o referință pentru identificarea plată.
- Valoarea declarată sau asigurarea, dacă îi ai în contract.
- Data ridicării, care trebuie să respecte zilele agreate cu curierul.
Dacă magazinul tău are deja aceste date structurate în comandă, ai jumătate din treabă făcută. Dacă adresa e un singur câmp de text liber, urmează problemele descrise mai jos.
Ce diferă între curieri, din ce am întâlnită noi
Tabelul conține particularități pe care le-am întâlnit în integrări reale. Documentația fiecărui curier se schimbă, așa că verific-o întotdeauna pe cea curentă.
| Curier | Autentificare și cont | Ce am întâlnit în practică |
|---|---|---|
| FAN Courier | Cont cu identificator de client | Pentru retururi are nevoie de adresa sucursalei salvată în configurație; fără ea, AWB-ul de retur e respins |
| Cargus | Autentificare cu token | Dacă te autentifici la fiecare colet în timpul urmăririi, poți primi eroarea 429 (prea multe cereri), deci refolosește tokenul |
| Sameday | Cont cu punct de ridicare | La unele servicii cere identificatorul localității din nomenclatorul lor; la retur, structura datelor e inversată (clientul apare ca terț de la care se ridică coletul) |
| GLS (MyGLS) | Utilizator, parolă transmisă ca hash și număr de client | Codul poștal e obligatoriu și validat de GLS; nomenclatorul lor nu are câmp de județ; erorile vin cu HTTP 200, în liste de erori, nu cu coduri HTTP de eșec |
Adresa: unde se pierd cele mai multe AWB-uri
Cele mai multe erori de creare a unui AWB nu vin din API, ci din adresă. Trei lucruri se repetă în orice integrare:
Nomenclatorul de localități. Fiecare curier are propria listă de localități, cu propriile grafii. Un client care scrie „Bucuresti”, „București” sau „Buc. Sector 3” poate fi acceptat de unul și respins de altul. Soluția sigură este să pui în checkout două liste de selecție (județ și localitate), alimentate din nomenclatorul curierilor, nu un câmp liber. Aceasta înseamnă și că selectorul de adresă din checkout trebuie să funcționeze în varianta de checkout folosită, așa cum e explicat în ghidul despre checkout cu blocuri sau clasic.
Codul poștal. Unii curieri îl rutează după codul poștal și îl validează strict. La GLS, de exemplu, un cod inexistent este respins cu o eroare explicită, iar Bucureștiul are coduri diferite pe sectoare, deci un cod generic pentru „București” nu ajunge. Cea mai bună abordare este să deduci codul din localitate și, la București, din sector, și să ceri sectorul clientului dacă lipsește.
Strada și numărul. Documentația unora cere numărul ca valoare numerică, iar pe teren apar „12A”, „5 bis” sau adrese fără număr. Păstrează numărul și detaliile separate de stradă și testează cu adrese reale, pentru că unele valori acceptate în practică nu apar în documentație. Telefonul se normalizează într-un format unitar (E.164) înainte de trimitere.
Rambursul
Rambursul cere în mod curent suma, moneda și, uneori, o referință. Două detalii contează: nu toate punctele de livrare acceptă ramburs (la GLS, informația vine ca atribut al fiecărui punct din nomenclator), iar suma trebuie să coincidă cu totalul comenzii, inclusiv livrarea, altfel curierul încasează altă sumă decât cea din magazin. Dacă ai clienți firme, ai grijă și la datele de facturare, pentru că factura trebuie să se potrivească cu ce se încasează.
Lockerele și punctele de ridicare
Livrarea în locker sau în punct partener este acum o așteptare obișnuită a clienților. Tehnic, cere două lucruri: un nomenclator de puncte (la GLS România, de ordinul a 3.000 de puncte: ParcelShop-uri, lockere și depozite) și salvarea identificatorului punctului ales în comandă. Două capcane: identificatorul punctului nu coincide mereu cu un cod poștal (codul real se citește din adresa punctului), iar la livrarea în locker curierul ignoră adresa clientului și folosește adresa lockerului, așa că eticheta trebuie să arate lockerul ca destinatar, cu datele clientului ca persoană de contact.
Etichetele AWB
Salvează eticheta în momentul creării. La GLS, de pildă, o etichetă deja tipărită nu mai poate fi cerută a doua oară prin API (răspunsul este o eroare), deci singura reimprimare posibilă este din contul lor sau din copia pe care ai salvat-o tu. Formatul contează și el: o etichetă de 10 pe 15 cm (A6) nu seamănă cu una termică mică, iar tipul implicit depinde adesea de setările contului, nu de apelul tău.
Tracking-ul
Fiecare curier are propriul set de statusuri: GLS singur are în jur de o sută de coduri. Ca clientul să vadă ceva coerent, mapezi toate codurile pe un set mic de statusuri proprii (creat, preluat, în tranzit, livrat, returnat, anulat). Mai sunt trei lucruri care ies în practică:
- Un colet abia creat poate răspunde „negăsit”. Pentru primele minute nu e o eroare, ci „în așteptare”.
- După anulare, curierul poate raporta încă o vreme un status vechi. Nu retrograda un colet anulat într-un status neterminal.
- Nu verifica toate coletele la fel de des. Un colet creat ieri merită verificat la câteva zeci de minute, unul de acum o lună de câteva ori pe zi, iar după un număr de zile ar trebui să renunți, altfel arzi cereri pe date moarte.
Erori și robustețe
Tratează erorile ca pe o parte din produs, nu ca pe o excepție. Reține că unii curieri răspund cu HTTP 200 chiar și la credențiale greșite, deci nu te baza pe codul HTTP, ci pe corpul răspunsului; că un 404 poate însemna fie „colet inexistent”, fie „adresă de API greșită”; că reluarea orbă a unei cereri poate crea AWB-uri duplicate sau poate declanșa limite de siguranță ale curierului; și că unii curieri nu oferă un mediu de test utilizabil. Noi am validat integrările pe colete reale, anulate imediat, cu acord explicit și cu date de test, iar tu ar trebui să faci la fel, cu atenție, pentru că un AWB real este o cheltuială reală.
Construiești singur sau folosești o platformă
Integrarea cu un singur curier, fără retururi și fără lockere, poate fi făcută direct în magazin. Dar de la doi curieri în sus, sau când ai nevoie de retururi, lockere, tracking pentru client și mentenanță când API-urile se schimbă, costul total crește repede. Atunci are sens fie o platformă gata făcută, fie o integrare construită la comandă pe API-urile curierilor. Dacă ai volum mare de colete, Ordova este soluția pe care o folosim noi.
Checklist înainte de go-live
- Toate datele de expeditor sunt completate și testate (adresă, telefon, punct de ridicare).
- Selectorii de județ și localitate folosesc nomenclatorul curierului.
- Codul poștal e dedus sau validat, nu lăsat liber.
- Rambursul coincide cu totalul comenzii, în moneda corectă.
- Lockerele funcționează în varianta de checkout folosită.
- Eticheta se salvează la creare și se poate retipări.
- Tracking-ul distinge „în așteptare” de eroare.
- Ai testat anularea și retururile cu un colet real.
Întrebări frecvente
De ce îmi respinge curierul AWB-ul dacă adresa pare corectă?
De cele mai multe ori din cauza nomenclatorului: localitatea sau codul poștal nu se potrivesc exact cu lista curierului. Verifică și numărul de stradă și telefonul.
Am nevoie de contract cu fiecare curier?
Da. Credențialele de API se obțin din contul tău la curier, iar serviciile disponibile (ramburs, lockere, retur) depind de contract.
Pot folosi mai mulți curieri în același magazin?
Da, dar adaugi complexitate: fiecare curier are propriul nomenclator, propriile statusuri și propriile erori, și toate trebuie normalizate într-un model comun.
E mai bine un plugin sau o integrare custom?
Depinde de numărul de curieri și de cerințe. Pentru un curier și un flux simplu, un plugin poate ajunge. Pentru mai mulți curieri, retururi și tracking propriu, o integrare dedicată e de obicei mai stabilă.
Ce e mai riscant la o integrare cu curierii?
Adresele și erorile tratate greșit: un AWB duplicat, un ramburs greșit sau un colet ajuns la o adresă incorectă costă mai mult decât dezvoltarea însăși.
Dacă vrei să afli ce ar presupune pentru magazinul tău, vezi cum arată o integrare cu curierii și cum lucrăm în logistică și transport.
