Documentație API

Documentația completă a API-ului Shipo: autentificare, endpoint-uri, parametri, exemple de cod și răspunsuri. Integrează platforma în aplicația ta și automatizează expedierea coletelor.

API Endpoints

Modificări
Prezentare generală
Autentificare
Client
Orașe
Străzi
Curieri
Tarife
Lockere & PUDO
Expedieri
Retururi
Tracking

Modificări API

Changelog

Aici sunt listate modificările importante ale API-ului. Verifică această secțiune înainte de a face actualizări la integrarea ta. Modificările marcate Acțiune necesară pot cere schimbări în integrarea ta.

Adresele salvate ale contului, atât cele de ridicare (sender), cât și cele de livrare (recipient), pot fi acum listate, citite, create, modificate și șterse direct prin API, fără să intri pe site. GET /client/address le listează paginat, cu filtrul opțional party. PATCH /client/address/{id} modifică doar câmpurile trimise. O adresă de ridicare poate fi marcată ca implicită cu is_default. ID-urile se trimit în POST /shipment ca sender_address_id (ridicare) sau recipient_address_id (livrare), la serviciile cu adresă. Atenție: aceste endpoint-uri răspund la erorile de validare cu codul HTTP 422, nu cu 200 ca endpoint-urile mai vechi.
GET /client/address_list funcționează în continuare, dar va fi eliminat în curând. Trece integrarea pe GET /client/address?party=sender, care returnează aceleași adrese de ridicare. Fiecare adresă are aceleași câmpuri de adresă (id, alias, name, company_name, phone, email și câmpurile address_*), plus is_default (adresa de ridicare implicită), complete (dacă adresa poate fi folosită într-o expediere) și full_address (adresa pe un singur rând). Sectorul vine ca număr (3), nu ca text ("Sectorul 3"). Câmpurile interne, de exemplu client_id sau courier_id, nu mai sunt incluse. Lista nu mai vine direct ca răspuns: adresele sunt în câmpul data, alături de pagination (implicit 100 de adrese pe pagină, maxim 500 cu per_page).
Regula introdusă pe 29.09.2026 pentru GLS și DPD se aplică acum tuturor curierilor, inclusiv Sameday și Cargus. La orice serviciu cu predare în locker sau punct PUDO (sender_address_type locker sau pudo), pe lângă sender_address_id (ID-ul punctului din /points) trebuie trimise și câmpurile de adresă ale expeditorului: orașul (sender_address_city sau sender_address_city_id), strada (sender_address_street sau sender_address_street_id), numărul (sender_address_street_no) și, pentru București, sectorul (sender_address_sector). Coletul care nu poate fi livrat se returnează la această adresă. La Sameday, coletul se întoarce mai întâi în easybox-ul în care a fost predat și ajunge la adresă doar dacă nu este ridicat de acolo la timp. Fără aceste câmpuri, POST /shipment răspunde cu Validation failed. Serviciile cu ridicare de la adresă nu sunt afectate.
La serviciile GLS și DPD cu predare în locker sau punct PUDO (sender_address_type locker sau pudo), pe lângă sender_address_id (ID-ul punctului din /points) trebuie trimise acum și câmpurile de adresă ale expeditorului: orașul (sender_address_city sau sender_address_city_id), strada (sender_address_street sau sender_address_street_id), numărul (sender_address_street_no) și, pentru București, sectorul (sender_address_sector). Dacă expedierea nu poate fi livrată, coletul se returnează la această adresă. Anterior aceste câmpuri erau cerute doar la FAN Courier. Fără ele, POST /shipment răspunde cu Validation failed. Serviciile cu ridicare de la adresă nu sunt afectate.
Numele, adresele si celelalte campuri text accepta acum si literele cu sedila ş ţ Ş Ţ, pe langa cele cu virgula ș ț Ș Ț. Anterior un nume ca Ştefan era refuzat cu eroarea invalid characters. La salvare si la trimiterea catre curier ele sunt transformate in forma corecta cu virgula, deci Ştefan apare in expediere ca Ștefan. Nu este nevoie de nicio modificare in integrarea ta.
POST /shipment nu mai trimite automat expedierea catre curier daca esti client cu plata la termen si creditul disponibil nu acopera costul ei. Anterior expedierea pleca oricum, iar contul putea depasi limita de credit. Acum expedierea este salvata, iar raspunsul este 402 cu success: false si id-ul expedierii. Dupa achitarea soldului o poti trimite cu POST /shipment/send/{id}, fara sa o creezi din nou. Verifica in integrarea ta codul de raspuns, nu doar prezenta AWB-ului.
Câmpurile insurance, open_on_delivery, notify_recipient și quick_cod trimise ca text ("false", "true") sunt acum interpretate corect. Anterior, "false" era tratat ca activat, deci se puteau factura servicii nedorite (asigurare, deschidere la livrare) și se putea trimite SMS către destinatar. Dacă integrarea ta trimitea aceste valori ca text, costul expedierilor se poate modifica. Verifică ce trimite. Valori acceptate: true, false, 1, 0, "1", "0", "true", "false"; orice altceva este respins la validare.
A fost adăugat GET /points, care returnează punctele de ridicare valabile pentru un tarif (rate_id), cu filtrare după localitate, județ, text liber sau coordonate. ID-ul returnat se trimite ca recipient_address_id (livrare în locker) sau sender_address_id (ridicare din locker). Atenție: pentru serviciile la adresă aceleași câmpuri primesc ID-ul unei adrese salvate, nu ID-ul unui punct. Documentația a fost clarificată în acest sens.
/client/address_list returnează acum întotdeauna o listă, conform documentației. Anterior, dacă existau adrese salvate, răspunsul era un obiect indexat după id ({"7": {...}}) în loc de [{...}], ceea ce putea genera erori în integrări. În plus, adresele care conțin caractere stocate greșit nu mai duc la un răspuns gol.
A fost adăugat parametrul quick_cod la request-ul /shipment, care activează rambursul rapid (Turbo) și taxează conform tarifului standard sau personalizat al contului. Se aplică doar dacă expedierea are cod > 0.
Cheia API se trimite acum în header-ul auth-key în loc de auth_key. Actualizează integrarea pentru a folosi auth-key (cu cratimă) la request-ul /auth.

Prezentare generală

v1.0

API-ul Shipo permite integrarea programatică cu platforma noastră de expediții. Prin intermediul acestui API poți crea expedieri, calcula tarife, gestiona adrese și urmări colete.

URL de bază

Toate request-urile API trebuie trimise către:
https://api.shipo.ro/

Autentificare

API-ul folosește autentificare în doi pași:

  1. Obține un access token folosind cheia ta API (auth-key) prin endpoint-ul /auth
  2. Folosește token-ul primit ca Bearer Token în header-ul Authorization pentru toate celelalte request-uri

Format răspunsuri

Toate răspunsurile sunt în format JSON. Răspunsurile de succes includ de obicei un câmp success: true, iar erorile includ un câmp message cu detalii despre eroare.

Coduri HTTP

CodDescriere
200Request procesat cu succes
201Resursă creată (de exemplu o adresă salvată, prin POST /client/address)
400Request invalid (date lipsă sau incorecte)
401Neautorizat (token lipsă sau invalid)
403Acces interzis (cheie API invalidă)
404Resursa cerută nu există (de exemplu o adresă salvată cu un ID necunoscut)
405Metodă HTTP nepermisă
422Date invalide, cu lista erorilor în errors. Îl folosesc doar endpoint-urile /client/address; celelalte răspund la erorile de validare cu 200 și success: false
500Eroare internă server

Autentificare

Obligatoriu

Pentru a accesa API-ul, trebuie mai întâi să obții un token de acces. Cheia API o poți genera din Setări → API.

Trimite cheia ta API în header-ul auth-key pentru a primi un token de acces valid 1 oră.

Headers
ParametruTipObligatoriuDescriere
auth-key string Da Cheia ta de autentificare API, generată din setări 
// Obține access token
fetch("https://api.shipo.ro/auth", {
    method: "POST",
    headers: {
        "auth-key": "CHEIA_TA_API"
    }
})
.then(response => response.json())
.then(data => {
    console.log("Access Token:", data.access_token);
    console.log("Expiră în:", data.expires_in, "secunde");
});
$ch = curl_init("https://api.shipo.ro/auth");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "auth-key: CHEIA_TA_API"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo $response["access_token"];
echo $response["expires_in"]; // 3600 secunde
Răspuns succes 200
{
    "access_token": "eyJhbGciOiJIUzI1NiIsIn...",
    "expires_in": 3600
}
Răspuns eroare 401
{ "error": "Unauthorized" }
Răspuns eroare 403
{ "error": "Invalid auth-key" }

Utilizarea token-ului

După obținerea token-ului, adaugă-l în header-ul Authorization la fiecare request:
Authorization: Bearer TOKEN_PRIMIT

Client

Endpoint-uri pentru informațiile contului tău și pentru gestionarea adreselor salvate, de ridicare și de livrare.

Returnează informațiile de bază ale contului tău.

