Dezvoltatori

API v2 — livrarea prin eZif (pentru magazine)

AWB-ul comenzii emis prin eZif, opțiunile de livrare, lockerele, localitățile și codurile poștale, starea livrării, pagina publică de urmărire și anunțurile awb.created / awb.status.

Specificația API (JSON)

Din v0.140.0, magazinele (modulul WooCommerce 2.0 și orice altă platformă) emit AWB-urile prin eZif, cu curierii conectați în Setări → Curieri: o singură conexiune la curieri pentru facturare, AWB, ramburs, decont și urmărire.

Autentificarea e aceeași ca la API-ul v1: antetele X-Ezif-Key, X-Ezif-Timestamp, X-Ezif-Signature (și X-Ezif-Site cu domeniul magazinului). Drepturile cheii: citirile cer „Citire documente” (documents:read); emiterea AWB-ului, eticheta și anularea cer dreptul nou „Livrare” (shipping:write), bifat de Administrator în Setări → Integrări → API și chei → Setările aplicației.

Endpoint-urile

Metoda și adresa Ce face
GET /api/ext/v2/shipping/options curierii conectați, cu punctele de ridicare și serviciile (kind: door la adresă, locker, pudo la punct)
GET /api/ext/v2/shipping/places?courier=&kind=&service= județele și localitățile în care curierul are puncte (filtrele de la checkout)
GET /api/ext/v2/shipping/points?courier=&kind=&county=&city=&q=&service= lockerele / punctele: cu county — toate punctele județului / localității, ordonate alfabetic (din v0.173.5); fără county — cel mult 40; răspunsul are found (câte s-au găsit) și total; câmpurile: id, name, type, city, county, address, postal_code
GET /api/ext/v2/shipping/cities?courier=&county=&q= localitățile din nomenclatorul curierului (validarea adresei)
GET /api/ext/v2/postal-codes?county=&locality=&street= · ?code= codul poștal după adresă (best = codul sigur) sau adresele unui cod
POST /api/ext/v2/orders/{external_id}/awb emite AWB-ul comenzii (detalii mai jos)
GET /api/ext/v2/orders/{external_id}/shipping AWB-ul comenzii, curierul, starea (emis, in_tranzit, livrat, refuzat, returnat, anulat), ultimul eveniment, legătura de urmărire
GET /api/ext/v2/awbs/{awb}/label eticheta PDF
DELETE /api/ext/v2/awbs/{awb} anulează AWB-ul (la curier, doar înainte de preluare)
POST /api/ext/v2/orders/{external_id}/cancel din v0.148.8: comanda anulată în magazin — proforma anulată, AWB-urile anulate la curier (și cele trimise de pluginul curierului, dacă curierul e conectat), comanda din Comenzi anulată cu rezervările eliberate; factura nu se atinge. Corp opțional {"reason": "…"}. Răspunsul: found, proformas, invoices (cu storno), awbs (cancelled, message), order, warnings; avertismentele apar și la „De rezolvat”. Cere dreptul „Facturare” (invoice:write); se poate relua

AWB-ul comenzii

POST /api/ext/v2/orders/{external_id}/awb, unde external_id e numărul comenzii trimis și la factura v1:

{"courier": "sameday", "service": 7, "pickup_point": 11, "parcels": 1, "weight": 2.5,
 "cod": null, "order_ref": "5002", "observation": "Sunați înainte",
 "recipient": {"name": "Ana Pop", "phone": "0721000000", "email": "ana@client.ro",
               "street": "Str. Livrării 3", "city": "Otopeni", "county": "Ilfov", "postal_code": "075100"},
 "location": null, "extras": null}
  • Comanda are document eZif (factura sau proforma ei): AWB-ul trece pe document; fără cod, rambursul = restul de plată.
  • Comanda nu are încă document: AWB-ul se emite fără document, legat de comandă (recipient obligatoriu), și trece singur pe factura emisă ulterior.
  • La locker / punct: service = un serviciu cu kind locker / pudo, iar location = punctul ales la checkout (obiectul primit din /shipping/points).
  • extras: opțiunile curierului (wootPRO: plic, valoare declarată, asigurare, deschidere, sâmbătă; Poșta Română: fragil, confirmare de primire, avizare SMS…).

Răspunsul: awb, courier, invoice_id, label_url, tracking_url, cost.

Pagina publică de urmărire

tracking_url e o legătură semnată către pagina eZif de urmărire (fără cont; nu se poate ghici): starea coletului, ultimul eveniment și legătura către curier. Cu ?format=json sau Accept: application/json întoarce aceleași date în JSON (pentru contul clientului din magazin).

Anunțurile către magazin

Pe adresa de callback a cheii (sau a firmei), semnate ca la v1: - awb.created — AWB emis prin eZif: external_id, invoice_id, awb, courier, tracking_url; - awb.status — starea livrării s-a schimbat: external_id, invoice_id, awb, courier, status, tracking_url.

Aplicațiile cu evenimente alese trebuie să bifeze aceste două evenimente în Setările aplicației.

E-mailurile către client

Setări → Comunicare cu clienții: AWB emis, Coletul a fost livrat și Livrarea nu a reușit (refuzat / returnat), fiecare cu Trimitere automată; pleacă o singură dată pe AWB, cu legătura de urmărire ({link_urmarire}; legătura directă la curier: {link_curier}).

Documentația aplicației eZif 0.204.6.