Documentație API

Etichete AWB și anulare

După ce expediția există, ai nevoie de etichetă pentru colet — și uneori de posibilitatea de a renunța la expediere.

Descărcarea etichetei

GET/public/awb/print/{awbNumber}Bearer JWT

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`format`	pdf \| zpl	opțional	PDF pentru imprimante obișnuite, ZPL pentru imprimante termice Zebra.
`paperSize`	A4 \| A6 \| A4_4xA6	opțional	`A4_4xA6` pune patru etichete pe o foaie A4. Implicit, A4.
`language`	string	opțional	Limba textului de pe etichetă, de exemplu RO sau EN.

Exemplu

bash

curl -o eticheta.pdf \
  -H "Authorization: Bearer $TOKEN" \
  "https://www.api.livraria.ro/public/awb/print/81356295593?format=pdf&paperSize=A6"

Răspunsul este fișierul brut: Content-Type: application/pdf, respectiv tipul ZPL. Nu este JSON — scrie-l direct pe disc.

Expediția trebuie să fie a contului autentificat; altfel primești 403.

Link semnat, pentru deschidere în browser

O navigare de nivel superior — un buton care deschide eticheta într-un tab nou — nu poate trimite header-ul Authorization. Pentru asta există un link scurt, semnat, care conține propria autorizație.

GET/public/awb/print-link/{awbNumber}Bearer JWT

Proprietatea expediției se verifică aici, la emitere.

Răspuns 200 OK

json

{
  "token": "bGFiZWwtcHJpbnQ6ODEzNTYyOTU1OTM...",
  "url": "/public/awb/label/81356295593?token=bGFiZWwtcHJpbnQ...",
  "expiresAt": "2026-10-28T09:10:12.000Z"
}

GET/public/awb/label/{awbNumber}?token=...token în URL

Servește PDF-ul fără header de autentificare. Acceptă aceiași parametri format, paperSize și language.

Mai multe etichete într-un singur PDF

POST/public/awb/print/mergedBearer JWT

Corpul cererii

Câmp	Tip	Cerut	Descriere
`awbNumbers`	string[]	obligatoriu	AWB-urile de inclus, în ordinea de tipărire. Duplicatele se elimină.
`paperSize`	A4 \| A6 \| A4_4xA6	opțional	Ca la descărcarea unei singure etichete.
`language`	string	opțional	Limba textului de pe etichete.

Cerere

json

{
  "awbNumbers": ["81356295593", "7000167017150", "1ONB24524001822"],
  "paperSize": "A4_4xA6",
  "language": "RO"
}

Răspunsuri

Cod	Ce înseamnă
200	PDF-ul comasat. AWB-urile care nu au putut fi aduse sunt listate, separate prin virgulă, în header-ul `X-Livraria-Failed-Awbs` — verifică-l întotdeauna, răspunsul este 200 chiar dacă lipsesc etichete.
403	Una dintre expediții aparține altui cont. Nu se întoarce nimic.
404	Unul dintre AWB-uri nu există.
502	Nicio etichetă nu a putut fi adusă de la curieri.

Anularea expedierii

Verifică mai întâi

Fiecare expediție citită prin API poartă canCancel, cancelBlockedReason și cancelDeadline. Citește-le înainte de a încerca anularea — vezi Creare expediție.

PATCH/public/awb/cancel/{awbNumber}Bearer JWT

Răspuns 200 OK

json

{
  "success": true,
  "message": "Expedierea a fost anulata",
  "courierCancelled": true,
  "courierOutcome": "ACCEPTED",
  "requiresCredit": false,
  "refundDue": false
}

Câmpurile răspunsului

Câmp	Tip	Cerut	Descriere
`success`	boolean	mereu	Expedierea este anulată în Livrǎria. Nu depinde de răspunsul curierului.
`courierCancelled`	boolean \| null	opțional	Curierul a confirmat anularea. False înseamnă că la noi este anulată, dar la curier nu — contactează-ne dacă ajungi aici.
`courierOutcome`	ACCEPTED \| REFUSED \| ERROR \| NOT_ATTEMPTED	opțional	Răspunsul curierului, așa cum a fost înregistrat.
`requiresCredit`	boolean \| null	opțional	Expedierea era deja facturată. Suma de stornat este în `creditAmount`.
`refundDue`	boolean \| null	opțional	Expedierea fusese plătită cu cardul la comandă, deci urmează o restituire.

409 — coletul este deja la curier

Dacă parcursul a început, anularea este refuzată și nimic nu se schimbă:

json

{
  "statusCode": 409,
  "code": "IN_COURIER_CUSTODY",
  "message": "Curierul are deja coletul"
}

IN_COURIER_CUSTODY înseamnă că coletul este preluat; CUSTODY_UNKNOWN că nu am putut stabili unde se află. În ambele cazuri, pasul următor este un retur, nu o anulare.

DELETE/public/awb/{awbNumber}Bearer JWT