fetch("https://api.shipo.ro/client", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/client");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "id": 123,
    "billing_type": "prepaid",
    "name": "Ion Popescu",
    "email": "[email protected]",
    "status": "active",
    "coord": [26.1027200000, 44.4361410000]
}
Câmpuri răspuns
CâmpTipDescriere
idintegerID-ul unic al clientului
billing_typestringTipul de facturare: prepaid sau postpaid
namestringNumele clientului
emailstringEmail-ul clientului
statusstringStatusul contului
coordarrayCoordonatele implicite [longitudine, latitudine]

Acest endpoint va fi eliminat în curând

Folosește în locul lui endpoint-urile noi client/address, descrise mai jos. GET /client/address?party=sender returnează aceleași adrese de ridicare, cu paginare, plus is_default, complete și full_address. Adresele sunt în câmpul data al răspunsului, iar sectorul vine ca număr.

Returnează lista tuturor adreselor de ridicare (sender) asociate contului tău. Folosește id-ul adresei ca sender_address_id la crearea expedierilor.

fetch("https://api.shipo.ro/client/address_list", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/client/address_list");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
[
    {
        "id": 1,
        "client_id": 123,
        "party": "sender",
        "alias": "Sediu",
        "name": "Ion Popescu",
        "company_name": "SC Exemplu SRL",
        "phone": "0712345678",
        "address_city_id": 16404,
        "address_street_id": 5001,
        "address_street_no": "10"
    }
]

Returnează paginat adresele salvate ale contului tău, cele mai noi primele: adresele de ridicare (party: "sender") și adresele de livrare (party: "recipient"). Folosește id-ul unei adrese de ridicare ca sender_address_id, iar pe cel al unei adrese de livrare ca recipient_address_id în POST /shipment, la serviciile cu ridicare sau livrare la adresă. POST /shipment este disponibil conturilor cu plată la termen (postpaid).

Query Parameters
ParametruTipObligatoriuDescriere
partystringNusender (doar adresele de ridicare) sau recipient (doar adresele de livrare). Fără el primești ambele tipuri
page_nointegerNuNumărul paginii (default 1, min 1, max 100000)
per_pageintegerNuAdrese per pagină (default 100, min 1, max 500)

Lista conține doar adresele stradale salvate în cont, aceleași ca pe pagina Adrese din contul tău. Adresele de facturare nu sunt incluse.

// Adresele de ridicare, prima pagină
fetch("https://api.shipo.ro/client/address?party=sender&page_no=1&per_page=100", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => {
    console.log("Total adrese:", data.pagination.total);
    data.data.forEach(address => console.log(address.id, address.full_address));
});

// Adresele de livrare
// /client/address?party=recipient
$query = http_build_query([
    "party"    => "sender",
    "page_no"  => 1,
    "per_page" => 100,
]);

$ch = curl_init("https://api.shipo.ro/client/address?" . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

foreach ($response["data"] as $address) {
    echo $address["id"] . " " . $address["full_address"] . PHP_EOL;
}
Răspuns succes 200
{
    "success": true,
    "pagination": {
        "page": 1,
        "per_page": 100,
        "total": 1,
        "total_pages": 1
    },
    "data": [
        {
            "id": 501,
            "party": "sender",
            "alias": "Depozit",
            "name": "Ion Popescu",
            "company_name": "SC Exemplu SRL",
            "phone": "0712345678",
            "email": "[email protected]",
            "address_city_id": 16404,
            "address_city": "BUCURESTI",
            "address_county": "BUCURESTI",
            "address_municipality": "",
            "address_sector": 6,
            "address_street_id": null,
            "address_street": "Estacadei",
            "address_street_type": "Strada",
            "address_street_no": "15",
            "address_building": "P41",
            "address_entrance": "4",
            "address_floor": "1",
            "address_apartment": "53",
            "address_postal_code": "062225",
            "address_note": "",
            "full_address": "Strada Estacadei, Nr. 15, Bl. P41, Sc. 4, Et. 1, Ap. 53, Sectorul 6, Bucuresti, Bucuresti, 062225",
            "is_default": true,
            "complete": true,
            "added_on": "2026-10-13 10:15:00",
            "modified_on": "2026-10-13 10:15:00"
        }
    ]
}
Câmpuri răspuns
CâmpTipDescriere
successbooleanDacă operația a reușit
pagination.pageintegerPagina curentă
pagination.per_pageintegerAdrese per pagină
pagination.totalintegerTotal adrese pentru filtrul ales
pagination.total_pagesintegerTotal pagini (0 dacă nu există adrese)
dataarrayAdresele, cele mai noi primele. Fiecare are câmpurile descrise la GET /client/address/{id}
Răspuns eroare validare 422
{
    "success": false,
    "message": "Validation failed",
    "errors": [
        {
            "field": "per_page",
            "code": "invalid_per_page",
            "message": "per_page must be a whole number from 1 to 500."
        }
    ]
}

Returnează o adresă salvată a contului tău, după ID. O adresă care nu există, o adresă a altui cont sau un ID care nu este un număr primesc același răspuns 404.

fetch("https://api.shipo.ro/client/address/502", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/client/address/502");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 200 sau 404
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "data": {
        "id": 502,
        "party": "recipient",
        "name": "Maria Ionescu",
        "company_name": "",
        "phone": "0723456789",
        "email": "[email protected]",
        "address_city_id": 2989,
        "address_city": "Cluj-Napoca",
        "address_county": "Cluj",
        "address_municipality": "",
        "address_sector": null,
        "address_street_id": 111689,
        "address_street": "Clabucet",
        "address_street_type": "Aleea",
        "address_street_no": "8",
        "address_building": "P1",
        "address_entrance": "2",
        "address_floor": "",
        "address_apartment": "74",
        "address_postal_code": "400537",
        "address_note": "",
        "full_address": "Aleea Clabucet, Nr. 8, Bl. P1, Sc. 2, Ap. 74, Cluj-Napoca, Cluj, 400537",
        "complete": true,
        "added_on": "2026-10-13 10:20:00",
        "modified_on": "2026-10-13 10:20:00"
    }
}
Câmpuri răspuns (data)
CâmpTipDescriere
idintegerID-ul adresei. Se trimite ca sender_address_id (ridicare) sau recipient_address_id (livrare) în POST /shipment
partystringsender (adresă de ridicare) sau recipient (adresă de livrare)
aliasstringNumele adresei în cont. Doar la adresele de ridicare
namestringPersoana de contact
company_namestringCompanie (gol la persoane fizice)
phonestringTelefon
emailstringEmail. La adresele de ridicare este emailul contului
address_city_idinteger|nullID-ul orașului
address_citystringOrașul
address_countystringJudețul
address_municipalitystringComuna sau municipiul, completat doar când deosebește localități cu același nume
address_sectorinteger|nullSectorul (1-6) la București, null în rest
address_street_idinteger|nullID-ul străzii, null când strada a fost trimisă ca text
address_streetstringNumele străzii, fără tip
address_street_typestringTipul străzii (Strada, Bulevardul, Aleea etc.)
address_street_nostringNumăr
address_buildingstringBloc
address_entrancestringScara
address_floorstringEtaj
address_apartmentstringApartament
address_postal_codestringCod poștal
address_notestringObservații adresă
full_addressstringAdresa completă pe un singur rând
is_defaultbooleanDacă este adresa de ridicare implicită a contului. Doar la adresele de ridicare
completebooleanDacă adresa are toate datele cerute de POST /shipment. O adresă cu false este refuzată ca sender_address_id sau recipient_address_id până când o completezi cu PATCH
added_onstringData creării (YYYY-MM-DD HH:MM:SS)
modified_onstringData ultimei modificări (YYYY-MM-DD HH:MM:SS)
Răspuns eroare 404
{
    "success": false,
    "message": "Address not found"
}

Salvează în cont o adresă de ridicare (party: "sender") sau de livrare (party: "recipient"). Adresa trece prin aceleași verificări ca pe pagina Adrese din contul tău și prin limitele de lungime ale curierilor, deci poate fi folosită direct în POST /shipment. Răspunsul este 201 cu adresa salvată. Nu se verifică dacă adresa există deja, deci un request repetat pentru o adresă de livrare creează o a doua adresă (la adresele de ridicare, un alias repetat este refuzat).

Body (JSON)
CâmpTipRidicare (sender)Livrare (recipient)Descriere
partystringDaDasender pentru o adresă de ridicare, recipient pentru o adresă de livrare. Nu se mai poate schimba după creare
aliasstringDaNu se acceptăNumele adresei în cont, de exemplu Depozit (max. 20 car.). Unic printre adresele de ridicare ale contului, fără diferență între litere mari și mici
namestringDaDaPersoana de contact, prenume și nume (max. 48 car.)
company_namestringNuNuCompanie (max. 35 car.). Completat înseamnă adresă de firmă, gol înseamnă persoană fizică
phoneinteger|stringDaDaTelefon valid (max. 20 car.)
emailstringIgnoratNuEmail (max. 80 car.). La adresele de ridicare se folosește mereu emailul contului, iar valoarea trimisă este ignorată
address_city_idintegerCondiționatCondiționatID-ul orașului (din /city), sau address_city. Are prioritate față de address_city
address_citystringCondiționatCondiționatOrașul ca text (max. 100 car.), dacă nu trimiți address_city_id. Se trimite împreună cu address_county
address_countystringCondiționatCondiționatJudețul. Obligatoriu alături de address_city, cu excepția Bucureștiului
address_municipalitystringNuNuComuna sau municipiul. Necesar doar când în același județ există mai multe localități cu același nume
address_sectorinteger|stringCondiționatCondiționatSectorul 1-6, ca număr (3) sau ca text ("Sectorul 3", "Sector 3"). Obligatoriu pentru București, ignorat la celelalte orașe
address_street_idintegerCondiționatCondiționatID-ul străzii returnat de căutarea de străzi /address (câmpul system_id), sau address_street. Are prioritate față de text și trebuie să fie o stradă din orașul adresei
address_streetstringCondiționatCondiționatStrada ca text, dacă nu trimiți address_street_id. Tipul și numele străzii au împreună max. 48 car.
address_street_typestringNuNuTipul străzii (Strada, Bulevardul, Calea etc.), folosit doar cu address_street. Dacă lipsește, tipul este separat automat din text ("Strada Florilor" devine tipul Strada și numele Florilor)
address_street_nointeger|stringDaDaNumărul (max. 10 car.): litere, cifre, spațiu sau cratimă, cu cel puțin o literă sau cifră
address_buildinginteger|stringNuNuBloc (max. 10 car.: litere, cifre, spațiu sau cratimă)
address_entranceinteger|stringNuNuScara (max. 5 car., aceleași caractere ca la bloc)
address_floorinteger|stringNuNuEtaj (max. 5 car., aceleași caractere ca la bloc)
address_apartmentinteger|stringNuNuApartament (max. 5 car., aceleași caractere ca la bloc)
address_postal_codeinteger|stringNuNuCod poștal, exact 6 cifre. Dacă lipsește, este completat automat după stradă și oraș
address_notestringNuNuObservații adresă (max. 40 car.)
is_defaultbooleanNuNu se acceptătrue face din adresă adresa de ridicare implicită a contului. Valori acceptate: true, false, 1, 0, "1", "0", "true", "false"

Cum se trimite adresa

Orașul: trimite fie address_city_id (din /city), fie address_city împreună cu address_county. Dacă în același județ există mai multe localități cu același nume, adaugă address_municipality sau trimite address_city_id; altfel adresa este refuzată pe address_city, ca să nu fie salvată într-o localitate greșită. Pentru București trimite doar address_city: "Bucuresti", fără județ (sunt acceptate și București și Bucharest).

Strada: trimite fie address_street_id, ID-ul returnat de căutarea de străzi /address (câmpul system_id), fie strada ca text în address_street, cu address_street_type opțional.

Sectorul: la București, address_sector este obligatoriu, ca număr de la 1 la 6 sau ca text "Sectorul N". În răspuns sectorul vine ca număr.

Codul poștal: dacă nu trimiți address_postal_code, este completat automat după stradă și oraș.

Adresele de ridicare: alias este obligatoriu și trebuie să fie unic în cont, iar emailul este mereu cel al contului. alias și is_default nu se trimit pentru adresele de livrare.

Adresa implicită: este adresa de ridicare pe care POST /shipment o folosește când request-ul nu are expeditor. Cu is_default: true adresa nouă devine implicită. Fără is_default, prima adresă de ridicare devine implicită dacă în acel moment contul nu are una.
Adresă de ridicare în București, cu strada ca text
fetch("https://api.shipo.ro/client/address", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        party: "sender",
        alias: "Depozit",
        name: "Ion Popescu",
        company_name: "SC Exemplu SRL",
        phone: "0712345678",
        address_city: "Bucuresti",
        address_sector: 6,
        address_street: "Strada Estacadei",
        address_street_no: "15",
        address_building: "P41",
        address_entrance: "4",
        address_floor: "1",
        address_apartment: "53",
        is_default: true
    })
})
.then(response => response.json().then(data => ({ status: response.status, data })))
.then(({ status, data }) => {
    if (status === 201) {
        console.log("Adresă salvată, ID:", data.data.id);
    } else {
        console.log("Erori:", data.errors);
    }
});
$ch = curl_init("https://api.shipo.ro/client/address");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "party" => "sender",
        "alias" => "Depozit",
        "name" => "Ion Popescu",
        "company_name" => "SC Exemplu SRL",
        "phone" => "0712345678",
        "address_city" => "Bucuresti",
        "address_sector" => 6,
        "address_street" => "Strada Estacadei",
        "address_street_no" => "15",
        "address_building" => "P41",
        "address_entrance" => "4",
        "address_floor" => "1",
        "address_apartment" => "53",
        "is_default" => true
    ])
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 201 la succes, 422 la erori de validare
curl_close($ch);

