Documentație API
Prezentare generală
API-ul Livrǎria îți permite să ceri cotații, să generezi AWB-uri, să descarci etichete și să urmărești colete la toți curierii cu care lucrăm, din propriul sistem.
Adresa de bază
Toate apelurile pleacă de la o singură adresă. Nu există prefix de versiune în cale — versiunea API este 1.0, iar schimbările incompatibile sunt anunțate înainte.
https://www.api.livraria.roCererile și răspunsurile sunt JSON (Content-Type: application/json), datele sunt ISO 8601 în UTC, iar sumele sunt în RON. Crearea unei resurse răspunde cu 201, citirile cu 200.
Fluxul de integrare
O expediție se creează în patru apeluri. Pașii 2 și 3 scriu pe cererea de cotație, motiv pentru care pasul 4 nu mai trimite nimic în afară de identificatorul acesteia.
| Pas | Apel | Rezultat |
|---|---|---|
| 1 | POST /public/awb/quotes | Cererea de cotație este salvată și primești cotații de la fiecare curier. Reține quoteRequest.id și courierQuotes[].id. |
| 2 | PUT /quote-request/{id}/selected-courier-quote | Fixează cotația aleasă pe cerere. |
| 3 | POST /quote-request/{id}/billing-info | Atașează datele de facturare. |
| 4 | POST /expedition | Generează AWB-ul la curier și întoarce expediția. |
Acesta este exact fluxul folosit de modulele oficiale pentru Shopify, WooCommerce, PrestaShop și OpenCart. Pentru detalii pe fiecare pas, vezi Cotații, Pregătirea comenzii și Creare expediție.
Autentificare
Toate rutele legate de contul tău cer un JWT în header-ul Authorization. Tokenul se obține cu datele contului Livrǎria, pe care îl creezi o singură dată în aplicație.
Authorization: Bearer <accessToken>Nu există chei de API. Tokenul este valabil 3600 de secunde — ține-l în memorie pe toată durata lui și reautentifică-te doar când expiră. Detaliile sunt pe pagina Autentificare.
Ce funcționează fără autentificare
Câteva rute sunt publice, pentru că le folosești înainte să ai un cont pe fir sau direct din magazinul tău:
GET /public/couriers— curierii activi și ce servicii suportă fiecare.GET /public/location/*— județe, orașe și coduri poștale.GET /pudo-points— lockere și puncte de ridicare.POST /public/awb/quick-quotes— prețuri orientative, fără să salveze nimic.GET /expedition/public/tracking— urmărire cu date personale mascate, potrivită pentru pagina ta de „urmărește comanda”.
Limite de cereri
Limitele se aplică pe client, într-o fereastră de 60 de secunde. Depășirea întoarce 429 Too Many Requests, cu Retry-After în header.
| Rută | Limită |
|---|---|
POST /auth/login | 10 cereri / minut |
GET /expedition/public/tracking | 30 cereri / minut |
| Orice altă rută | 120 cereri / minut |
Răspunsurile poartă X-RateLimit-Limit, X-RateLimit-Remaining și X-RateLimit-Reset, deci poți regla ritmul fără să aștepți un 429.
Erori
Erorile au forma standard NestJS. La validare, message este o listă cu fiecare problemă găsită, nu doar cu prima.
{
"statusCode": 400,
"message": [
"Greutatea nu poate depasi 100 kg",
"phoneNSN must be a valid Romanian number"
],
"error": "Bad Request"
}| Cod | Ce înseamnă |
|---|---|
| 400 | Validare eșuată. Citește lista din `message` — acolo scrie exact ce câmp este de vină. |
| 401 | Token lipsă, expirat sau invalid. Reautentifică-te și reia cererea. |
| 403 | Resursa aparține altui cont, sau contul are o restricție (factură scadentă neplătită — corpul poartă `code: "BILLING_LOCKED"`). |
| 404 | Resursa nu există. |
| 409 | Conflict. La anulare înseamnă că coletul este deja la curier; la selecția cotației, că expediția a fost deja creată. |
| 410 | Cotația selectată a expirat. Cere o cotație nouă. |
| 422 | Cererea este înțeleasă, dar nu poate fi executată: lipsesc datele de facturare, sau curierul cere un câmp pe care destinatarul nu îl are (`code: "RECIPIENT_FIELDS_REQUIRED"`). |
| 429 | Ai depășit limita de cereri. |
| 5xx | Eroare la noi sau la curier. Poate fi reîncercată, cu backoff — vezi avertismentul de mai jos. |
Exemplu complet
Tot fluxul, de la autentificare la etichetă, cu curl și jq:
# 1. Autentificare — tokenul este valabil o oră
TOKEN=$(curl -s -X POST https://www.api.livraria.ro/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"integrare@firma.ro","password":"..."}' \
| jq -r .data.accessToken)
# 2. Cotații (cererea este salvată pe cont)
QUOTE=$(curl -s -X POST https://www.api.livraria.ro/public/awb/quotes \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d @quote-body.json)
QR_ID=$(echo "$QUOTE" | jq -r .quoteRequest.id)
# Cel mai ieftin curier care poate duce coletul.
# Niciodată fără filtrul isDisabled: o cotație dezactivată are amount 0.
CQ_ID=$(echo "$QUOTE" | jq -r \
'[.courierQuotes[] | select(.isDisabled == false)]
| sort_by(.amount) | .[0].id')
# 3. Alege curierul
curl -X PUT "https://www.api.livraria.ro/quote-request/$QR_ID/selected-courier-quote" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"courierQuoteId\":\"$CQ_ID\"}"
# 4. Atașează datele de facturare
curl -X POST "https://www.api.livraria.ro/quote-request/$QR_ID/billing-info" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Firma Mea SRL","email":"facturare@firma.ro",
"street":"Calea Victoriei 10","city":"Bucuresti","county":"BUCURESTI"}'
# 5. Creează expediția — AWB-ul se generează la curier
AWB=$(curl -s -X POST https://www.api.livraria.ro/expedition \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d "{\"quoteRequestId\":\"$QR_ID\"}" | jq -r .awbNumber)
# 6. Descarcă eticheta
curl -o eticheta.pdf -H "Authorization: Bearer $TOKEN" \
"https://www.api.livraria.ro/public/awb/print/$AWB?format=pdf&paperSize=A6"Rute de referință rapidă
/auth/loginpublic10/min/public/awb/quotesBearer JWT120/min/quote-request/{id}/selected-courier-quoteBearer JWT/quote-request/{id}/billing-infoBearer JWT/expeditionBearer JWT/public/awb/print/{awbNumber}Bearer JWT/public/awb/cancel/{awbNumber}Bearer JWT/expedition/public/trackingpublic30/minAi nevoie de ajutor cu integrarea?
Spune-ne ce sistem integrezi și la ce pas te-ai oprit. Dacă ai deja un apel care eșuează, trimite-ne corpul cererii și răspunsul primit.
Contactează-ne