Documentație API

Creare expediție

Ultimul pas al fluxului. Transformă o cerere de cotație pregătită în expediție reală și generează AWB-ul la curierul ales.

Creare

POST/expeditionBearer JWT120/min

Corpul cererii

Câmp	Tip	Cerut	Descriere
`quoteRequestId`	string (UUID)	obligatoriu	Cererea de cotație, cu cotație selectată și date de facturare atașate.
`pickupDate`	string (ISO 8601)	opțional	Data de ridicare pe care o ceri curierului. Lipsa ei lasă curierul să programeze ridicarea după regulile lui.
`notes`	string	opțional	Observații pentru expediere.

Cerere

json

{
  "quoteRequestId": "3f9c1a34-7b2e-4d81-9f05-6c1e8a4b2d70",
  "pickupDate": "2026-10-29T10:00:00.000Z",
  "notes": "Fragil"
}

Răspuns 201 Created

json

{
  "id": "9d1e5b77-4a02-4c31-8f6d-5b7e2a1c9043",
  "awbNumber": "81356295593",
  "trackingNumber": "81356295593",
  "createdAt": "2026-10-28T09:05:12.000Z",
  "courierId": "6577824a89f273256f8ff488",
  "price": 18.95,
  "status": {
    "id": "a1b2c3d4-...",
    "code": "NEW",
    "label": "New Order",
    "final": false
  }
}

Generarea AWB-ului

AWB-ul se cere curierului sincron, în timpul apelului. În mod normal răspunsul conține deja awbNumber și trackingNumber. Dacă sistemul curierului răspunde târziu, expediția rămâne creată cu awbNumber: null, iar numărul se completează când curierul răspunde.

Cum eviți o expediere dublă

O eroare 5xx nu înseamnă că nu s-a creat nimic. Înainte de a reîncerca, caută expediția după referința ta:

