Documentație API

Date de referință

Rute publice, fără autentificare, pe care îți validezi datele înainte de a cere o cotație. O combinație greșită de județ, oraș și cod poștal este cel mai frecvent motiv de refuz la curier.

Curieri activi

GET/public/courierspublic

Răspuns 200 OK (extras)

json

[
  {
    "_id": "6577824a89f273256f8ff488",
    "name": "Dpd",
    "slug": "dpd",
    "active": true,
    "capabilities": {
      "cod": true,
      "insurance": true,
      "doorToDoor": true,
      "pickupPointOnly": false,
      "openOnDelivery": "forwarded"
    }
  },
  {
    "_id": "6a56bcf2012656f4e3835a1c",
    "name": "GLS",
    "slug": "gls",
    "active": true,
    "capabilities": {
      "cod": true,
      "insurance": false,
      "doorToDoor": true,
      "pickupPointOnly": false,
      "openOnDelivery": "not_offered"
    }
  }
]

Lista conține numai curierii activi în acest moment. Nu o codifica în aplicația ta: un curier poate fi dezactivat temporar și atunci dispare de aici, deși restul fluxului rămâne neschimbat.

capabilities

Câmp	Tip	Cerut	Descriere
`cod`	boolean	mereu	Curierul acceptă ramburs.
`insurance`	boolean	mereu	Curierul acceptă valoare declarată.
`doorToDoor`	boolean	mereu	Curierul livrează la adresă.
`pickupPointOnly`	boolean	mereu	Curierul livrează exclusiv în puncte de ridicare sau lockere.
`openOnDelivery`	string	mereu	Nu este boolean. Vezi tabelul de mai jos — doar două valori înseamnă că serviciul ajunge efectiv la destinatar.

Valorile openOnDelivery

Valoare	Ce înseamnă
`forwarded`	Serviciul este transmis curierului și se execută.
`forwarded_door_only`	Se execută, dar numai la livrările la adresă — nu în locker.
`not_offered`	Curierul nu are serviciul.
`offered_not_implemented`	Curierul îl oferă, dar integrarea noastră nu îl transmite încă.
`unknown`	Nu avem informația.

Județe, orașe, coduri poștale

Județe

GET/public/location/countiespublic

Răspuns 200 OK (extras)

json

[
  { "_id": "65a05136e3618f2c5b0fce48", "name": "ALBA" },
  { "_id": "65a05136e3618f2c5b0fce49", "name": "ARAD" },
  { "_id": "65a05136e3618f2c5b0fce4a", "name": "ARGES" }
]

43 de intrări, cu majuscule și fără diacritice. Include NECUNOSCUT, folosit pentru adrese nerezolvate.

Orașe

GET/public/location/cities?name={partial}&county={judet}public

Ambii parametri sunt opționali și pot fi combinați. name face potrivire parțială.

Răspuns 200 OK

json

[
  {
    "_id": "6837af78bd813185db7a815e",
    "name": "CLUJ-NAPOCA",
    "county": "CLUJ",
    "municipality": "MUN. CLUJ-NAPOCA",
    "postcode": "400001"
  }
]

Coduri poștale

GET/public/location/postcodespublic

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`postcode`	string	opțional	Caută după cod poștal.
`county / city`	string	opțional	Restrânge la un județ sau un oraș.
`streetName`	string	opțional	Numele străzii, pentru codul la nivel de stradă.
`streetNumber`	number	opțional	Numărul. Prefixele de tip `nr.` și spațiile în plus sunt tolerate și eliminate.
`streetBlock`	string	opțional	Codul blocului. Prefixele `bl.` și `Bloc` sunt tolerate.

Răspuns 200 OK

json

[
  {
    "_id": "65ba208760e31fcf8987a88e",
    "county": "CLUJ",
    "city": "CLUJ-NAPOCA",
    "streetType": "Strada",
    "streetName": "Memorandumului",
    "fullStreetName": "Strada Memorandumului",
    "postcode": "400114",
    "siruta": "54984"
  }
]

Un răspuns gol este un rezultat valid, nu o eroare: înseamnă că nu avem cod poștal pentru combinația cerută. Tratează-l ca atare și lasă utilizatorul să introducă manual.

Rezolvarea denumirilor din propriul sistem

Catalogul nostru păstrează ortografii pe care listele de regiuni din alte platforme nu le folosesc — VILCEA (nu VALCEA), DAMBOVITA, SATU MARE. Rezolvă o dată, păstrează maparea:

// Catalogul nostru nu folosește aceleași denumiri ca orice platformă.
// Nu trimite valoarea brută din magazinul tău — rezolvă-o o dată
// și păstrează maparea.
const ALIASES = {
  'Vâlcea': 'VILCEA',
  'Valcea': 'VILCEA',
  'Dâmbovița': 'DAMBOVITA',
  'Dimbovita': 'DAMBOVITA',
  'Satu-Mare': 'SATU MARE',
};