if ($status === 201) {
    echo $response["data"]["id"];
} else {
    print_r($response["errors"]);
}
Adresă de livrare, cu ID-uri de oraș și stradă (body)
{
    "party": "recipient",
    "name": "Maria Ionescu",
    "phone": "0723456789",
    "email": "[email protected]",
    "address_city_id": 2989,
    "address_street_id": 111689,
    "address_street_no": "8",
    "address_building": "P1",
    "address_entrance": "2",
    "address_apartment": "74"
}
Răspuns succes 201
{
    "success": true,
    "data": {
        "id": 501,
        "party": "sender",
        "alias": "Depozit",
        "name": "Ion Popescu",
        "company_name": "SC Exemplu SRL",
        "phone": "0712345678",
        "email": "[email protected]",
        "address_city_id": 16404,
        "address_city": "BUCURESTI",
        "address_county": "BUCURESTI",
        "address_municipality": "",
        "address_sector": 6,
        "address_street_id": null,
        "address_street": "Estacadei",
        "address_street_type": "Strada",
        "address_street_no": "15",
        "address_building": "P41",
        "address_entrance": "4",
        "address_floor": "1",
        "address_apartment": "53",
        "address_postal_code": "062225",
        "address_note": "",
        "full_address": "Strada Estacadei, Nr. 15, Bl. P41, Sc. 4, Et. 1, Ap. 53, Sectorul 6, Bucuresti, Bucuresti, 062225",
        "is_default": true,
        "complete": true,
        "added_on": "2026-10-13 10:15:00",
        "modified_on": "2026-10-13 10:15:00"
    }
}

Câmpurile din data sunt descrise la GET /client/address/{id}.

Răspuns eroare validare 422
{
    "success": false,
    "message": "Validation failed",
    "errors": [
        {
            "field": "phone",
            "code": "invalid_phone",
            "message": "Field 'phone' must be a valid phone number."
        },
        {
            "field": "address_sector",
            "code": "sector_required",
            "message": "address_sector (1 to 6) is required for Bucuresti."
        }
    ]
}

Toate câmpurile greșite apar în același răspuns, în errors. Fiecare eroare are câmpul (field), un cod (code) pe care îl poți folosi în integrare și un mesaj în engleză (message). Alte coduri posibile, de exemplu: required, duplicate_alias, county_required, city_not_found, city_ambiguous, street_not_in_city, invalid_street_id, street_too_long, invalid_sector, not_allowed, unknown_field. Un body care nu este un obiect JSON primește 400.

Modifică o adresă salvată, câmp cu câmp. Trimite doar câmpurile care se schimbă; cele pe care nu le trimiți își păstrează valorile. Câmpurile și limitele sunt cele de la POST /client/address, dar la modificare niciunul nu este obligatoriu. Răspunsul este 200 cu adresa după modificare.

Reguli de modificare
SituațieCe se întâmplă
Câmp netrimisÎși păstrează valoarea
Câmp trimis cu valoarea actualăNu este modificat și nici verificat din nou. Poți citi adresa cu GET, schimba un câmp și trimite tot obiectul înapoi
Câmp trimis cu null sau ""Golește un câmp opțional. Un câmp obligatoriu nu poate fi golit (422). Golirea lui company_name face din adresă una de persoană fizică
Orașul (address_city_id, address_city, address_county, address_municipality)Se trimite ca un tot: dacă schimbi oricare dintre ele, orașul este înlocuit cu ce ai trimis. Strada trebuie trimisă din nou în același request, altfel primești 422 pe address_street. Dacă noul oraș este București și nu trimiți sector, rămâne sectorul existent (iar dacă adresa nu are sector, primești 422 pe address_sector); la alte orașe sectorul se golește
Strada (address_street_id, address_street, address_street_type)Se trimite tot ca un tot: dacă schimbi oricare dintre ele, strada este înlocuită cu ce ai trimis
Codul poștalDacă se schimbă orașul sau strada și nu trimiți address_postal_code, codul poștal este recalculat
partyNu se poate schimba. Aceeași valoare este ignorată, o valoare diferită primește 422
is_defaulttrue face din adresă adresa de ridicare implicită. false anulează alegerea doar dacă adresa este cea implicită; contul rămâne atunci fără adresă implicită
Câmpuri doar pentru citire (id, full_address, complete, added_on, modified_on, address_type)Pot fi trimise înapoi așa cum le-ai primit de la GET și sunt ignorate. La adresele de ridicare, email este ignorat
Câmp necunoscutRefuzat cu 422 și codul unknown_field, ca o greșeală de scriere să nu fie ignorată fără să afli
Body gol ({})Nu schimbă nimic și returnează adresa

