Documentație API

Dicționar de date

Fiecare câmp al cererii de cotație, cu tipul lui și limita pe care API-ul o verifică efectiv. Când o cerere întoarce 400, răspunsul ei este aici.

Corpul cererii de cotație

Se trimite la nivelul de sus, atât la POST /public/awb/quotes, cât și la POST /public/awb/quick-quotes.

Câmp	Tip	Cerut	Descriere
`sender`	Subject	obligatoriu	Expeditorul. `email` este obligatoriu pentru această parte.
`recipient`	Subject	obligatoriu	Destinatarul. `email` este opțional aici.
`content.packages`	Package[]	obligatoriu	Între 1 și 20 de pachete.
`service`	Service	obligatoriu	Livrare sâmbătă, deschidere la livrare, ramburs, valoare declarată.
`paymentInfo.courierServicePayer`	enum	obligatoriu	`SENDER`, `RECIPIENT` sau `THIRD_PARTY`.
`packageDescription`	string	obligatoriu	Ce vede curierul ca conținut. Emoji se elimină, iar textul se taie la 50 de caractere.
`shipmentNote`	string	opțional	Observație transmisă curierului.
`externalRef`	string	opțional	Referința comenzii din sistemul tău, cel mult 255 de caractere. Trebuie să înceapă cu un prefix de integrare — vezi mai jos.
`originLockerId`	string	opțional	Lockerul de predare. Se trimite împreună cu `originCourierId`.
`destinationLockerId`	string	opțional	Lockerul de livrare. Se trimite împreună cu `destinationCourierId`.
`saveRecipient`	boolean	opțional	Salvează destinatarul în lista de destinatari a contului.

Subject — expeditor și destinatar

Aceeași structură pentru amândoi. Diferă o singură regulă: email.

Exemplu

json

{
  "name": "Firma Mea SRL",
  "isCompany": true,
  "companyName": "Firma Mea SRL",
  "cui": "RO12345678",
  "email": "logistica@firma.ro",
  "phoneCountryCode": "+40",
  "phoneNSN": "700000000",
  "clientId": "CLIENT-4471",
  "address": {
    "country": "Romania",
    "county": "BUCURESTI",
    "city": "BUCURESTI",
    "postcode": "010061",
    "street": "Calea Victoriei",
    "streetNumber": "10",
    "block": "B2",
    "staircase": "1",
    "floor": "3",
    "apartment": "12"
  }
}

Câmp	Tip	Cerut	Descriere
`name`	string	obligatoriu	Trebuie să conțină cel puțin o literă. Un nume numai din cifre sau simboluri este refuzat.
`email`	string	expeditor: da	Obligatoriu pentru expeditor — pe el pleacă confirmarea expedierii. Opțional pentru destinatar, dar unele servicii îl cer; atunci primești 422 cu RECIPIENT_FIELDS_REQUIRED.
`phoneCountryCode`	string	obligatoriu	Prefixul internațional, de exemplu `+40`.
`phoneNSN`	string	obligatoriu	Numărul național, fără prefix de țară și fără zeroul din față. Pentru `+40`: exact 9 cifre, începând cu 2, 3 sau 7.
`address`	Address	obligatoriu	Vezi secțiunea următoare.
`isCompany`	boolean	opțional	Când este `true`, `companyName` devine obligatoriu. Influențează și plafonul de ramburs.
`companyName`	string	condiționat	Obligatoriu când `isCompany` este `true`.
`cui`	string	opțional	Codul fiscal.
`clientId`	string	opțional	Identificatorul clientului în sistemul tău. Se păstrează pe expediție.

Address

Câmp	Tip	Cerut	Descriere
`country`	string	obligatoriu	De exemplu `Romania`.
`county`	string	obligatoriu	Așa cum apare în catalogul de județe: majuscule, fără diacritice.
`city`	string	obligatoriu	Verifică-l în catalogul de orașe.
`postcode`	string	obligatoriu	Codul poștal. Combinația greșită județ / oraș / cod poștal este cel mai frecvent motiv de refuz la curier.
`street`	string	obligatoriu	Numele străzii, fără număr.
`streetNumber`	string	opțional	Numărul. Ține-l separat de nume — nu îl îndesa în street.
`block, staircase, floor, apartment`	string	opțional	Bloc, scară, etaj, apartament.
`localityPostcode`	string	opțional	Codul poștal al localității, când diferă de cel al străzii.

Package

