e-packet API

Adresa de bază

https://zbdnzolswscjoxhpsbtt.supabase.co/functions/v1/api/v1

Specificația OpenAPI

openapi.json — pentru Postman și alte unelte

API-ul e-packet vă permite să generați AWB-uri din propriul sistem (magazin online, ERP, aplicație), cu prețurile și creditul contului dumneavoastră e-packet.

Cum obțineți o cheie

Cheile API se emit la cerere: contactați-ne. Orice cont e-packet poate primi o cheie. Creditul se alimentează din aplicație, ca de obicei, iar prețurile sunt exact cele pe care le vedeți în aplicație pentru contul dumneavoastră.

Autentificare

Trimiteți cheia la fiecare cerere, în antetul Authorization:

Authorization: Bearer epk_live_…

Cheia este un secret de server. Nu o puneți niciodată într-o pagină web, într-o aplicație mobilă sau într-un depozit de cod public. API-ul nu răspunde cererilor făcute din browser.

Live și test

• epk_live_… — AWB-uri reale, la curieri.
• epk_test_… — mediul de test (sandbox) al curierilor, doar pentru DPD și Sameday, singurii curieri cu un mediu de test real. Alt curier cu o cheie de test este refuzat (422, sandbox_not_supported), iar tarifele includ doar DPD și Sameday. AWB-urile de test sunt salvate, dar nu se ia nimic din credit și creditul nu este verificat.

O cheie de test vede doar AWB-urile create cu o cheie de test, iar o cheie live nu le vede.

Limite de utilizare

Cel mult 60 de cereri pe minut pentru o cheie, toate adresele la un loc. Peste limită primiți 429 cu antetul Retry-After; nimic nu este creat sau taxat.

Erori

Toate erorile au aceeași formă: un cod HTTP, un code în engleză (stabil, pentru program), un message în română (pentru oameni) și source, care spune cine a refuzat: courier (curierul) sau e-packet (noi). Pentru erorile de câmp primiți și field.

Refuzurile curierului

Când curierul refuză un AWB primiți 502, courier_refused, source: "courier", plus:

• courier — curierul care a refuzat (DPD, SDY, CGS, FCR, DSC, TCE);
• reason — motivul, stabil, pentru program (tabelul de mai jos);
• field — câmpul din cererea dumneavoastră, când curierul îl indică.

{
  "error": {
    "code": "courier_refused",
    "message": "DPD a refuzat codul poștal destinatarului: nu corespunde localității sau adresei. Verificați codul poștal al adresei.",
    "source": "courier",
    "courier": "DPD",
    "reason": "invalid_postcode",
    "field": "recipient.postcode"
  }
}

Mesajul (message) este scris de noi, nu textul curierului, și se poate îmbunătăți în timp: programul dumneavoastră trebuie să se bazeze pe code și reason, nu pe text. Lista de motive poate crește; tratați orice reason necunoscut ca pe other. Un AWB refuzat nu se taxează.

Rar, o verificare a noastră oprește expedierea înainte să ajungă la curier: primiți tot courier_refused, dar cu source: "e-packet" și reason: "other".

Câmpurile necunoscute sunt refuzate (422), ca o greșeală de scriere să nu treacă neobservată.

Lucruri importante

• Tariful este o estimare. Nu există rezervare de preț: AWB-ul se taxează la prețul calculat în momentul generării, exact ca în aplicație. Diferențele apar rar (de exemplu la o schimbare de tarif a curierului sau a abonamentului).
• Cheile de test generează doar cu DPD și Sameday, în mediul lor de test, și nu se taxează. Ceilalți curieri nu au un mediu de test real, așa că sunt refuzați.
• Fiecare cerere `POST /awb` creează și taxează un AWB nou (cu o cheie live), chiar dacă trimiteți aceeași referință de două ori. Evitarea dublurilor (de exemplu la reîncercare după un timeout) este responsabilitatea sistemului dumneavoastră.
• Ridicarea se comandă automat după AWB pentru DPD, FAN Courier și Dragon Star, când expeditorul este o adresă. Dacă ridicarea nu poate fi comandată, AWB-ul rămâne valid.
• Anularea unui AWB nu este disponibilă prin API: contactați-ne.

Limite pe curier