Sunt verificate doar câmpurile pe care le schimbi. O adresă mai veche care nu respectă regulile actuale (de exemplu un etaj mai lung de 5 caractere) poate fi modificată în continuare; câmpurile pe care nu le atingi sunt păstrate exact cum erau.

Schimbă telefonul și fă adresa implicită
fetch("https://api.shipo.ro/client/address/501", {
    method: "PATCH",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        phone: "0722111222",
        is_default: true
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/client/address/501");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PATCH",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "phone" => "0722111222",
        "is_default" => true
    ])
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 200, 404 sau 422
curl_close($ch);

print_r($response);
Mută adresa în alt oraș (orașul și strada împreună, body)
{
    "address_city": "Cluj-Napoca",
    "address_county": "Cluj",
    "address_street": "Aleea Clabucet",
    "address_street_no": "8"
}
Golește observațiile (body)
{
    "address_note": null
}
Răspuns succes 200
{
    "success": true,
    "data": {
        "id": 501,
        "party": "sender",
        "alias": "Depozit",
        "name": "Ion Popescu",
        "company_name": "SC Exemplu SRL",
        "phone": "0722111222",
        "email": "[email protected]",
        "address_city_id": 16404,
        "address_city": "BUCURESTI",
        "address_county": "BUCURESTI",
        "address_municipality": "",
        "address_sector": 6,
        "address_street_id": null,
        "address_street": "Estacadei",
        "address_street_type": "Strada",
        "address_street_no": "15",
        "address_building": "P41",
        "address_entrance": "4",
        "address_floor": "1",
        "address_apartment": "53",
        "address_postal_code": "062225",
        "address_note": "",
        "full_address": "Strada Estacadei, Nr. 15, Bl. P41, Sc. 4, Et. 1, Ap. 53, Sectorul 6, Bucuresti, Bucuresti, 062225",
        "is_default": true,
        "complete": true,
        "added_on": "2026-10-13 10:15:00",
        "modified_on": "2026-10-13 11:02:00"
    }
}
Răspuns eroare validare 422
{
    "success": false,
    "message": "Validation failed",
    "errors": [
        {
            "field": "address_street",
            "code": "street_required_with_city",
            "message": "Send the street again when the city changes."
        }
    ]
}
Răspuns eroare 404
{
    "success": false,
    "message": "Address not found"
}

Șterge o adresă salvată a contului tău. Dacă era adresa de ridicare implicită, contul rămâne fără adresă implicită și nicio altă adresă nu devine implicită în locul ei; POST /shipment fără expeditor folosește atunci prima adresă de ridicare completă. Expedierile create deja cu această adresă nu sunt afectate.

fetch("https://api.shipo.ro/client/address/502", {
    method: "DELETE",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/client/address/502");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "DELETE",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 200 sau 404
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true
}
Răspuns eroare 404
{
    "success": false,
    "message": "Address not found"
}

Adrese salvate: coduri de răspuns

Endpoint-urile /client/address lucrează cu adresele stradale salvate în cont, de ridicare și de livrare. Erorile de validare primesc codul HTTP 422, cu success: false și lista errors. Atenție: endpoint-urile mai vechi răspund la erorile de validare cu 200, deci verifică în integrare codul HTTP. O adresă inexistentă sau a altui cont primește 404 (Address not found), un body care nu este un obiect JSON primește 400, iar o metodă HTTP nepermisă primește 405, cu metodele acceptate în header-ul Allow. ID-urile adreselor se trimit în POST /shipment ca sender_address_id (adresă de ridicare) sau recipient_address_id (adresă de livrare), la serviciile cu ridicare sau livrare la adresă. POST /shipment este disponibil conturilor cu plată la termen (postpaid).

Orașe

Caută și găsește ID-ul orașului necesar pentru celelalte endpoint-uri.

Străzi

Caută străzi într-un anumit oraș. Rezultatele pot fi folosite ca sender_address_street_id sau recipient_address_street_id.

Curieri

Obține lista curierilor disponibili și serviciile lor.

Returnează lista curierilor activi împreună cu serviciile lor. Poți filtra după tipul adresei expeditorului.

Body (JSON) - opțional
ParametruTipObligatoriuDescriere
sender_address_typestringNuFiltrează: address, locker, pudo
 
fetch("https://api.shipo.ro/couriers", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        sender_address_type: "address"
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/couriers");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "sender_address_type" => "address"
    ])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
[
    {
        "id": 1,
        "name": "FAN Courier",
        "slug": "fancourier",
        "enabled": true,
        "logo": "https://shipo.ro/assets/couriers/icon-square-fancourier.jpg",
        "services": [
            {
                "id": 10,
                "courier_id": 1,
                "type": "standard",
                "sender_address_type": "address",
                "recipient_address_type": "address",
                "description": "Livrare standard la adresă"
            }
        ]
    }
]

Tarife

Calculează tarifele de expediere și obține lista serviciilor disponibile.

Returnează toate serviciile de expediere. Folosește id-ul ca rate_id la crearea expedierilor.

fetch("https://api.shipo.ro/rates/services", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/rates/services");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
[
    {
        "id": 10,
        "courier_id": 1,
        "type": "standard",
        "sender_address_type": "address",
        "recipient_address_type": "address",
        "description": "Livrare standard la adresă"
    }
]
Câmpuri răspuns
CâmpTipDescriere
idintegerID serviciu (folosește ca rate_id)
courier_idintegerID curier
typestringTipul serviciului
sender_address_typestringaddress, locker, pudo
recipient_address_typestringaddress, locker, pudo
descriptionstringDescrierea serviciului

Calculează tarifele de expediere în funcție de rută și colete.

Body (JSON)
ParametruTipObligatoriuDescriere
sender_cityintegerDaID adresă ridicare (din GET /client/address?party=sender)
delivery_citystringDaOrașul de livrare
codfloatNuValoare ramburs (0 dacă nu se aplică)
parcelsarrayNuLista coletelor. Implicit: 1 colet 30x20x10cm, 1kg
courierarrayNuFiltrare după slug curier (ex: ["fancourier"])
sender_typestringNuFiltrare: address sau locker
Structura colet (parcels[])
CâmpTipDescriere
lengthintegerLungime cm (implicit: 30)
widthintegerLățime cm (implicit: 20)
heightintegerÎnălțime cm (implicit: 10)
weightintegerGreutate kg (implicit: 1)
 
fetch("https://api.shipo.ro/rates", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        sender_city: 1,
        delivery_city: "Cluj-Napoca",
        cod: 150.00,
        parcels: [
            { length: 30, width: 20, height: 15, weight: 2 }
        ]
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/rates");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "sender_city" => 1,
        "delivery_city" => "Cluj-Napoca",
        "cod" => 150.00,
        "parcels" => [
            ["length" => 30, "width" => 20, "height" => 15, "weight" => 2]
        ]
    ])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "1": {
        "rate_id": 1,
        "courier_slug": "fancourier",
        "courier_name": "FAN Courier",
        "service_type": "standard",
        "total_fee": 15.50,
        "is_cod_available": true
    },
    "15": {
        "rate_id": 15,
        "courier_slug": "dpd",
        "courier_name": "DPD",
        "service_type": "standard",
        "total_fee": 14.80,
        "is_cod_available": true
    }
}
Răspuns eroare 200
{
    "success": false,
    "message": "No couriers deliver this shipment"
}

Lockere & PUDO

Obține lista punctelor de ridicare (lockere sau puncte PUDO) valabile pentru un tarif. Folosește id-ul punctului ca recipient_address_id (livrare în locker) sau sender_address_id (ridicare din locker) la crearea expedierii.

Atenție: două tipuri diferite de ID

Pentru serviciile address, câmpurile sender_address_id / recipient_address_id primesc ID-ul unei adrese salvate. Pentru serviciile locker sau pudo, aceleași câmpuri primesc ID-ul punctului returnat de /points. Nu sunt interschimbabile.

Returnează punctele valabile pentru tariful trimis. Curierul și tipul punctului (locker sau PUDO) sunt deduse automat din rate_id, deci lista conține doar puncte acceptate de acel serviciu.