Șterge expedierea din sistemul curierului. Operația anulează mai întâi, deci refuză cu 409 în aceleași situații ca anularea.

Ai nevoie de ajutor?

Scrie-ne și îți răspunde cineva din echipă.

Contactează-ne

Descărcarea etichetei

GET/public/awb/print/{awbNumber}Bearer JWT

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`format`	pdf \| zpl	opțional	PDF pentru imprimante obișnuite, ZPL pentru imprimante termice Zebra.
`paperSize`	A4 \| A6 \| A4_4xA6	opțional	`A4_4xA6` pune patru etichete pe o foaie A4. Implicit, A4.
`language`	string	opțional	Limba textului de pe etichetă, de exemplu RO sau EN.

Exemplu

bash

curl -o eticheta.pdf \
  -H "Authorization: Bearer $TOKEN" \
  "https://www.api.livraria.ro/public/awb/print/81356295593?format=pdf&paperSize=A6"

Răspunsul este fișierul brut: Content-Type: application/pdf, respectiv tipul ZPL. Nu este JSON — scrie-l direct pe disc.

Expediția trebuie să fie a contului autentificat; altfel primești 403.

Link semnat, pentru deschidere în browser

GET/public/awb/print-link/{awbNumber}Bearer JWT

Proprietatea expediției se verifică aici, la emitere.

Răspuns 200 OK

json

{
  "token": "bGFiZWwtcHJpbnQ6ODEzNTYyOTU1OTM...",
  "url": "/public/awb/label/81356295593?token=bGFiZWwtcHJpbnQ...",
  "expiresAt": "2026-10-28T09:10:12.000Z"
}

GET/public/awb/label/{awbNumber}?token=...token în URL

Servește PDF-ul fără header de autentificare. Acceptă aceiași parametri format, paperSize și language.

Mai multe etichete într-un singur PDF

POST/public/awb/print/mergedBearer JWT

Corpul cererii

Câmp	Tip	Cerut	Descriere
`awbNumbers`	string[]	obligatoriu	AWB-urile de inclus, în ordinea de tipărire. Duplicatele se elimină.
`paperSize`	A4 \| A6 \| A4_4xA6	opțional	Ca la descărcarea unei singure etichete.
`language`	string	opțional	Limba textului de pe etichete.

Cerere

json

{
  "awbNumbers": ["81356295593", "7000167017150", "1ONB24524001822"],
  "paperSize": "A4_4xA6",
  "language": "RO"
}

Răspunsuri

Cod	Ce înseamnă
200	PDF-ul comasat. AWB-urile care nu au putut fi aduse sunt listate, separate prin virgulă, în header-ul `X-Livraria-Failed-Awbs` — verifică-l întotdeauna, răspunsul este 200 chiar dacă lipsesc etichete.
403	Una dintre expediții aparține altui cont. Nu se întoarce nimic.
404	Unul dintre AWB-uri nu există.
502	Nicio etichetă nu a putut fi adusă de la curieri.

Anularea expedierii

Verifică mai întâi

Fiecare expediție citită prin API poartă canCancel, cancelBlockedReason și cancelDeadline. Citește-le înainte de a încerca anularea — vezi Creare expediție.

PATCH/public/awb/cancel/{awbNumber}Bearer JWT

Răspuns 200 OK

json

{
  "success": true,
  "message": "Expedierea a fost anulata",
  "courierCancelled": true,
  "courierOutcome": "ACCEPTED",
  "requiresCredit": false,
  "refundDue": false
}

Câmpurile răspunsului

Câmp	Tip	Cerut	Descriere
`success`	boolean	mereu	Expedierea este anulată în Livrǎria. Nu depinde de răspunsul curierului.
`courierCancelled`	boolean \| null	opțional	Curierul a confirmat anularea. False înseamnă că la noi este anulată, dar la curier nu — contactează-ne dacă ajungi aici.
`courierOutcome`	ACCEPTED \| REFUSED \| ERROR \| NOT_ATTEMPTED	opțional	Răspunsul curierului, așa cum a fost înregistrat.
`requiresCredit`	boolean \| null	opțional	Expedierea era deja facturată. Suma de stornat este în `creditAmount`.
`refundDue`	boolean \| null	opțional	Expedierea fusese plătită cu cardul la comandă, deci urmează o restituire.

409 — coletul este deja la curier

Dacă parcursul a început, anularea este refuzată și nimic nu se schimbă:

json

{
  "statusCode": 409,
  "code": "IN_COURIER_CUSTODY",
  "message": "Curierul are deja coletul"
}

IN_COURIER_CUSTODY înseamnă că coletul este preluat; CUSTODY_UNKNOWN că nu am putut stabili unde se află. În ambele cazuri, pasul următor este un retur, nu o anulare.

DELETE/public/awb/{awbNumber}Bearer JWT

Șterge expedierea din sistemul curierului. Operația anulează mai întâi, deci refuză cu 409 în aceleași situații ca anularea.