Se aplică, pe lângă regulile câmpurilor, limita mai strictă dintre aplicație și curier. Peste limită primiți 422 cu câmpul vizat, înainte ca ceva să fie trimis curierului.

Pentru toți curierii: colet 0,1–100 kg, laturi 1–300 cm (apoi limita curierului); plic cel mult 0,5 kg (TCE 0,3 kg); un singur colet la locker; deschiderea coletului nu se poate la locker sau la plic; asigurarea nu se poate pentru colete peste 32 kg; livrarea sâmbăta doar la Cargus.

Statusuri

Codurile din GET /status (câmpul status). Cele finale nu se mai schimbă.

Formatul etichetei: A6 există la DPD, Sameday și Cargus; FAN Courier tipărește A4; Dragon Star și TCE au o singură etichetă, a curierului. Un format indisponibil devine A4.

{
  "data": [
    {
      "id": 109,
      "name": "CLUJ NAPOCA",
      "display_name": "Cluj Napoca (Cluj)",
      "county": "CJ"
    }
  ],
  "page": 1,
  "page_size": 1000,
  "total": 1,
  "has_more": false
}

{
  "error": {
    "code": "invalid_field",
    "message": "Codul poștal are exact 6 cifre.",
    "field": "recipient.postcode"
  }
}

{
  "error": {
    "code": "invalid_field",
    "message": "Codul poștal are exact 6 cifre.",
    "field": "recipient.postcode"
  }
}

{
  "sender_locality_id": 14515,
  "recipient_locality_id": 109,
  "package_type": "parcel",
  "parcels": [
    {
      "weight": 2,
      "length": 30,
      "width": 20,
      "height": 10
    }
  ],
  "delivery_type": "ALL",
  "cash_on_delivery": 150
}

{
  "quotes": [
    {
      "courier": "DPD",
      "delivery_type": "D2D",
      "available": true,
      "price": 28.68,
      "currency": "RON"
    },
    {
      "courier": "TCE",
      "delivery_type": "D2D",
      "available": false,
      "reason": "Curierul nu oferă un tarif pentru acest transport."
    }
  ]
}

{
  "error": {
    "code": "invalid_field",
    "message": "Codul poștal are exact 6 cifre.",
    "field": "recipient.postcode"
  }
}

{
  "courier": "DPD",
  "delivery_type": "D2D",
  "sender": {
    "first_name": "Ion",
    "last_name": "Popescu",
    "company": "Magazin SRL",
    "phone": "0712345678",
    "email": "comenzi@magazin.ro",
    "locality_id": 14515,
    "postcode": "010011",
    "street": "Strada Exemplu",
    "number": "5"
  },
  "recipient": {
    "first_name": "Ana",
    "last_name": "Ionescu",
    "phone": "0722333444",
    "email": "ana@example.ro",
    "locality_id": 109,
    "postcode": "400001",
    "street": "Strada Mare",
    "number": "12",
    "block": "A2",
    "apartment": "7"
  },
  "package_type": "parcel",
  "parcels": [
    {
      "weight": 2,
      "length": 30,
      "width": 20,
      "height": 10
    }
  ],
  "contents": "Haine",
  "cash_on_delivery": {
    "amount": 150,
    "account_holder": "Ion Popescu",
    "iban": "RO49AAAA1B31007593840000",
    "bank_name": "Banca Transilvania"
  },
  "reference": "COMANDA-1042"
}

{
  "awb_number": "80512345678",
  "courier": "DPD",
  "delivery_type": "D2D",
  "price": 31.12,
  "currency": "RON",
  "credit_left": 468.88,
  "reference": "COMANDA-1042",
  "pickup": {
    "requested": true,
    "id": "123456",
    "from": "2026-10-05T09:00:00",
    "to": "2026-10-05T18:00:00"
  }
}

{
  "error": {
    "code": "invalid_field",
    "message": "Codul poștal are exact 6 cifre.",
    "field": "recipient.postcode"
  }
}

{
  "awb": "80512345678",
  "courier": "DPD",
  "status": "in_tranzit",
  "label": "În tranzit",
  "is_final": false,
  "status_at": "2026-10-05T11:20:00Z",
  "checked_at": "2026-10-05T12:01:00Z"
}