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

Prezentare generală
Autentificare
Client
Orașe
Străzi
Curieri
Tarife
Expedieri
Retururi
Tracking

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
400Request invalid (date lipsă sau incorecte)
401Neautorizat (token lipsă sau invalid)
403Acces interzis (cheie API invalidă)
405Metodă HTTP nepermisă
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 obținerea informațiilor despre contul tău și lista adreselor de ridicare.

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]

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"
    }
]

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 /client/address_list)
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
{
    "10": {
        "rate_id": 10,
        "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"
}

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
Adresa expeditor
sender_address_idinteger|stringCondiționatID adresă salvată. Obligatoriu pt locker/pudo. Dacă specificat, câmpurile de adresă nu mai sunt necesare.
sender_company_namestringNuCompanie expeditor (max. 35 car.)
sender_namestringCondiționatNume complet (max. 48 car.)
sender_phoneinteger|stringCondiționatTelefon (max. 48 car.)
oras_plecarestringCondiționatOraș expeditor (sau sender_address_city_id)
sender_address_city_idintegerCondiționatID oraș expeditor (sau oras_plecare)
sender_address_sectorintegerCondiționatSector 1-6. Obligatoriu pt București
sender_address_street_idintegerCondiționatID stradă (sau strada_plecare)
strada_plecarestringCondiționatStradă text liber (max. 48 car.)
sender_address_street_nointeger|stringCondiționatNr. stradă (max. 10 car.). Obligatoriu dacă nu se folosește sender_address_id
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ționatID punct livrare. Obligatoriu pt locker/pudo
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
oras_sosirestringCondiționatOraș destinatar (sau recipient_address_city_id)
recipient_address_city_idintegerCondiționatID oraș (sau oras_sosire)
recipient_address_sectorintegerCondiționatSector 1-6. Obligatoriu pt București
recipient_address_street_idintegerCondiționatID stradă (sau strada_sosire)
strada_sosirestringCondiționatStradă text liber (max. 48 car.)
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 /client/address_list), câmpurile individuale de adresă nu mai sunt necesare. Pentru locker/pudo, folosește recipient_address_id.
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",
        oras_sosire: "Cluj-Napoca",
        recipient_address_street_id: 3001,
        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",
        "oras_sosire" => "Cluj-Napoca",
        "recipient_address_street_id" => 3001,
        "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 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,
        sender_name: "Ion Popescu",
        sender_phone: "0712345678",
        sender_company_name: "SC Exemplu SRL",
        oras_plecare: "Bucuresti",
        sender_address_sector: 1,
        sender_address_street_id: 5001,
        sender_address_street_no: "10",
        recipient_name: "Maria Ionescu",
        recipient_phone: "0723456789",
        recipient_email: "[email protected]",
        oras_sosire: "Cluj-Napoca",
        recipient_address_street_id: 3001,
        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,
        "sender_name" => "Ion Popescu",
        "sender_phone" => "0712345678",
        "sender_company_name" => "SC Exemplu SRL",
        "oras_plecare" => "Bucuresti",
        "sender_address_sector" => 1,
        "sender_address_street_id" => 5001,
        "sender_address_street_no" => "10",
        "recipient_name" => "Maria Ionescu",
        "recipient_phone" => "0723456789",
        "recipient_email" => "[email protected]",
        "oras_sosire" => "Cluj-Napoca",
        "recipient_address_street_id" => 3001,
        "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",
        oras_sosire: "Cluj-Napoca",
        recipient_address_street_id: 3001,
        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",
        "oras_sosire" => "Cluj-Napoca",
        "recipient_address_street_id" => 3001,
        "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" }