const counties = await fetch(`${API}/public/location/counties`)
  .then(r => r.json());

const normalise = (s) =>
  s.normalize('NFD').replace(/\p{Diacritic}/gu, '').toUpperCase().trim();

function resolveCounty(raw) {
  const wanted = normalise(ALIASES[raw] ?? raw);
  return counties.find(c => normalise(c.name) === wanted)?.name ?? null;
}

Puncte de ridicare și lockere

GET/pudo-pointspublic

Toate punctele, de la toți curierii. Este un răspuns mare — câteva mii de intrări — deci folosește-l pentru sincronizări periodice, nu la fiecare afișare de coș.

GET/pudo-points/by-courier?courier={slug}public

Punctele unui singur curier. slug este cel din GET /public/couriers.

Răspuns 200 OK (o intrare)

json

[
  {
    "provider": "Dpd",
    "id": "28001",
    "name": "BUCURESTI - CORBITA 3C (OUTDOOR LOCKER)",
    "address": {
      "city": "Bucuresti",
      "postalCode": "010011",
      "country": "Romania"
    },
    "coordinates": { "latitude": 44.409049, "longitude": 26.058635 },
    "schedule": [
      { "day": 0, "openingHour": "00:00", "closingHour": "23:59" }
    ],
    "contact": {},
    "capabilities": {
      "lockerSizes": [
        { "size": "S", "available": 1 },
        { "size": "M", "available": 1 },
        { "size": "L", "available": 1 }
      ],
      "paymentTypes": ["CARD"]
    }
  }
]

GET/pudo-points/closest?address={adresa}public

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`address`	string	obligatoriu	Adresa de la care se măsoară distanța.
`courier`	string	opțional	Restrânge rezultatele la un singur curier, după slug.
`limit`	number	opțional	Câte rezultate, implicit 10.
`radiusKm`	number	opțional	Rază în kilometri. Este ignorat când trimiți și `courier`.

Punctele tale proprii de ridicare, dacă ai înregistrat vreunul, se citesc separat: GET /public/pickup-points/me (autentificat). Lista globală de puncte Livrǎria este la GET /public/pickup-points.

Fără autentificare

Toate rutele de pe această pagină sunt publice. Le poți apela din front-end, dar sunt supuse limitei generale de cereri, așa că pentru liste mari (orașe, puncte de ridicare) e mai bine să le sincronizezi pe serverul tău decât să le ceri la fiecare vizitator.

bash

curl https://www.api.livraria.ro/public/location/counties

Ai nevoie de ajutor?

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

Contactează-ne

Curieri activi

GET/public/courierspublic

Răspuns 200 OK (extras)

json

[
  {
    "_id": "6577824a89f273256f8ff488",
    "name": "Dpd",
    "slug": "dpd",
    "active": true,
    "capabilities": {
      "cod": true,
      "insurance": true,
      "doorToDoor": true,
      "pickupPointOnly": false,
      "openOnDelivery": "forwarded"
    }
  },
  {
    "_id": "6a56bcf2012656f4e3835a1c",
    "name": "GLS",
    "slug": "gls",
    "active": true,
    "capabilities": {
      "cod": true,
      "insurance": false,
      "doorToDoor": true,
      "pickupPointOnly": false,
      "openOnDelivery": "not_offered"
    }
  }
]

Lista conține numai curierii activi în acest moment. Nu o codifica în aplicația ta: un curier poate fi dezactivat temporar și atunci dispare de aici, deși restul fluxului rămâne neschimbat.

capabilities

Câmp	Tip	Cerut	Descriere
`cod`	boolean	mereu	Curierul acceptă ramburs.
`insurance`	boolean	mereu	Curierul acceptă valoare declarată.
`doorToDoor`	boolean	mereu	Curierul livrează la adresă.
`pickupPointOnly`	boolean	mereu	Curierul livrează exclusiv în puncte de ridicare sau lockere.
`openOnDelivery`	string	mereu	Nu este boolean. Vezi tabelul de mai jos — doar două valori înseamnă că serviciul ajunge efectiv la destinatar.

Valorile openOnDelivery

Valoare	Ce înseamnă
`forwarded`	Serviciul este transmis curierului și se execută.
`forwarded_door_only`	Se execută, dar numai la livrările la adresă — nu în locker.
`not_offered`	Curierul nu are serviciul.
`offered_not_implemented`	Curierul îl oferă, dar integrarea noastră nu îl transmite încă.
`unknown`	Nu avem informația.

Județe, orașe, coduri poștale

Județe

GET/public/location/countiespublic