// POST /expedition a întors 5xx. NU reîncerca direct.
// Caută mai întâi după propria ta referință.
const existing = await fetch(
  `${API}/expedition?search=${encodeURIComponent('API-10023')}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());

if (existing.meta.total > 0) {
  // Expediția există. Dacă awbNumber este încă null,
  // curierul nu a răspuns la timp — reia citirea mai târziu.
  return existing.data[0];
}

// Abia acum poți reîncerca, cu același quoteRequestId.

Erori

Cod	Ce înseamnă	Ce faci
403	Cont blocat de o factură scadentă neplătită (corpul poartă `code: "BILLING_LOCKED"`), sau credit insuficient.	Plătește factura restantă. Nicio expediție nu se creează până atunci.
422	Lipsesc datele de facturare, sau curierul cere câmpuri pe care destinatarul nu le are (`code: "RECIPIENT_FIELDS_REQUIRED"`).	Completează ce lipsește. În ambele cazuri nu s-a creat nicio expediție.
410	Cotația selectată a expirat (sunt valabile 24 de ore).	Reia de la cererea de cotație.
5xx	Eroare la noi sau la curier.	Caută expediția după externalRef înainte de a reîncerca.

Citirea expedițiilor

O singură expediție

GET/expedition/{id}Bearer JWT

Vederea completă, într-un singur apel: status curent și istoricul de statusuri, AWB și număr de urmărire, curier, preț, datele de ridicare și livrare raportate de curier, pachetele, expeditorul și destinatarul cu adrese, rambursul și valoarea declarată, tipul de livrare și datele de locker. Include și content.measuredTotalWeight — greutatea măsurată de curier, când a recântărit coletul.

Lista expedițiilor

GET/expeditionBearer JWT

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`page`	number	opțional	Implicit 1.
`limit`	number	opțional	Implicit 50, maximum 100.
`status`	string	opțional	Unul sau mai multe coduri de status, separate prin virgulă. Un cod necunoscut întoarce 400, nu o listă goală. Vezi lista codurilor.
`search`	string	opțional	AWB, număr de urmărire, referința ta, date de expeditor/destinatar sau un număr de telefon. Telefonul se caută pe numărul național, deci `0700000001`, `+40700000001` și `700000001` sunt echivalente. Termenii cu mai puțin de 6 cifre nu sunt tratați ca telefon.
`dateFrom / dateTo`	string	opțional	`YYYY-MM-DD` în ora României, sau un moment ISO 8601 complet. `dateTo` include ziua întreagă, nu doar miezul nopții.
`courierId`	string	opțional	Doar expedițiile duse de acest curier.

Răspuns 200 OK

json

{
  "data": [
    {
      "id": "9d1e5b77-4a02-4c31-8f6d-5b7e2a1c9043",
      "awbNumber": "81356295593",
      "trackingNumber": "81356295593",
      "createdAt": "2026-10-28T09:05:12.000Z",
      "courierId": "6577824a89f273256f8ff488",
      "price": 18.95,
      "status": { "code": "IN_TRANSIT", "label": "In Transit", "final": false },
      "courier": { "name": "Dpd", "slug": "dpd" },
      "canCancel": false,
      "cancelBlockedReason": "DSC_WINDOW_EXPIRED",
      "cancelDeadline": "2026-10-28T09:35:12.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
}

Căutare după număr de urmărire

GET/expedition/tracking?trackingNumber={nr}Bearer JWT

Varianta autentificată, cu date complete. Pentru pagina ta publică de urmărire folosește ruta publică, care maschează datele personale.

Câmpurile de anulare

Orice expediție citită prin API poartă trei câmpuri care spun dacă poate fi încă anulată. Le citești înainte de a oferi un buton de anulare, ca să nu propui o acțiune care va eșua:

Câmp	Tip	Cerut	Descriere
`canCancel`	boolean	mereu	Dacă expedierea poate fi anulată chiar acum.
`cancelBlockedReason`	string \| null	când canCancel este false	Motivul, în formă citibilă de mașină — de exemplu `DSC_WINDOW_EXPIRED`.
`cancelDeadline`	string \| null	opțional	Momentul în care se închide fereastra de anulare. Null când curierul nu impune o limită de timp.

Anularea propriu-zisă este descrisă în Etichete AWB și anulare.

Ai nevoie de ajutor?

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

Contactează-ne

Creare

POST/expeditionBearer JWT120/min

Corpul cererii

Câmp	Tip	Cerut	Descriere
`quoteRequestId`	string (UUID)	obligatoriu	Cererea de cotație, cu cotație selectată și date de facturare atașate.
`pickupDate`	string (ISO 8601)	opțional	Data de ridicare pe care o ceri curierului. Lipsa ei lasă curierul să programeze ridicarea după regulile lui.
`notes`	string	opțional	Observații pentru expediere.

Cerere

json

{
  "quoteRequestId": "3f9c1a34-7b2e-4d81-9f05-6c1e8a4b2d70",
  "pickupDate": "2026-10-29T10:00:00.000Z",
  "notes": "Fragil"
}

Răspuns 201 Created

json

{
  "id": "9d1e5b77-4a02-4c31-8f6d-5b7e2a1c9043",
  "awbNumber": "81356295593",
  "trackingNumber": "81356295593",
  "createdAt": "2026-10-28T09:05:12.000Z",
  "courierId": "6577824a89f273256f8ff488",
  "price": 18.95,
  "status": {
    "id": "a1b2c3d4-...",
    "code": "NEW",
    "label": "New Order",
    "final": false
  }
}

Generarea AWB-ului

Cum eviți o expediere dublă

O eroare 5xx nu înseamnă că nu s-a creat nimic. Înainte de a reîncerca, caută expediția după referința ta:

// POST /expedition a întors 5xx. NU reîncerca direct.
// Caută mai întâi după propria ta referință.
const existing = await fetch(
  `${API}/expedition?search=${encodeURIComponent('API-10023')}`,
  { headers: { Authorization: `Bearer ${token}` } }
).then(r => r.json());

if (existing.meta.total > 0) {
  // Expediția există. Dacă awbNumber este încă null,
  // curierul nu a răspuns la timp — reia citirea mai târziu.
  return existing.data[0];
}

// Abia acum poți reîncerca, cu același quoteRequestId.

Erori

Cod	Ce înseamnă	Ce faci
403	Cont blocat de o factură scadentă neplătită (corpul poartă `code: "BILLING_LOCKED"`), sau credit insuficient.	Plătește factura restantă. Nicio expediție nu se creează până atunci.
422	Lipsesc datele de facturare, sau curierul cere câmpuri pe care destinatarul nu le are (`code: "RECIPIENT_FIELDS_REQUIRED"`).	Completează ce lipsește. În ambele cazuri nu s-a creat nicio expediție.
410	Cotația selectată a expirat (sunt valabile 24 de ore).	Reia de la cererea de cotație.
5xx	Eroare la noi sau la curier.	Caută expediția după externalRef înainte de a reîncerca.

Citirea expedițiilor

O singură expediție

GET/expedition/{id}Bearer JWT

Lista expedițiilor

GET/expeditionBearer JWT

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`page`	number	opțional	Implicit 1.
`limit`	number	opțional	Implicit 50, maximum 100.
`status`	string	opțional	Unul sau mai multe coduri de status, separate prin virgulă. Un cod necunoscut întoarce 400, nu o listă goală. Vezi lista codurilor.
`search`	string	opțional	AWB, număr de urmărire, referința ta, date de expeditor/destinatar sau un număr de telefon. Telefonul se caută pe numărul național, deci `0700000001`, `+40700000001` și `700000001` sunt echivalente. Termenii cu mai puțin de 6 cifre nu sunt tratați ca telefon.
`dateFrom / dateTo`	string	opțional	`YYYY-MM-DD` în ora României, sau un moment ISO 8601 complet. `dateTo` include ziua întreagă, nu doar miezul nopții.
`courierId`	string	opțional	Doar expedițiile duse de acest curier.

Răspuns 200 OK

json

{
  "data": [
    {
      "id": "9d1e5b77-4a02-4c31-8f6d-5b7e2a1c9043",
      "awbNumber": "81356295593",
      "trackingNumber": "81356295593",
      "createdAt": "2026-10-28T09:05:12.000Z",
      "courierId": "6577824a89f273256f8ff488",
      "price": 18.95,
      "status": { "code": "IN_TRANSIT", "label": "In Transit", "final": false },
      "courier": { "name": "Dpd", "slug": "dpd" },
      "canCancel": false,
      "cancelBlockedReason": "DSC_WINDOW_EXPIRED",
      "cancelDeadline": "2026-10-28T09:35:12.000Z"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 50, "totalPages": 1 }
}

Căutare după număr de urmărire

GET/expedition/tracking?trackingNumber={nr}Bearer JWT

Varianta autentificată, cu date complete. Pentru pagina ta publică de urmărire folosește ruta publică, care maschează datele personale.

Câmpurile de anulare

Orice expediție citită prin API poartă trei câmpuri care spun dacă poate fi încă anulată. Le citești înainte de a oferi un buton de anulare, ca să nu propui o acțiune care va eșua:

Câmp	Tip	Cerut	Descriere
`canCancel`	boolean	mereu	Dacă expedierea poate fi anulată chiar acum.
`cancelBlockedReason`	string \| null	când canCancel este false	Motivul, în formă citibilă de mașină — de exemplu `DSC_WINDOW_EXPIRED`.
`cancelDeadline`	string \| null	opțional	Momentul în care se închide fereastra de anulare. Null când curierul nu impune o limită de timp.

Anularea propriu-zisă este descrisă în Etichete AWB și anulare.