Query string
ParametruTipObligatoriuDescriere
rate_idintegerDaID-ul tarifului (din /rates). Determină curierul și tipul punctului
partystringCondiționatsender sau recipient. Necesar doar dacă tariful folosește tipuri diferite de puncte pe cele două capete
citystringNuFiltrare după localitate. Caută fragmente, nu potrivire exactă (Ocna returnează și Ocna Mureș, și Târgu Ocna)
countystringNuFiltrare după județ, tot pe fragment
termstringNuCăutare liberă, pe fragment, în numele punctului, stradă și localitate
coordstringNuCăutare după coordonate, format latitudine,longitudine (ex: 46.7712,23.6236). Rezultatele sunt ordonate crescător după distanță și fiecare punct primește distance_km
radiusfloatNuRaza de căutare în km, folosită împreună cu coord. Implicit 10, minim 0.1, maxim 200. Valorile în afara intervalului sunt aduse la limită, deci radius=0 înseamnă 100 m, nu „fără limită”
max_resultsintegerNuLimitează numărul de puncte returnate. Se aplică după sortare, deci cu coord primești cele mai apropiate N puncte. Implicit toate; minim 1

Diferențe între curieri

Datele punctelor vin de la fiecare curier în parte, așa că unele câmpuri pot fi goale: Poșta Română și Sameday nu trimit numărul stradal separat (la Poșta Română street conține adresa completă), accepted_payment lipsește la FAN Courier și Poșta Română, iar opening_hours este completat doar la punctele PUDO DPD și Poșta Română. Fă integrarea tolerantă la câmpuri goale — garantate pentru toți curierii sunt id, name, city, county, postal_code, address, lat și lng.
// Cele mai apropiate 5 lockere de un set de coordonate
fetch("https://api.shipo.ro/points?rate_id=42&coord=46.7712,23.6236&radius=15&max_results=5", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));

// Sau toate lockerele dintr-o localitate
// /points?rate_id=42&city=Cluj-Napoca
$query = http_build_query([
    "rate_id"     => 42,
    "coord"       => "46.7712,23.6236",
    "radius"      => 15,
    "max_results" => 5,
]);

$ch = curl_init("https://api.shipo.ro/points?" . $query);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "courier": "sameday",
    "type": "locker",
    "total": 37,
    "returned": 2,
    "data": [
        {
            "id": 1234,
            "name": "easybox OMV Belu",
            "county": "Bucuresti",
            "city": "Sectorul 4",
            "street": "Sos. Oltenitei, Nr. 2",
            "street_no": "",
            "postal_code": "041304",
            "address": "Sos. Oltenitei, Nr. 2, Sectorul 4, Bucuresti",
            "lat": 44.3931,
            "lng": 26.1174,
            "opening_hours": "",
            "accepted_payment": "Card",
            "dropoff_allowed": 1,
            "distance_km": 1.24
        }
    ]
}
CâmpDescriere
courierSlug-ul curierului dedus din rate_id
typelocker sau pudo, dedus tot din tarif
totalCâte puncte au corespuns filtrelor, înainte de max_results
returnedCâte puncte sunt efectiv în data, după max_results
data[].idValoarea care se trimite ca recipient_address_id sau sender_address_id. Poate fi numar sau text, in functie de curier (GLS foloseste un cod de forma 021173-PARCELLOCK), deci trimite-l mai departe exact asa cum l-ai primit, fara sa-l convertesti in numar
data[].dropoff_allowed1 daca punctul accepta predarea unui colet. Un punct cu 0 poate fi folosit doar ca destinatie, nu ca sender_address_id
data[].distance_kmApare doar când folosești coord. Este 0 pentru un punct aflat exact la coordonatele cerute
Răspuns eroare 400
{
    "success": false,
    "message": "Filtering by county is not available for this courier"
}

Alte mesaje posibile: Missing rate_id, Rate not found or inactive, This rate delivers to an address, so it does not use lockers or pudo points, This rate uses a different point type for sender and recipient. Add party=sender or party=recipient, Invalid coord. Expected "latitude,longitude"….

Expedieri

Creează, validează, trimite și anulează expedieri.

Returnează lista paginată a expedierilor contului autentificat. Maxim 500 expedieri per pagină.

Query Parameters
ParametruTipObligatoriuDescriere
page_nointegerNuNumărul paginii (default 1, min 1, max 100000)
per_pageintegerNuExpedieri per pagină (default 100, min 1, max 500)
status_orderstringNuFiltru pe status comandă: completed, paid, finalized, canceled, refunded
status_deliverystringNuFiltru pe status livrare: order_placed, collected, in_transit, out_for_delivery, delivered, canceled, dropoff_locker, dropoff_pudo, loaded_locker, loaded_pudo, return_to_sender
awbstringNuFiltru pe AWB exact (max 20 caractere alfanumerice)
fromstringNuData minimă placed_on (format YYYY-MM-DD)
tostringNuData maximă placed_on (format YYYY-MM-DD)
Exemplu cu paginare și filtre
fetch("https://api.shipo.ro/shipments?page_no=1&per_page=100&status_delivery=delivered&from=2026-01-01&to=2026-04-29", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipments?page_no=1&per_page=100&status_delivery=delivered&from=2026-01-01&to=2026-04-29");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "pagination": {
        "page": 1,
        "per_page": 100,
        "total": 237,
        "total_pages": 3
    },
    "data": [
        {
            "id": 12345,
            "awb": "2150012345678",
            "order_id": "PICKUP-9876",
            "courier": "fancourier",
            "courier_name": "FAN Courier",
            "status_order": "paid",
            "status_delivery": "delivered",
            "is_return": false,
            "cost": 19.99,
            "cod": 250.00,
            "weight": 3,
            "weight_initial": 3,
            "parcel_count": 2,
            "IBAN": "RO12BREL0005123456789012",
            "account_holder": "SC Exemplu SRL",
            "open_on_delivery": true,
            "insurance": true,
            "declared_value": 500,
            "is_recalculated": false,
            "is_reweighed": false,
            "is_atypical": false,
            "is_bnpl": false,
            "is_oversized": false,
            "is_redirected": false,
            "is_quick_cod": false,
            "contents": "Electronice",
            "note": "Fragil",
            "placed_on": "2026-04-15 12:34:56",
            "added_on": "2026-04-15 12:30:00",
            "label_a4": "https://shipo.ro/downloader/awb/label_a4_12345.pdf",
            "label_a6": "https://shipo.ro/downloader/awb/label_a6_12345.pdf",
            "sender": {
                "name": "Ion Popescu",
                "company_name": "SC Exemplu SRL",
                "email": "[email protected]",
                "phone": "0712345678",
                "address": "Strada Exemplu nr. 10, Bucuresti",
                "address_type": "address",
                "address_country": "Romania",
                "address_county": "Bucuresti",
                "address_municipality": "Bucuresti",
                "address_city": "Bucuresti",
                "address_sector": "1",
                "address_street": "Strada Exemplu",
                "address_street_type": "Strada",
                "address_street_no": "10",
                "address_building": "",
                "address_entrance": "",
                "address_floor": "",
                "address_apartment": "",
                "address_postal_code": "010101",
                "address_intercom": "",
                "address_note": ""
            },
            "recipient": {
                "name": "Maria Ionescu",
                "company_name": "",
                "email": "[email protected]",
                "phone": "0723456789",
                "address": "Strada Florilor nr. 25, Cluj-Napoca",
                "address_type": "address",
                "address_country": "Romania",
                "address_county": "Cluj",
                "address_municipality": "Cluj-Napoca",
                "address_city": "Cluj-Napoca",
                "address_sector": "",
                "address_street": "Strada Florilor",
                "address_street_type": "Strada",
                "address_street_no": "25",
                "address_building": "",
                "address_entrance": "",
                "address_floor": "",
                "address_apartment": "",
                "address_postal_code": "400123",
                "address_intercom": "",
                "address_note": ""
            },
            "parcels": [
                { "weight": 3, "initial_weight": 3, "length": 40, "width": 30, "height": 20 },
                { "weight": 1, "initial_weight": 1, "length": 20, "width": 15, "height": 10 }
            ]
        }
    ]
}
Răspuns succes — expediere retur (campuri suplimentare cand is_return = true)
{
    "id": 12346,
    "is_return": true,
    "pending_approval": false,
    "return_reason": "Produs deteriorat",
    "return_IBAN": "RO12BREL0005987654321098",
    "return_account_holder": "Andrei Popa"
}
Câmpuri răspuns
CâmpTipDescriere
Răspuns top-level
successbooleanDacă operația a reușit
pagination.pageintegerPagina curentă
pagination.per_pageintegerExpedieri per pagină
pagination.totalintegerTotal expedieri pentru filtrele selectate
pagination.total_pagesintegerTotal pagini disponibile
dataarrayLista expedierilor (sortate după placed_on descrescător)
Identificatori
data[].idintegerID expediție Shipo
data[].awbstringNumărul AWB (gol dacă nu s-a generat încă)
data[].order_idstringID-ul ridicării (pickup ID-ul atribuit de curier)
data[].courierstringSlug curier (ex: fancourier, cargus, dpd)
data[].courier_namestringNume curier
Statusuri
data[].status_orderstringStatus comandă (completed, paid, finalized, canceled, refunded)
data[].status_deliverystringStatus livrare (order_placed, collected, in_transit, out_for_delivery, delivered, canceled, dropoff_locker, dropoff_pudo, loaded_locker, loaded_pudo, return_to_sender)
Date generale
data[].is_returnbooleanDacă expedierea este retur
data[].costfloatCost total expediere (RON)
data[].codfloatValoare ramburs (RON)
data[].weightfloatGreutate totală curentă (kg)
data[].weight_initialfloatGreutate totală inițială (kg)
data[].parcel_countintegerNumăr colete
data[].IBANstringIBAN pentru ramburs (gol dacă nu este COD)
data[].account_holderstringTitular cont IBAN
data[].declared_valuefloatValoare declarată (RON)
data[].contentsstringConținut colet
data[].notestringObservații
data[].placed_onstringData plasare AWB (YYYY-MM-DD HH:MM:SS)
data[].added_onstringData creare în sistem
data[].label_a4string|nullURL etichetă A4
data[].label_a6string|nullURL etichetă A6
Servicii extra (boolean)
data[].open_on_deliverybooleanDeschidere la livrare
data[].insurancebooleanAsigurare colet
Flag-uri stare (boolean)
data[].is_recalculatedbooleanExpedierea a fost recalculată
data[].is_reweighedbooleanRecalcularea a inclus o re-cântărire
data[].is_atypicalbooleanColet atipic
data[].is_bnplbooleanPlată după livrare (Buy Now Pay Later)
data[].is_oversizedbooleanColet supradimensionat
data[].is_redirectedbooleanExpediție redirecționată
data[].is_quick_codbooleanRamburs rapid
Date expeditor (data[].sender)
sender.namestringNume complet
sender.company_namestringCompanie
sender.emailstringEmail
sender.phonestringTelefon
sender.addressstringAdresă concatenată
sender.address_typestringTip adresă: address, locker, pudo
sender.address_countrystringȚară
sender.address_countystringJudeț
sender.address_municipalitystringMunicipiu / oraș principal
sender.address_citystringLocalitate
sender.address_sectorstringSector (1-6, doar București)
sender.address_streetstringStradă
sender.address_street_typestringTip stradă (Strada, Bulevard, etc.)
sender.address_street_nostringNumăr stradă
sender.address_buildingstringBloc
sender.address_entrancestringScara
sender.address_floorstringEtaj
sender.address_apartmentstringApartament
sender.address_postal_codestringCod poștal
sender.address_intercomstringInterfon
sender.address_notestringObservații adresă
Date destinatar (data[].recipient)
Aceleași câmpuri ca sender, prefixate recipient.
Colete (data[].parcels)
parcels[].weightfloatGreutate curentă (kg)
parcels[].initial_weightfloatGreutate inițială (kg)
parcels[].lengthfloatLungime (cm)
parcels[].widthfloatLățime (cm)
parcels[].heightfloatÎnălțime (cm)
Câmpuri retur (doar dacă is_return = true)
data[].pending_approvalbooleanReturul este în așteptare aprobare
data[].return_reasonstringMotivul returului
data[].return_IBANstringIBAN-ul clientului care a inițiat returul
data[].return_account_holderstringTitular cont IBAN client retur
Răspuns eroare validare 200
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "per_page": ["Câmpul per_page nu poate fi mai mare decât 500."]
    }
}