Câmp	Tip	Cerut	Descriere
`weight`	number	obligatoriu	Kilograme, între 0,01 și 100 — per pachet. Mai mult de două zecimale se rotunjește în sus la următorii 0,01 kg.
`length, width, height`	number	obligatoriu	Centimetri, între 1 și 300 fiecare, independent. Nu există verificare de circumferință sau de volum agregat.
`packageType`	string	obligatoriu	`package` sau `envelope`. Vezi nota de mai jos.

Service

Câmp	Tip	Cerut	Descriere
`saturdayDelivery`	boolean	obligatoriu	Livrare sâmbătă. Trimite-l explicit, chiar și false.
`openOnDelivery`	boolean	obligatoriu	Deschidere la livrare. Nu toți curierii o duc până la destinatar — vezi `openOnDeliveryUnsupported` pe cotație.
`cod.amount`	number	opțional	Suma de încasat de la destinatar, în RON. Plafonul depinde de expeditor — vezi tabelul de limite.
`cod.bankAccount`	string	condiționat	IBAN românesc. Devine obligatoriu când `cod.amount` este mai mare decât 0.
`cod.collector`	enum	condiționat	`CLIENT` sau `THIRD_PARTY`. Obligatoriu când se cere ramburs.
`insurance.amount`	number	opțional	Valoarea declarată, în RON. Pe baza ei se calculează despăgubirea în caz de pierdere.

Limitele validate de API

Acestea sunt verificările care produc un 400 sau care dezactivează o cotație. Nu sunt estimări — sunt regulile pe care le aplică serverul.

Refuză cererea (400)

Ce	Limită
Ramburs, expeditor persoană juridică	maximum 10.000 RON
Ramburs, expeditor persoană fizică	maximum 5.000 RON
Valoare declarată	maximum 40.000 RON
Greutate pe pachet	0,01 – 100 kg
Fiecare dimensiune a unui pachet	1 – 300 cm
Pachete pe expediere	1 – 20
Ramburs cerut fără IBAN sau fără collector	ambele devin obligatorii
E-mail expeditor lipsă	obligatoriu
Telefon +40 care nu are 9 cifre începând cu 2, 3 sau 7	refuzat

Dezactivează cotațiile de locker

Ce	Limită
Pachete, când expedierea atinge un locker	exact 1
Greutate	maximum 30 kg
Lungime	maximum 44,3 cm
Lățime	maximum 45 cm
Înălțime	maximum 40,4 cm

Nu există plafon pe greutatea totală a expedierii — doar pe fiecare pachet. Unii curieri aplică limite proprii, mai strânse, și atunci cotația lor vine cu isDisabled: true și motivul în error.message.

Enumerări

courierServicePayer

Valoare	Ce înseamnă
`SENDER`	Transportul este plătit de expeditor.
`RECIPIENT`	Transportul este plătit de destinatar.
`THIRD_PARTY`	Transportul este plătit de un terț.

cod.collector

Valoare	Ce înseamnă
`CLIENT`	Rambursul se virează în contul tău.
`THIRD_PARTY`	Rambursul merge către un terț.

deliveryType (în răspunsul cotației)

Valoare	Ce înseamnă
`DOOR_TO_DOOR`	De la adresă la adresă.
`DOOR_TO_LOCKER`	Ridicare de la adresă, livrare în locker.
`LOCKER_TO_DOOR`	Predare în locker, livrare la adresă.
`LOCKER_TO_LOCKER`	Din locker în locker.

Prefixe acceptate pentru externalRef

Fiecare integrare își marchează referințele. Pentru o integrare proprie, prin API, folosește API-.

prefixe

API-          integrări proprii, prin API
SHOPIFY-     modulul Shopify
WP-          modulul WooCommerce
PRESTASHOP-  modulul PrestaShop
OPENCART-    modulul OpenCart
GOMAG-       integrarea Gomag
MERCHANTPRO- integrarea MerchantPro
BASELINKER-  integrarea BaseLinker

O referință care nu începe cu unul dintre acestea întoarce 400. Exemplu valid: API-10023.

Formate de etichetă

format: pdf sau zpl. paperSize: A4, A6 sau A4_4xA6.

Coduri de status ale expediției

Lista completă, cu explicații și cu steagul final, este pe pagina Urmărire expediții.

Ai nevoie de ajutor?

Dacă o cerere este refuzată cu un mesaj care nu se potrivește cu nimic de aici, trimite-ne corpul cererii și răspunsul — poate fi o regulă pe care trebuie să o documentăm.

Contactează-ne