Răspuns 200 OK (extras)

json

[
  { "_id": "65a05136e3618f2c5b0fce48", "name": "ALBA" },
  { "_id": "65a05136e3618f2c5b0fce49", "name": "ARAD" },
  { "_id": "65a05136e3618f2c5b0fce4a", "name": "ARGES" }
]

43 de intrări, cu majuscule și fără diacritice. Include NECUNOSCUT, folosit pentru adrese nerezolvate.

Orașe

GET/public/location/cities?name={partial}&county={judet}public

Ambii parametri sunt opționali și pot fi combinați. name face potrivire parțială.

Răspuns 200 OK

json

[
  {
    "_id": "6837af78bd813185db7a815e",
    "name": "CLUJ-NAPOCA",
    "county": "CLUJ",
    "municipality": "MUN. CLUJ-NAPOCA",
    "postcode": "400001"
  }
]

Coduri poștale

GET/public/location/postcodespublic

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`postcode`	string	opțional	Caută după cod poștal.
`county / city`	string	opțional	Restrânge la un județ sau un oraș.
`streetName`	string	opțional	Numele străzii, pentru codul la nivel de stradă.
`streetNumber`	number	opțional	Numărul. Prefixele de tip `nr.` și spațiile în plus sunt tolerate și eliminate.
`streetBlock`	string	opțional	Codul blocului. Prefixele `bl.` și `Bloc` sunt tolerate.

Răspuns 200 OK

json

[
  {
    "_id": "65ba208760e31fcf8987a88e",
    "county": "CLUJ",
    "city": "CLUJ-NAPOCA",
    "streetType": "Strada",
    "streetName": "Memorandumului",
    "fullStreetName": "Strada Memorandumului",
    "postcode": "400114",
    "siruta": "54984"
  }
]

Un răspuns gol este un rezultat valid, nu o eroare: înseamnă că nu avem cod poștal pentru combinația cerută. Tratează-l ca atare și lasă utilizatorul să introducă manual.

Rezolvarea denumirilor din propriul sistem

Catalogul nostru păstrează ortografii pe care listele de regiuni din alte platforme nu le folosesc — VILCEA (nu VALCEA), DAMBOVITA, SATU MARE. Rezolvă o dată, păstrează maparea:

// Catalogul nostru nu folosește aceleași denumiri ca orice platformă.
// Nu trimite valoarea brută din magazinul tău — rezolvă-o o dată
// și păstrează maparea.
const ALIASES = {
  'Vâlcea': 'VILCEA',
  'Valcea': 'VILCEA',
  'Dâmbovița': 'DAMBOVITA',
  'Dimbovita': 'DAMBOVITA',
  'Satu-Mare': 'SATU MARE',
};

const counties = await fetch(`${API}/public/location/counties`)
  .then(r => r.json());

const normalise = (s) =>
  s.normalize('NFD').replace(/\p{Diacritic}/gu, '').toUpperCase().trim();

function resolveCounty(raw) {
  const wanted = normalise(ALIASES[raw] ?? raw);
  return counties.find(c => normalise(c.name) === wanted)?.name ?? null;
}

Puncte de ridicare și lockere

GET/pudo-pointspublic

Toate punctele, de la toți curierii. Este un răspuns mare — câteva mii de intrări — deci folosește-l pentru sincronizări periodice, nu la fiecare afișare de coș.

GET/pudo-points/by-courier?courier={slug}public

Punctele unui singur curier. slug este cel din GET /public/couriers.

Răspuns 200 OK (o intrare)

json

[
  {
    "provider": "Dpd",
    "id": "28001",
    "name": "BUCURESTI - CORBITA 3C (OUTDOOR LOCKER)",
    "address": {
      "city": "Bucuresti",
      "postalCode": "010011",
      "country": "Romania"
    },
    "coordinates": { "latitude": 44.409049, "longitude": 26.058635 },
    "schedule": [
      { "day": 0, "openingHour": "00:00", "closingHour": "23:59" }
    ],
    "contact": {},
    "capabilities": {
      "lockerSizes": [
        { "size": "S", "available": 1 },
        { "size": "M", "available": 1 },
        { "size": "L", "available": 1 }
      ],
      "paymentTypes": ["CARD"]
    }
  }
]

GET/pudo-points/closest?address={adresa}public

Parametri de interogare

Câmp	Tip	Cerut	Descriere
`address`	string	obligatoriu	Adresa de la care se măsoară distanța.
`courier`	string	opțional	Restrânge rezultatele la un singur curier, după slug.
`limit`	number	opțional	Câte rezultate, implicit 10.
`radiusKm`	number	opțional	Rază în kilometri. Este ignorat când trimiți și `courier`.

Fără autentificare

bash

curl https://www.api.livraria.ro/public/location/counties