Creează o nouă expediere. Răspunsul conține AWB-ul și link-urile pentru etichete.

Body (JSON)
ParametruTipObligatoriuDescriere
Informații generale
rate_idintegerDaID serviciu curierat (din /rates/services)
contentsstringDaConținut colet (max. 40 car., alfanumeric)
notestringNuObservații (max. 40 car.)
parcelsarrayDaLista coletelor (length, width, height, weight)
Servicii extra
codfloatNuValoare ramburs. Contul tău trebuie să aibă IBAN și Titular cont completate în setări
insurancebooleanNuAsigurare colet
declared_valuefloatCondiționatObligatoriu dacă insurance=true. Între 1 și 5000
open_on_deliverybooleanNuDeschidere la livrare
notify_recipientbooleanNuNotificare destinatar prin SMS la generarea AWB-ului
quick_codbooleanNuRamburs rapid (Turbo). Se aplică doar dacă expedierea are cod > 0
Adresa expeditor
sender_address_idinteger|stringCondiționatPentru servicii cu ridicare de la adresă: ID adresă salvată (din GET /client/address?party=sender) — opțional, dar dacă e specificat, câmpurile de adresă nu mai sunt necesare. Pentru servicii cu ridicare din locker/pudo: obligatoriu, ID-ul punctului din /points. Se trimit în plus și câmpurile de adresă ale expeditorului (oraș, stradă, număr), deoarece coletul nelivrat se returnează la această adresă
sender_company_namestringNuCompanie expeditor (max. 35 car.)
sender_namestringCondiționatNume complet (max. 48 car.)
sender_phoneinteger|stringCondiționatTelefon (max. 48 car.)
sender_address_citystringCondiționatOraș expeditor (sau sender_address_city_id). Se trimite împreună cu sender_address_county
sender_address_countystringCondiționatJudeț expeditor. Obligatoriu alături de sender_address_city, cu excepția Bucureștiului
sender_address_municipalitystringNuComună expeditor. Necesară doar pentru localitățile cu același nume în același județ (altfel se ia prima potrivire)
sender_address_city_idintegerCondiționatID oraș expeditor (sau sender_address_city)
sender_address_sectorintegerCondiționatSector 1-6. Obligatoriu pt București
sender_address_streetstringCondiționatStradă text liber (max. 48 car.), sau sender_address_street_id
sender_address_street_idintegerCondiționatID stradă (sau sender_address_street)
sender_address_street_nointeger|stringCondiționatNr. stradă (max. 10 car.). Obligatoriu dacă nu se folosește o adresă salvată prin sender_address_id, inclusiv la ridicarea din locker/pudo
sender_address_buildinginteger|stringNuBloc (max. 10 car.)
sender_address_entranceinteger|stringNuScara (max. 10 car.)
sender_address_floorinteger|stringNuEtaj (max. 10 car.)
sender_address_apartmentinteger|stringNuApartament (max. 10 car.)
sender_address_postal_codeinteger|stringNuCod poștal (exact 6 cifre)
Adresa destinatar
recipient_address_idinteger|stringCondiționatPentru servicii cu livrare la adresă: ID adresă salvată a destinatarului (din GET /client/address?party=recipient). Pentru servicii cu livrare în locker/pudo: obligatoriu, ID-ul punctului din /points
recipient_company_namestringNuCompanie destinatar (max. 35 car.)
recipient_namestringDaNume complet (max. 48 car.)
recipient_phoneinteger|stringDaTelefon (max. 48 car.)
recipient_emailstringCondiționatEmail (max. 80 car.). Obligatoriu pt locker/pudo și pentru FAN Courier (cu excepția unei adrese salvate)
recipient_address_citystringCondiționatOraș destinatar (sau recipient_address_city_id). Se trimite împreună cu recipient_address_county
recipient_address_countystringCondiționatJudeț destinatar. Obligatoriu alături de recipient_address_city, cu excepția Bucureștiului
recipient_address_municipalitystringNuComună destinatar. Necesară doar pentru localitățile cu același nume în același județ (altfel se ia prima potrivire)
recipient_address_city_idintegerCondiționatID oraș (sau recipient_address_city)
recipient_address_sectorintegerCondiționatSector 1-6. Obligatoriu pt București
recipient_address_streetstringCondiționatStradă text liber (max. 48 car.), sau recipient_address_street_id
recipient_address_street_idintegerCondiționatID stradă (sau recipient_address_street)
recipient_address_street_nointeger|stringCondiționatNr. stradă (max. 10 car.). Obligatoriu dacă nu se folosește recipient_address_id
recipient_address_buildinginteger|stringNuBloc (max. 10 car.)
recipient_address_entranceinteger|stringNuScara (max. 10 car.)
recipient_address_floorinteger|stringNuEtaj (max. 10 car.)
recipient_address_apartmentinteger|stringNuApartament (max. 10 car.)
recipient_address_postal_codeinteger|stringNuCod poștal (exact 6 cifre)
Metadate
metaobjectNuInfo suplimentare (os_type, os_version, utm_url)

Notă despre adrese

Dacă folosești sender_address_id (din GET /client/address?party=sender), câmpurile individuale de adresă nu mai sunt necesare. Pentru serviciile care livrează în locker sau punct PUDO, trimite recipient_address_id cu ID-ul punctului obținut din /points — în acest caz sunt necesare numele, telefonul și emailul destinatarului (emailul este obligatoriu pentru locker/pudo, pentru că acolo se trimite codul de ridicare), fără câmpuri de adresă. Simetric, pentru serviciile care ridică din locker/pudo, trimite sender_address_id cu ID-ul punctului din /points.

Adresa de retur la predarea în locker/pudo: la toate serviciile cu ridicare din locker/pudo, adresa expeditorului rămâne obligatorie. Trimite atât sender_address_id cu ID-ul punctului, cât și câmpurile de localitate și stradă ale expeditorului. Coletul care nu poate fi livrat se returnează la această adresă (la Sameday, după ce nu este ridicat din easybox-ul în care a fost predat).

Sursa ID-urilor de adresă salvată: adresele de ridicare vin din GET /client/address?party=sender, iar ID-urile lor se trimit ca sender_address_id. Adresele de livrare salvate sunt disponibile prin GET /client/address?party=recipient, iar ID-urile lor se trimit ca recipient_address_id la serviciile address. Adrese noi, de ridicare sau de livrare, se creează cu POST /client/address. ID-ul unei adrese de ridicare nu este acceptat ca recipient_address_id și nici invers. Fără o adresă salvată, trimite câmpurile de adresă individual.

Localitatea și strada: se trimit fie ca text (sender_address_city + sender_address_county și sender_address_street), fie ca ID-uri (sender_address_city_id, sender_address_street_id), la fel pentru destinatar. Dacă în același județ există mai multe localități cu același nume, adaugă sender_address_municipality (respectiv recipient_address_municipality) sau folosește ID-ul, altfel se ia prima potrivire. Pentru București se trimite doar sender_address_city: "Bucuresti", fără județ, împreună cu sender_address_sector.

Denumiri vechi: oras_plecare, strada_plecare, oras_sosire și strada_sosire rămân acceptate pentru integrările existente și au prioritate dacă sunt trimise împreună cu noile denumiri. Ele așteaptă localitatea într-un singur câmp, în formatul "Oraș, Județ".
Exemplu minimal (cu adresă salvată)
fetch("https://api.shipo.ro/shipment", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        rate_id: 10,
        contents: "Haine",
        sender_address_id: 1,
        recipient_name: "Maria Ionescu",
        recipient_phone: "0723456789",
        recipient_address_city: "Cluj-Napoca",
        recipient_address_county: "Cluj",
        recipient_address_street: "Strada Memorandumului",
        // variantă secundară: recipient_address_street_id: 3001 (ID stradă din /address)
        recipient_address_street_no: "15",
        parcels: [
            { length: 30, width: 20, height: 10, weight: 1 }
        ]
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipment");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "rate_id" => 10,
        "contents" => "Haine",
        "sender_address_id" => 1,
        "recipient_name" => "Maria Ionescu",
        "recipient_phone" => "0723456789",
        "recipient_address_city" => "Cluj-Napoca",
        "recipient_address_county" => "Cluj",
        "recipient_address_street" => "Strada Memorandumului",
        // variantă secundară: "recipient_address_street_id" => 3001 (ID stradă din /address)
        "recipient_address_street_no" => "15",
        "parcels" => [
            ["length" => 30, "width" => 20, "height" => 10, "weight" => 1]
        ]
    ])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Exemplu adresă → locker

Alege un tarif cu recipient_address_type: "locker" din /rates, ia ID-ul punctului din /points?rate_id=42 și trimite-l ca recipient_address_id. Nu se trimit câmpuri de adresă pentru destinatar, dar emailul este obligatoriu.

fetch("https://api.shipo.ro/shipment", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        rate_id: 42,
        contents: "Haine",
        sender_address_id: 7,
        recipient_address_id: 1234,
        recipient_name: "Maria Ionescu",
        recipient_phone: "0723456789",
        recipient_email: "[email protected]",
        parcels: [
            { length: 30, width: 20, height: 10, weight: 2 }
        ]
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipment");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "rate_id" => 42,
        "contents" => "Haine",
        "sender_address_id" => 7,
        "recipient_address_id" => 1234,
        "recipient_name" => "Maria Ionescu",
        "recipient_phone" => "0723456789",
        "recipient_email" => "[email protected]",
        "parcels" => [
            ["length" => 30, "width" => 20, "height" => 10, "weight" => 2]
        ]
    ])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Exemplu complet (cu ramburs și adrese manuale)
fetch("https://api.shipo.ro/shipment", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        rate_id: 10,
        contents: "Electronice",
        note: "Fragil",
        cod: 250.00,
        insurance: true,
        declared_value: 500,
        open_on_delivery: true,
        notify_recipient: true,
        quick_cod: true,
        sender_name: "Ion Popescu",
        sender_phone: "0712345678",
        sender_company_name: "SC Exemplu SRL",
        sender_address_city: "Bucuresti",
        sender_address_sector: 1,
        sender_address_street: "Strada Aviatorilor",
        sender_address_street_no: "10",
        recipient_name: "Maria Ionescu",
        recipient_phone: "0723456789",
        recipient_email: "[email protected]",
        recipient_address_city: "Cluj-Napoca",
        recipient_address_county: "Cluj",
        recipient_address_street: "Strada Memorandumului",
        // variantă secundară: recipient_address_street_id: 3001 (ID stradă din /address)
        recipient_address_street_no: "25",
        parcels: [
            { length: 40, width: 30, height: 20, weight: 3 },
            { length: 20, width: 15, height: 10, weight: 1 }
        ]
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipment");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "rate_id" => 10,
        "contents" => "Electronice",
        "note" => "Fragil",
        "cod" => 250.00,
        "insurance" => true,
        "declared_value" => 500,
        "open_on_delivery" => true,
        "notify_recipient" => true,
        "quick_cod" => true,
        "sender_name" => "Ion Popescu",
        "sender_phone" => "0712345678",
        "sender_company_name" => "SC Exemplu SRL",
        "sender_address_city" => "Bucuresti",
        "sender_address_sector" => 1,
        "sender_address_street" => "Strada Aviatorilor",
        "sender_address_street_no" => "10",
        "recipient_name" => "Maria Ionescu",
        "recipient_phone" => "0723456789",
        "recipient_email" => "[email protected]",
        "recipient_address_city" => "Cluj-Napoca",
        "recipient_address_county" => "Cluj",
        "recipient_address_street" => "Strada Memorandumului",
        // variantă secundară: "recipient_address_street_id" => 3001 (ID stradă din /address)
        "recipient_address_street_no" => "25",
        "parcels" => [
            ["length" => 40, "width" => 30, "height" => 20, "weight" => 3],
            ["length" => 20, "width" => 15, "height" => 10, "weight" => 1]
        ]
    ])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "expedition": 12345,
    "awb": "2150012345678",
    "label_a4": "https://shipo.ro/downloader/awb/label_a4_12345.pdf",
    "label_a6": "https://shipo.ro/downloader/awb/label_a6_12345.pdf",
    "message": "Shipment created successfully."
}
Câmpuri răspuns
CâmpTipDescriere
successbooleanDacă operația a reușit
expeditionintegerID expediție
awbstringNumărul AWB
label_a4stringURL etichetă A4
label_a6stringURL etichetă A6
Răspuns eroare validare 200
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "rate_id": ["Câmpul rate_id este obligatoriu."],
        "contents": ["Câmpul contents este obligatoriu."]
    }
}

Validează datele fără a crea expedierea. Aceiași parametri ca POST /shipment.

fetch("https://api.shipo.ro/shipment/validate", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN",
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        rate_id: 10,
        contents: "Haine",
        sender_address_id: 1,
        recipient_name: "Maria Ionescu",
        recipient_phone: "0723456789",
        recipient_address_city: "Cluj-Napoca",
        recipient_address_county: "Cluj",
        recipient_address_street: "Strada Memorandumului",
        // variantă secundară: recipient_address_street_id: 3001 (ID stradă din /address)
        recipient_address_street_no: "15",
        parcels: [{ length: 30, width: 20, height: 10, weight: 1 }]
    })
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipment/validate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "rate_id" => 10,
        "contents" => "Haine",
        "sender_address_id" => 1,
        "recipient_name" => "Maria Ionescu",
        "recipient_phone" => "0723456789",
        "recipient_address_city" => "Cluj-Napoca",
        "recipient_address_county" => "Cluj",
        "recipient_address_street" => "Strada Memorandumului",
        // variantă secundară: "recipient_address_street_id" => 3001 (ID stradă din /address)
        "recipient_address_street_no" => "15",
        "parcels" => [["length" => 30, "width" => 20, "height" => 10, "weight" => 1]]
    ])
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{ "success": true, "message": "Validation passed" }
Răspuns eroare 200
{
    "success": false,
    "message": "Validation failed",
    "errors": { "recipient_name": ["Câmpul recipient_name este obligatoriu."] }
}

Trimite o expediere existentă către curier.

URL Parameters
ParametruTipObligatoriuDescriere
idintegerDaID expediție (din răspunsul de creare)
 
fetch("https://api.shipo.ro/shipment/send/12345", {
    method: "POST",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipment/send/12345");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "ec": "1",
    "expedition": 12345,
    "awb": "2150012345678",
    "label_a4": "https://shipo.ro/downloader/awb/label_a4_12345.pdf",
    "label_a6": "https://shipo.ro/downloader/awb/label_a6_12345.pdf",
    "message": "Shipment sent to courier successfully."
}
Răspuns eroare 200
{
    "success": false,
    "ec": "1",
    "expedition": 12345,
    "message": "Shipment could not be sent to courier."
}

Anulează o expediere existentă folosind numărul AWB.

URL Parameters
ParametruTipObligatoriuDescriere
awbstringDaNumărul AWB (2-100 caractere)
 
fetch("https://api.shipo.ro/shipment/cancel/2150012345678", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/shipment/cancel/2150012345678");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{ "success": true, "message": "Shipment canceled successfully." }
Răspuns eroare 200
{ "success": false, "message": "Shipment could not be canceled." }
Expediere negăsită 200
{ "success": false, "message": "Shipment not found." }

Retururi

Endpoint dedicat clienților care au magazine online asociate. Returnează retururile expediate către magazinele tale, inclusiv pe cele plătite de clientul care a inițiat returul (acelea nu apar în /shipments pentru că nu sunt asociate contului tău).

Important: Răspunsul conține mai puține câmpuri decât /shipments. Date sensibile precum IBAN-ul, costul expedierii, valoarea rambursului și flag-urile de stare sunt omise, deoarece returul poate aparține altui client.

Returnează lista paginată a retururilor expediate către magazinele online asociate contului autentificat. Maxim 500 retururi per pagină. Sortate descrescător după placed_on.

Query Parameters
ParametruTipObligatoriuDescriere
page_nointegerNuNumărul paginii (default 1, min 1, max 100000)
per_pageintegerNuRetururi per pagină (default 100, min 1, max 500)
status_orderstringNuFiltru pe status comandă: completed, paid, finalized, canceled, refunded
status_deliverystringNuFiltru pe status livrare: order_placed, collected, in_transit, out_for_delivery, delivered, canceled, dropoff_locker, dropoff_pudo, loaded_locker, loaded_pudo, return_to_sender
awbstringNuFiltru pe AWB exact (max 20 caractere alfanumerice)
fromstringNuData minimă placed_on (format YYYY-MM-DD)
tostringNuData maximă placed_on (format YYYY-MM-DD)
pending_approvalbooleanNuFiltrează după starea de aprobare: 1 sau true pentru retururi în așteptare aprobare, 0 sau false pentru cele deja procesate
Exemplu cu paginare și filtre
fetch("https://api.shipo.ro/store-returns?page_no=1&per_page=100&pending_approval=1", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/store-returns?page_no=1&per_page=100&pending_approval=1");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "pagination": {
        "page": 1,
        "per_page": 100,
        "total": 18,
        "total_pages": 1
    },
    "data": [
        {
            "id": 12345,
            "awb": "2150012345678",
            "order_id": "PICKUP-9876",
            "courier": "fancourier",
            "courier_name": "FAN Courier",
            "status_order": "paid",
            "status_delivery": "delivered",
            "is_return": true,
            "belongs_to_store": false,
            "pending_approval": false,
            "return_reason": "Produs deteriorat",
            "weight": 3,
            "parcel_count": 2,
            "contents": "Electronice",
            "note": "Fragil",
            "placed_on": "2026-04-15 12:34:56",
            "added_on": "2026-04-15 12:30:00",
            "sender": {
                "name": "Maria Ionescu",
                "company_name": "",
                "email": "[email protected]",
                "phone": "0723456789",
                "address": "Strada Florilor nr. 25, Cluj-Napoca",
                "address_type": "address",
                "address_country": "Romania",
                "address_county": "Cluj",
                "address_municipality": "Cluj-Napoca",
                "address_city": "Cluj-Napoca",
                "address_sector": "",
                "address_street": "Strada Florilor",
                "address_street_type": "Strada",
                "address_street_no": "25",
                "address_building": "",
                "address_entrance": "",
                "address_floor": "",
                "address_apartment": "",
                "address_postal_code": "400123",
                "address_intercom": "",
                "address_note": ""
            },
            "recipient": {
                "name": "Ion Popescu",
                "company_name": "SC Exemplu SRL",
                "email": "[email protected]",
                "phone": "0712345678",
                "address": "Strada Exemplu nr. 10, Bucuresti",
                "address_type": "address",
                "address_country": "Romania",
                "address_county": "Bucuresti",
                "address_municipality": "Bucuresti",
                "address_city": "Bucuresti",
                "address_sector": "1",
                "address_street": "Strada Exemplu",
                "address_street_type": "Strada",
                "address_street_no": "10",
                "address_building": "",
                "address_entrance": "",
                "address_floor": "",
                "address_apartment": "",
                "address_postal_code": "010101",
                "address_intercom": "",
                "address_note": ""
            },
            "parcels": [
                { "weight": 3, "initial_weight": 3, "length": 40, "width": 30, "height": 20 },
                { "weight": 1, "initial_weight": 1, "length": 20, "width": 15, "height": 10 }
            ]
        }
    ]
}
Câmpuri răspuns
CâmpTipDescriere
Răspuns top-level
successbooleanDacă operația a reușit
pagination.pageintegerPagina curentă
pagination.per_pageintegerRetururi per pagină
pagination.totalintegerTotal retururi pentru filtrele selectate
pagination.total_pagesintegerTotal pagini disponibile
dataarrayLista retururilor (sortate după placed_on descrescător)
Identificatori
data[].idintegerID expediție Shipo
data[].awbstringNumărul AWB (gol dacă nu s-a generat încă, ex: retur în așteptare aprobare)
data[].order_idstringID-ul ridicării (pickup ID-ul atribuit de curier)
data[].courierstringSlug curier (ex: fancourier, cargus, dpd)
data[].courier_namestringNume curier
Statusuri
data[].status_orderstringStatus comandă (completed, paid, finalized, canceled, refunded)
data[].status_deliverystringStatus livrare (order_placed, collected, in_transit, out_for_delivery, delivered, canceled, dropoff_locker, dropoff_pudo, loaded_locker, loaded_pudo, return_to_sender)
Date retur
data[].is_returnbooleanÎntotdeauna true pe acest endpoint
data[].belongs_to_storebooleantrue dacă returul este în contul tău (magazinul a plătit prin fluxul de aprobare, deci apare și în /shipments). false dacă returul este în contul altui client (clientul care a inițiat returul a plătit, deci nu apare în /shipments)
data[].pending_approvalbooleanReturul este în așteptare aprobare
data[].return_reasonstringMotivul returului
Date generale
data[].weightfloatGreutate totală (kg)
data[].parcel_countintegerNumăr colete
data[].contentsstringConținut colet
data[].notestringObservații
data[].placed_onstringData plasare retur (YYYY-MM-DD HH:MM:SS)
data[].added_onstringData creare în sistem
Date expeditor (data[].sender) — clientul care returnează
sender.namestringNume complet
sender.company_namestringCompanie
sender.emailstringEmail
sender.phonestringTelefon
sender.addressstringAdresă concatenată
sender.address_typestringTip adresă: address, locker, pudo
sender.address_countrystringȚară
sender.address_countystringJudeț
sender.address_municipalitystringMunicipiu / oraș principal
sender.address_citystringLocalitate
sender.address_sectorstringSector (1-6, doar București)
sender.address_streetstringStradă
sender.address_street_typestringTip stradă (Strada, Bulevard, etc.)
sender.address_street_nostringNumăr stradă
sender.address_buildingstringBloc
sender.address_entrancestringScara
sender.address_floorstringEtaj
sender.address_apartmentstringApartament
sender.address_postal_codestringCod poștal
sender.address_intercomstringInterfon
sender.address_notestringObservații adresă
Date destinatar (data[].recipient) — magazinul tău
Aceleași câmpuri ca sender, prefixate recipient.
Colete (data[].parcels)
parcels[].weightfloatGreutate curentă (kg)
parcels[].initial_weightfloatGreutate inițială (kg)
parcels[].lengthfloatLungime (cm)
parcels[].widthfloatLățime (cm)
parcels[].heightfloatÎnălțime (cm)
Răspuns eroare validare 200
{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "per_page": ["Câmpul per_page nu poate fi mai mare decât 500."]
    }
}

Tracking

Urmărește statusul expedierilor tale.

Returnează statusul curent și istoricul statusurilor.

Query Parameters
ParametruTipObligatoriuDescriere
awbstringDaNumărul AWB al expedierii
 
fetch("https://api.shipo.ro/tracking?awb=2150012345678", {
    method: "GET",
    headers: {
        "Authorization": "Bearer TOKEN"
    }
})
.then(response => response.json())
.then(data => console.log(data));
$ch = curl_init("https://api.shipo.ro/tracking?" . http_build_query(["awb" => "2150012345678"]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer TOKEN"
    ]
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

print_r($response);
Răspuns succes 200
{
    "success": true,
    "data": {
        "awb": "2150012345678",
        "status": "in_transit",
        "statusName": "În tranzit",
        "statusClasses": {
            "order_placed": "pastStep",
            "picked_up": "pastStep",
            "in_transit": "currentStep",
            "out_for_delivery": "futureStep",
            "delivered": "futureStep"
        },
        "statusLog": {}
    }
}
Câmpuri răspuns
CâmpTipDescriere
awbstringNumărul AWB
statusstringStatusul curent
statusNamestringNumele statusului în română
statusClassesobjectClase CSS: pastStep, currentStep, futureStep
statusLogobjectIstoricul statusurilor
Răspuns eroare 200
{ "success": false, "message": "Missing awb" }