# SmartShip API — Documentație API

> Generat automat din documentația oficială: https://smartship.ro/api-docs · Base URL: `https://api.smartship.ro` · OpenAPI: https://smartship.ro/api-docs/openapi.json

Bine ai venit în documentația API SmartShip.ro. Prin API poți estima costuri de livrare la toți curierii, emite AWB-uri, urmări colete, anula expedieri, descărca etichete și consulta decontările de ramburs — direct din aplicația ta. Toate cererile și răspunsurile folosesc JSON.

## Autentificare

Toate cererile se autentifică cu cheia ta API, trimisă în header-ul `X-API-KEY`. Găsești cheia în platformă: **Contul meu → Setări → API**. Tratează cheia ca pe o parolă — nu o publica în cod client-side (browser, aplicații mobile).

```bash
curl -X GET "https://api.smartship.ro/geolocation/counties" \
  -H "X-API-KEY: YOUR_API_KEY"
```

## Flux recomandat de integrare

**1. Localitățile:** expeditorul și destinatarul se trimit cu ID-ul numeric al localității (`city`), luat din [/geolocation/counties](https://smartship.ro/api-docs#geolocation-counties) și [/geolocation/cities](https://smartship.ro/api-docs#geolocation-cities). Expeditorii salvați în cont îi găsești în [/account/senders](https://smartship.ro/api-docs#account-senders).

**2. Prețul:** [/cost](https://smartship.ro/api-docs#cost) întoarce curierii disponibili, cu prețul cu TVA, sortați crescător. Alegi unul (sau îl lași pe client să aleagă).

**3. AWB-ul:** [/awb/new](https://smartship.ro/api-docs#awb-new) cu `courier_id` din pasul 2 și aceleași date. Răspunsul conține `awb`, `pdf_link` (eticheta) și `tracking_url` (pagina de urmărire pentru destinatar). Trimite și `order_id`, ca să poți regăsi AWB-ul după comanda ta.

**4. Eticheta și ridicarea:** descarci eticheta din `pdf_link` sau [/awb/print](https://smartship.ro/api-docs#awb-print). La curierii unde ridicarea nu se comandă automat, verifici și programezi cu [/pickup/availability](https://smartship.ro/api-docs#pickup-availability) și [/pickup](https://smartship.ro/api-docs#pickup-schedule).

**5. Urmărirea și banii:** statusul cu [/awb/status](https://smartship.ro/api-docs#awb-status) (sau lista cu [/awbs](https://smartship.ro/api-docs#awbs-list)), iar rambursurile încasate cu [/payouts](https://smartship.ro/api-docs#payouts).

**Răspunsuri și erori:** fiecare răspuns JSON are câmpul `status` — `200` înseamnă succes, orice altă valoare e o eroare, explicată în `message` (la erorile de validare `999`, lista completă e în `erori`). Verifică mereu `status` din JSON, nu doar codul HTTP. Codurile posibile sunt listate la fiecare endpoint.

## Curieri disponibili

Tabelul de mai jos e generat automat din platformă și reflectă curierii activi în acest moment, cu regulile fiecăruia. ID-ul din prima coloană se folosește la `courier_id` (emitere) și `curier_preferat` (estimare).

| ID | Curier | Greutate max | Max / colet | Ramburs | Paleți |
|---|---|---|---|---|---|
| 1 | Cargus | 200 kg | 31 kg | da | nu |
| 2 | SameDay | 200 kg | 31 kg | da | nu |
| 5 | DragonStar | 2000 kg | 2000 kg | da | da |
| 8 | PTT Express | 800 kg | 31 kg | da | nu |
| 12 | SameDay EasyBox | 30 kg | 20 kg | da | nu |
| 14 | PTT Express | 2000 kg | 2000 kg | da | da |
| 16 | SmartShip Delivery | 10000 kg | 10000 kg | da | da |
| 19 | FedEx | 200 kg | 68 kg | nu | nu |

## Obiecte comune

### Obiectele sender / recipient

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `name` | string | da | Nume și prenume (sau denumirea firmei). Minim două cuvinte. |
| `address` | string | da | Adresa completă: stradă, număr, detalii. |
| `email` | string | nu | Adresa de email. Destinatarul primește notificări de tracking pe această adresă. |
| `city` | integer | da | ID-ul localității, obținut din [/geolocation/cities](https://smartship.ro/api-docs#geolocation-cities). Nu se trimite denumirea, ci ID-ul numeric. |
| `phone` | string | da | Număr de telefon valid (10 cifre, format românesc). |
| `country` | string | da | Codul țării. Pentru livrări interne: `RO`. |
| `sector` | integer | nu | Obligatoriu doar pentru București: sectorul, valoare 1–6. Pentru restul localităților trimite 0. |

### Obiectul content

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `package_content` | string | da | Descrierea conținutului coletului (apare pe AWB). |
| `parcels` | integer | da | Numărul de colete. Pentru colete cu dimensiuni diferite folosește `parcels_multiple`. |
| `weight` | number | da | Greutatea totală în kg. Se facturează maximul dintre greutatea fizică și cea volumetrică (L×l×h / 6000 per colet). |
| `cash_on_delivery` | number | nu | Valoarea rambursului în RON. 0 = fără ramburs. Atenție: unii curieri (ex. FedEx) nu acceptă ramburs și nu vor apărea la estimare. |
| `length / width / height` | integer | da | Dimensiunile coletului în cm. |
| `insurance` | number | nu | Valoarea declarată / asigurată în RON. 0 = fără asigurare. |
| `iban` | string | nu | IBAN-ul pentru virarea rambursului. Obligatoriu când `cash_on_delivery` > 0. IBAN-ul este validat la fiecare cerere. |
| `open_package` | integer | nu | 1 = destinatarul poate deschide coletul la livrare (unde curierul suportă opțiunea). Implicit 0. **Nu se aplică la livrarea în locker** (nu există curier prezent care să deschidă coletul): dacă trimiți `open_package: 1` împreună cu `locker_id`, opțiunea este ignorată. |
| `order_id` | string | nu | ID-ul comenzii din sistemul tău. Poți regăsi ulterior AWB-ul după el, prin [/awb/order_id/{order_id}](https://smartship.ro/api-docs#awb-order-id). |
| `curier_preferat` | integer | nu | Doar la `/cost`: dacă e specificat, estimarea se face doar pentru acest curier (vezi tabelul de curieri). 0 sau lipsă = toți curierii. |
| `parcels_multiple` | array | nu | Colete multiple cu dimensiuni diferite: listă de obiecte `{"weight": 2, "length": 30, "width": 20, "height": 10}`. Dacă e prezentă, are prioritate față de `parcels`/`weight`/dimensiunile simple. |
| `dpd_shipment_note` | string | nu | Doar pentru DPD: notă suplimentară tipărită pe etichetă. Maxim 200 de caractere. |
| `locker_id` | integer | nu | Pentru livrare la **SameDay easybox (curier 12)**: ID-ul lockerului, din [/geolocation/easybox](https://smartship.ro/api-docs#geolocation-easybox). Fără `locker_id`, easybox nu apare la estimare și nu se poate emite. **Când trimiți `locker_id`, `/cost` întoarce DOAR varianta la locker** (ceilalți curieri livrează la adresă, deci nu sunt opțiuni pentru aceeași trimitere; regula are prioritate și față de `curier_preferat`). Ca să compari livrare acasă vs la locker, fă două apeluri: unul cu `locker_id`, unul fără. Dacă `locker_id` nu e valid, cererea eșuează cu `612` — nu se cotează livrare la adresă în locul lui. Coletul se livrează la locker, nu la adresa destinatarului (max 30 kg). |
| `personal_drop_off` | integer | nu | 1 = **predare personală**: duci tu coletul la un easybox sau punct SameDay, nu vine curierul să-l ridice de la adresa expeditorului. Disponibil doar la **SameDay (2)** și **SameDay easybox (12)**. La `/cost`, cu `personal_drop_off: 1` se întorc doar aceste variante, cu prețul pentru predare personală. Implicit 0. Vezi [Livrare la locker și predare personală](https://smartship.ro/api-docs#livrare-locker). |
| `swap` | integer | nu | Doar la `/awb/new`: 1 = **colet la schimb** (curierul predă coletul și preia altul înapoi). Costul se dublează (tur + retur). Acceptat la **PTT Express (14)** și **SmartShip Delivery (16)**. La curierii care nu îl acceptă cererea este respinsă cu eroarea `699`. Implicit 0. |
| `nocom` | integer | nu | Doar la `/awb/new`: 1 = NU comanda automat curierul pentru ridicare (valabil la FanCourier, DragonStar și PTT Express, unde ridicarea se comandă automat la emitere). Util dacă ai deja o ridicare zilnică programată. Implicit 0. |

## Livrare la locker și predare personală

Sunt două opțiuni independente, care se pot combina: **livrarea la locker** (destinatarul ridică coletul dintr-un locker, nu îl primește acasă) și **predarea personală** (tu, expeditorul, duci coletul la un easybox sau punct SameDay, în loc să vină curierul să-l ridice).

**Livrare la easybox, în 3 pași:** 1) iei ID-ul lockerului din [/geolocation/easybox](https://smartship.ro/api-docs#geolocation-easybox); 2) apelezi [/cost](https://smartship.ro/api-docs#cost) cu `content.locker_id` — răspunsul conține doar varianta `courier_id: 12`; 3) emiți cu [/awb/new](https://smartship.ro/api-docs#awb-new), cu `courier_id: 12` și același `content.locker_id`. Coletul ajunge în locker (max 30 kg), iar `open_package` este ignorat. Dacă trimiți ramburs, lockerul trebuie să accepte plata ramburs (altfel eroarea `6590`).

**Predare personală:** trimite `content.personal_drop_off: 1`, atât la `/cost` cât și la `/awb/new`. Este disponibilă la **SameDay (2)** și **SameDay easybox (12)**, iar prețul este cel pentru predare personală. Nu se comandă curier pentru ridicare: după emitere, duci coletul cu AWB-ul la un easybox sau punct SameDay. Cu alt curier primești eroarea `613`.

**Emitere: predare personală + livrare la easybox**

```bash
curl -X POST "https://api.smartship.ro/awb/new" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"courier_id":12,"recipient":{"name":"Ion Vasile","address":"Str. Memorandumului 28","email":"client@email.com","city":256212,"phone":"0720000000"},"sender":{"name":"Magazinul Meu SRL","address":"Str. Polonă 68","email":"expeditor@magazin.ro","city":255154,"phone":"0721000000"},"content":{"package_content":"Cosmetice","parcels":1,"weight":2,"cash_on_delivery":0,"length":30,"width":20,"height":10,"locker_id":1234,"personal_drop_off":1}}'
```

## Integrare cu AI (ChatGPT, Claude, Cursor)

**Ca să scrie un AI integrarea pentru tine**, dă-i una dintre variantele de mai jos (sunt generate automat din aceeași sursă ca pagina, deci sunt mereu la zi): [specificația OpenAPI](https://smartship.ro/api-docs/openapi.json) (cea mai bună pentru generare de cod), [documentația în Markdown](https://smartship.ro/api-docs/markdown) (o singură limbă, fără duplicări; [în engleză](https://smartship.ro/api-docs/markdown?lang=en)) sau butonul **„Copiază pentru AI”** din capul paginii. Pentru contract propriu există variantele [OpenAPI BYOC](https://smartship.ro/api-docs/openapi-byoc.json) și [Markdown BYOC](https://smartship.ro/api-docs/byoc/markdown). Rezumatul pentru modele AI este în [/llms.txt](https://smartship.ro/llms.txt).

**Conector AI (MCP), fără cod:** poți conecta contul SmartShip direct la Claude, ChatGPT sau orice aplicație compatibilă MCP și lucra în limbaj natural: „unde e coletul X?”, „ce colete au probleme?”, „cât costă un colet de 5 kg la Cluj?”, „emite un AWB pentru comanda 1234”, „anulează AWB-ul Y”. Asistentul poate urmări colete, căuta după comandă, lista expedieri, compara tarife (inclusiv colete cu dimensiuni diferite, asigurare, easybox și predare personală), vedea soldul, facturile și decontările, găsi lockere easybox, descărca etichete, dar și **emite AWB-uri, anula AWB-uri neridicate și programa ridicări FedEx**.

**Cum îl activezi:** din contul SmartShip, [Setări cont → Conector AI](https://smartship.ro/contul-meu/setari) → „Activează conectorul AI”. Primești un link `https://mcp.smartship.ro/c/…` care identifică contul tău, deci tratează-l ca pe o parolă (de acolo îl poți regenera, dezactiva sau trece pe „doar citire” oricând). În Claude: Setări → Conectori → Adaugă conector personalizat și lipești linkul. În Claude Code: `claude mcp add --transport http smartship https://mcp.smartship.ro/c/LINKUL_TAU`. În alte aplicații, adaugă-l ca server MCP de tip HTTP (sau prin `npx mcp-remote` cu același URL).

**Siguranța operațiunilor:** emiterea, anularea și programarea ridicării se fac în doi pași — asistentul îți arată întâi rezumatul (expeditor, destinatar, curier, cost) și execută doar după ce confirmi explicit în chat. Expeditorul se alege doar dintre cei salvați în cont, rambursul se virează doar într-un IBAN al contului, prețul se verifică din nou la confirmare, iar o comandă care are deja AWB activ nu primește încă unul fără cererea ta explicită.

## Endpoints

### POST /cost — Estimare cost livrare

Returnează costul livrării la toți curierii disponibili pentru datele trimise, sortat crescător după preț. Prețurile includ discountul contului tău și sunt exprimate în RON, **cu TVA inclus** (câmpul `cost`). Pentru comoditate întoarcem și `cost_fara_tva`. Fiecare curier include și `ramburs_delay` — estimarea timpului până la plata rambursului (`median` și `p75`, în zile de la livrare), calculată din livrările anterioare; `null` dacă nu avem date suficiente. Curierii care nu pot onora cererea (reguli de greutate, ramburs, rută) sunt omiși din răspuns.

Body: obiectele comune `sender`, `recipient` și `content` (vezi „Obiecte comune”).

**Exemplu de cerere**

```bash
curl -X POST "https://api.smartship.ro/cost" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient":{"name":"Ion Vasile","address":"Str. Memorandumului 28","email":"client@email.com","city":256212,"phone":"0720123456","country":"RO","sector":0},"sender":{"name":"Magazinul Meu SRL","address":"Str. Polonă 68","email":"expeditor@magazin.ro","city":255154,"phone":"0720333222","country":"RO","sector":1},"content":{"package_content":"Piese auto","parcels":1,"weight":2,"cash_on_delivery":0,"length":30,"width":20,"height":10,"insurance":0,"iban":"","open_package":0,"curier_preferat":0}}'
```

**Exemplu cu colete multiple — dimensiuni diferite (parcels_multiple)**

```json
{
    "recipient": {
        "name": "Ion Vasile",
        "address": "Str. Memorandumului 28",
        "email": "client@email.com",
        "city": 256212,
        "phone": "0720123456",
        "country": "RO",
        "sector": 0
    },
    "sender": {
        "name": "Magazinul Meu SRL",
        "address": "Str. Polonă 68",
        "email": "expeditor@magazin.ro",
        "city": 255154,
        "phone": "0720333222",
        "country": "RO",
        "sector": 1
    },
    "content": {
        "package_content": "Piese auto",
        "cash_on_delivery": 0,
        "insurance": 0,
        "iban": "",
        "open_package": 0,
        "curier_preferat": 0,
        "parcels_multiple": [
            {
                "weight": 2,
                "length": 30,
                "width": 20,
                "height": 10
            },
            {
                "weight": 5,
                "length": 40,
                "width": 30,
                "height": 20
            },
            {
                "weight": 1.5,
                "length": 20,
                "width": 15,
                "height": 10
            }
        ]
    }
}
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "costs": [
        {
            "courier_id": 1,
            "courier_name": "Cargus",
            "courier_logo": "https://smartship.ro/images/logo_curieri/cargus.png",
            "cost": 16.129999999999999005240169935859739780426025390625,
            "cost_fara_tva": 13.3300000000000000710542735760100185871124267578125,
            "ramburs_delay": {
                "median": 4,
                "p75": 5
            },
            "delivery_date": "2026-07-10",
            "pickup_date": "2026-07-09"
        },
        {
            "courier_id": 19,
            "courier_name": "FedEx",
            "courier_logo": "https://smartship.ro/images/logo_curieri/fedex_logo.png",
            "cost": 23.690000000000001278976924368180334568023681640625,
            "cost_fara_tva": 19.5799999999999982946974341757595539093017578125,
            "ramburs_delay": null,
            "delivery_date": "2026-07-10",
            "pickup_date": "2026-07-09"
        },
        {
            "courier_id": 6,
            "courier_name": "DPD",
            "courier_logo": "https://smartship.ro/images/logo_curieri/dpd.png",
            "cost": 16.6099999999999994315658113919198513031005859375,
            "cost_fara_tva": 13.730000000000000426325641456060111522674560546875,
            "ramburs_delay": {
                "median": 1,
                "p75": 1
            },
            "delivery_date": "2026-07-10",
            "pickup_date": "2026-07-09"
        }
    ],
    "total_weight_calculated": 2
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `999` | Erori de validare. Câmpul `erori` conține lista problemelor (nume incomplet, telefon invalid, localitate lipsă etc.). |
| `201` | IBAN invalid (când `cash_on_delivery` > 0). |
| `612` | `curier_preferat = 12` (easybox) fără `locker_id` valid. |
| `613` | `personal_drop_off: 1` cu un `curier_preferat` diferit de SameDay (2) sau easybox (12). |
| `301` | Cheie API invalidă. |

### POST /awb/new — Emitere AWB

Emite un AWB la curierul ales prin `courier_id`. Costul se calculează exact ca la `/cost` și se scade din creditul contului (sau intră pe factura la termen). Recomandare: apelează întâi `/cost` și lasă clientul/sistemul să aleagă curierul din răspuns.

Body: obiectele comune `sender`, `recipient` și `content` (vezi „Obiecte comune”).

**Câmpuri suplimentare**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `courier_id` | integer | da | ID-ul curierului cu care se emite AWB-ul — vezi tabelul de curieri de mai sus. |

**Exemplu de cerere**

```bash
curl -X POST "https://api.smartship.ro/awb/new" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"courier_id":19,"recipient":{"name":"Ion Vasile","address":"Str. Memorandumului 28","email":"client@email.com","city":256212,"phone":"0720123456","country":"RO","sector":0},"sender":{"name":"Magazinul Meu SRL","address":"Str. Polonă 68","email":"expeditor@magazin.ro","city":255154,"phone":"0720333222","country":"RO","sector":1},"content":{"package_content":"Piese auto","parcels":1,"weight":2,"cash_on_delivery":0,"length":30,"width":20,"height":10,"insurance":0,"iban":"","open_package":0,"order_id":"CMD-1234"}}'
```

**Exemplu cu colete multiple — dimensiuni diferite (parcels_multiple)**

```json
{
    "courier_id": 1,
    "recipient": {
        "name": "Ion Vasile",
        "address": "Str. Memorandumului 28",
        "email": "client@email.com",
        "city": 256212,
        "phone": "0720123456",
        "country": "RO",
        "sector": 0
    },
    "sender": {
        "name": "Magazinul Meu SRL",
        "address": "Str. Polonă 68",
        "email": "expeditor@magazin.ro",
        "city": 255154,
        "phone": "0720333222",
        "country": "RO",
        "sector": 1
    },
    "content": {
        "package_content": "Piese auto",
        "cash_on_delivery": 0,
        "insurance": 0,
        "iban": "",
        "open_package": 0,
        "order_id": "CMD-1234",
        "parcels_multiple": [
            {
                "weight": 2,
                "length": 30,
                "width": 20,
                "height": 10
            },
            {
                "weight": 5,
                "length": 40,
                "width": 30,
                "height": 20
            },
            {
                "weight": 1.5,
                "length": 20,
                "width": 15,
                "height": 10
            }
        ]
    }
}
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "message": "AWB created.",
    "awb": "874156063265",
    "courier_id": 19,
    "courier_name": "FedEx",
    "courier_logo": "https://smartship.ro/images/logo_curieri/fedex_logo.png",
    "cost": 23.690000000000001278976924368180334568023681640625,
    "cost_fara_tva": 19.5799999999999982946974341757595539093017578125,
    "pdf_link": "https://smartship.ro/api/CHEIA_TA_API/print/874156063265",
    "tracking_url": "https://smartship.ro/t/aB3xK9mQw2"
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `601` | `courier_id` invalid — nu e în lista curierilor acceptați. |
| `602` | Curierul nu este disponibil momentan. |
| `603` | Niciun curier disponibil pentru datele trimise. |
| `605` | Credit insuficient. Răspunsul include creditul disponibil și costul necesar. |
| `606` | Curierul ales nu acceptă ramburs (ex. FedEx). |
| `806` | easybox: `locker_id` lipsă sau invalid. |
| `613` | `personal_drop_off: 1` cu un `courier_id` diferit de SameDay (2) sau easybox (12). |
| `6589` | easybox: lockerul ales nu este disponibil momentan. |
| `6590` | easybox: lockerul ales nu acceptă plată ramburs — alege alt locker sau elimină rambursul. |
| `9855` | Costul nu a putut fi calculat pentru curierul ales (verifică datele / disponibilitatea rutei). |
| `999` | Erori de validare — vezi câmpul `erori`. |
| `301` | AWB-ul nu s-a emis. Câmpul `err` conține răspunsul curierului (fără datele trimise de noi: nu mai apar `fields` la Cargus și `datasend` la SameDay). |
| `5014, 5015, 5016, 50111` | DPD a refuzat expedierea. Răspunsul conține doar `status` și `message`. |

### GET /awb/status/{awb} — Status și tracking AWB

Returnează statusul curent și istoricul de tracking pentru un AWB emis prin contul tău. Statusurile principale: 0 = emis (neridicat), 1 = în tranzit, 2 = livrat, 5/6 = retur, 10 = anulat.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `awb (path)` | string | da | Numărul AWB-ului. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/awb/status/{awb}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "awb": "874156063265",
    "tracking_link": "https://smartship.ro/t/aB3xK9mQw2",
    "awb_status": 1,
    "awb_status_desc": "In tranzit",
    "carrier": "FedEx",
    "tracking": [
        {
            "date": "2026-07-09 14:20:00",
            "event_id": "1",
            "description": "Colet ridicat de la expeditor",
            "locality": "Bucuresti"
        },
        {
            "date": "2026-07-10 08:15:00",
            "event_id": "5",
            "description": "In curs de livrare",
            "locality": "Cluj-Napoca"
        }
    ]
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `301` | AWB-ul nu există sau nu aparține contului tău. |

### GET /awb/order_id/{order_id} — Status AWB după order_id

Identic cu [/awb/status](https://smartship.ro/api-docs#awb-status), dar caută AWB-ul după `order_id`-ul trimis la emitere — util când sistemul tău nu stochează numărul AWB.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `order_id (path)` | string | da | ID-ul comenzii trimis în `content.order_id` la emitere. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/awb/order_id/{order_id}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

### GET /awb/cancel/{awb} — Anulare AWB

Anulează un AWB emis prin contul tău. Anularea se face și la curier, iar costul este returnat în creditul contului o singură dată, numai după ce curierul confirmă anularea. Dacă curierul refuză sau nu răspunde, AWB-ul rămâne activ și nu se returnează nimic. Un AWB ridicat deja de curier nu mai poate fi anulat.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `awb (path)` | string | da | Numărul AWB-ului. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/awb/cancel/{awb}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "message": "AWB canceled.",
    "awb": "874156063265"
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `301` | AWB-ul nu există sau nu aparține contului tău. |
| `608` | Curierul a refuzat anularea (ex. coletul e deja ridicat) sau nu a răspuns; AWB-ul rămâne activ, fără returnarea costului. Motivul este în câmpul `message` (răspunsul nu mai conține câmpurile brute `res`, `res_dragon`, `err`). Refuzul DPD răspunde tot `608`, cu mesajul „Expedierea nu se poate anula. Mesaj DPD: …” (înainte venea cu status `200`). |
| `205` | AWB-ul este deja anulat (valabil pentru toți curierii). Cererea nu mai ajunge la curier și costul nu se returnează a doua oară. |
| `206` | Expedierea nu mai poate fi anulată (a fost deja ridicată/livrată), inclusiv la Cargus, când coletul a fost deja preluat. |
| `220` | Anularea pentru acest curier nu este disponibilă prin API. Exemplu: **PTT Express (14)**, care nu permite anularea unui AWB emis; AWB-ul rămâne activ și costul nu se returnează (nu mai există răspunsul `200` cu `warning: ptt_no_api_cancel`). |

### GET /awb/print/{awb}/{format} — Descărcare etichetă (PDF)

Returnează eticheta AWB-ului în format PDF, gata de printat. Răspunsul este fișierul PDF (nu JSON).

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `awb (path)` | string | da | Numărul AWB-ului. |
| `format (path)` | string | nu | `A4` (implicit) sau `A6` (etichetă compactă, pentru imprimante de etichete). |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/awb/print/{awb}/{format}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

### GET /geolocation/counties — Listă județe

Returnează lista județelor, cu ID-urile folosite la căutarea localităților.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `country (query)` | string | nu | Codul țării. Implicit `RO`. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/geolocation/counties" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "counties": [
        {
            "id": 1,
            "county": "Alba"
        },
        {
            "id": 2,
            "county": "Arad"
        }
    ]
}
```

### GET /geolocation/cities — Listă localități

Returnează localitățile dintr-un județ. ID-ul localității este cel care se trimite în câmpul `city` la expeditor/destinatar. Recomandare: sincronizează lista o dată pe zi, nu la fiecare cerere.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `county (query)` | integer | da | ID-ul județului, din [/geolocation/counties](https://smartship.ro/api-docs#geolocation-counties). |
| `loc_sel (query)` | string | nu | Opțional: numele unei localități; dacă e găsită, răspunsul include și `city_selected` cu ID-ul ei. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/geolocation/cities" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "county": {
        "id": 13,
        "name": "Cluj"
    },
    "city_selected": null,
    "cities": [
        {
            "id": 256212,
            "city": "Cluj-Napoca"
        },
        {
            "id": 256213,
            "city": "Apahida"
        }
    ]
}
```

### GET /geolocation/easybox — Listă lockere easybox

Returnează lista lockerelor easybox (Sameday) disponibile pentru livrare.

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/geolocation/easybox" \
  -H "X-API-KEY: YOUR_API_KEY"
```

### GET /account/senders — Expeditori salvați

Returnează expeditorii salvați în contul tău (adresele de ridicare). Pentru un singur expeditor: `/account/senders/{id}` — răspunsul conține obiectul `sender` în loc de lista `senders`.

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/account/senders" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "senders": [
        {
            "id": 1042,
            "nume": "Magazinul Meu SRL",
            "telefon": "0720333222",
            "email": "expeditor@magazin.ro",
            "judet": "Bucuresti",
            "localitate": "Bucuresti",
            "adresa": "Str. Polonă 68",
            "localitate_id": 255154,
            "sector": 1
        }
    ]
}
```

### GET /account/balance — Sold și limită de credit

Returnează soldul curent al contului, limita de credit și suma disponibilă pentru emitere. Util înainte de `/awb/new`, ca să eviți eroarea 605 (credit insuficient).

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/account/balance" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "balance": -657.720000000000027284841053187847137451171875,
    "credit_limit": 10000,
    "payment_on_terms": 1,
    "available_for_shipping": 9342.280000000000654836185276508331298828125,
    "currency": "RON"
}
```

### GET /awbs — Lista expedierilor

Returnează expedierile contului, paginat, cu filtre — pentru reconciliere și sincronizare în ERP. Statusuri: 0 = emis, 1 = în livrare, 2 = livrat, 5 = refuz primire, 6 = returnat, 10 = anulat.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `page (query)` | integer | nu | Pagina. Implicit 1. |
| `per_page (query)` | integer | nu | Rezultate per pagină. Implicit 50, maxim 100. |
| `status (query)` | integer | nu | Filtrează după status (vezi lista de mai sus). |
| `date_from / date_to (query)` | string | nu | Interval de date, format `YYYY-MM-DD`. |
| `order_id (query)` | string | nu | Filtrează după ID-ul comenzii tale. |
| `q (query)` | string | nu | Căutare text (minim 2 caractere) în numărul AWB, numele destinatarului, localitatea destinatarului și ID-ul comenzii. |
| `courier (query)` | integer | nu | Filtrează după curier — ID-ul numeric returnat în câmpul `courier_id`. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/awbs" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "total_awbs_count": 583,
    "current_page": 1,
    "per_page": 50,
    "total_pages": 12,
    "awbs": [
        {
            "awb": "874156063265",
            "date": "2026-07-09 15:20:03",
            "courier_id": 19,
            "courier_name": "FedEx",
            "status": 2,
            "status_desc": "Livrat",
            "cost": 19.760000000000001563194018672220408916473388671875,
            "cash_on_delivery": 0,
            "insurance": 0,
            "parcels": 1,
            "weight": 1,
            "recipient_name": "Ion Vasile",
            "recipient_county": "Cluj",
            "recipient_city": "Cluj-Napoca",
            "order_id": "CMD-1234",
            "tracking_url": "https://smartship.ro/t/aB3xK9mQw2"
        }
    ]
}
```

### GET /pickup/availability/{awb} — Disponibilitate ridicare FedEx

Pentru AWB-urile FedEx: returnează zilele și intervalele orare în care poate fi programată ridicarea coletului de la expeditor. Folosește valorile returnate la [POST /pickup/{awb}](https://smartship.ro/api-docs#pickup-schedule).

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `awb (path)` | string | da | Numărul AWB-ului FedEx. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/pickup/availability/{awb}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "awb": "874156063265",
    "options": [
        {
            "pickup_date": "2026-07-10",
            "schedule_day": "SAME_DAY",
            "available": true,
            "cutoff_time": "16:30:00",
            "default_ready_time": "15:00:00",
            "ready_time_options": [
                "09:00:00",
                "12:00:00",
                "15:00:00"
            ],
            "latest_time_options": [
                "12:00:00",
                "15:00:00",
                "18:00:00"
            ]
        }
    ]
}
```

### POST /pickup/{awb} — Programare ridicare FedEx

Programează ridicarea coletului FedEx de la adresa expeditorului, în ziua și intervalul ales (din [/pickup/availability](https://smartship.ro/api-docs#pickup-availability)). Maxim o comandă de ridicare per AWB. Expeditorul primește confirmarea pe email.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `awb (path)` | string | da | Numărul AWB-ului FedEx. |

**Câmpuri suplimentare**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `pickup_date` | string | da | Ziua ridicării, format `YYYY-MM-DD`. |
| `ready_time` | string | da | Ora de la care coletul e pregătit, format `HH:MM`. |
| `latest_time` | string | da | Ora până la care e disponibil, format `HH:MM`. |

**Exemplu de cerere**

```bash
curl -X POST "https://api.smartship.ro/pickup/{awb}" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pickup_date":"2026-07-10","ready_time":"12:00","latest_time":"18:00"}'
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "message": "Pickup scheduled.",
    "awb": "874156063265",
    "pickup_confirmation_code": "ABC123",
    "location": "CLJA",
    "pickup_date": "2026-07-10",
    "ready_time": "12:00",
    "latest_time": "18:00"
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `302` | AWB-ul nu este FedEx. |
| `305` | Există deja o ridicare programată pe acest AWB. |
| `998` | FedEx nu a confirmat — verifică intervalul cu /pickup/availability. |

### GET /invoices — Facturi

Returnează facturile emise către contul tău, paginat, cu link PDF public — pentru reconciliere contabilă alături de [/payouts](https://smartship.ro/api-docs#payouts).

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `page (query)` | integer | nu | Pagina. Implicit 1. |
| `per_page (query)` | integer | nu | Rezultate per pagină. Implicit 50, maxim 100. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/invoices" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "total_invoices_count": 22,
    "current_page": 1,
    "per_page": 50,
    "total_pages": 1,
    "invoices": [
        {
            "number": "SS1283958963",
            "date": "2026-07-01",
            "due_date": "2026-07-15",
            "total": 1240.5,
            "currency": "RON",
            "pdf_link": "https://smartship.ro/factura/xxxxxxxx"
        }
    ]
}
```

### GET /payouts — Listă deconturi ramburs

Returnează deconturile de ramburs virate către contul tău, paginat. Fiecare decont are un număr, dată, valoare totală și IBAN-ul destinație.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `page (query)` | integer | nu | Pagina. Implicit 1. |
| `per_page (query)` | integer | nu | Rezultate per pagină. Implicit 50, maxim 100. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/payouts" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "total_payouts_count": 128,
    "current_page": 1,
    "per_page": 50,
    "total_pages": 3,
    "payouts": [
        {
            "number": "PN472375",
            "date": "2026-07-08",
            "client": "Magazinul Meu SRL",
            "valoare": 4820.5,
            "iban": "RO49AAAA1B31007593840000",
            "awb_count": 37
        }
    ]
}
```

### GET /payouts/{number} — Detalii decont

Returnează detaliile unui decont: liniile componente, cu AWB-ul, destinatarul și suma fiecărei încasări incluse.

**Parametri**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `number (path)` | string | da | Numărul decontului, din [/payouts](https://smartship.ro/api-docs#payouts). Ex: `PN472375`. |

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/payouts/{number}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "payout": {
        "number": "PN472375",
        "date": "2026-07-08",
        "iban": "RO49AAAA1B31007593840000",
        "value": 4820.5,
        "lines": [
            {
                "date": "2026-07-07",
                "number": "PN472375",
                "value": 250,
                "recipient": "Ion Vasile",
                "awb": "874156063265"
            }
        ]
    }
}
```

### POST /transport-offer — Solicită ofertă transport (marfă grea)

Pentru marfă grea/voluminoasă (peste pragul standard), unde curierii obișnuiți nu sunt potriviți, poți cere o ofertă de transport dedicată. Trimiți detaliile expedierii + parametrii de transport, iar echipa SmartShip revine cu o ofertă (preț, transportator, termen). Verifici starea cu `GET /transport-offer/{ref}` și accepți/refuzi când oferta e gata. La acceptare se emite automat un AWB SmartShip Delivery și se scade prețul ofertei din credit.

Body: obiectele comune `sender`, `recipient` și `content` (vezi „Obiecte comune”).

**Câmpuri suplimentare**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `content.weight` | number | da | Greutate totală (kg). |
| `content.parcels` | integer | nu | Număr colete/paleți. Implicit 1. |
| `content.length/width/height` | integer | nu | Dimensiuni (cm). |
| `content.truck_type` | string | nu | Tip camion dorit: `box, prelata, platforma, basculanta, cisterna, container, agabaritic, autotransportator, cap_tractor`. |
| `content.groupage / adr / temperature_controlled` | boolean | nu | Acceptă grupaj / marfă ADR / necesită temperatură controlată. |
| `content.budget` | number | nu | Buget estimativ (lei), orientativ pentru ofertă. |
| `content.pickup_deadline / delivery_deadline` | string | nu | Termene dorite de preluare/livrare (text liber). |
| `content.message` | string | nu | Detalii suplimentare pentru echipă. |
| `content.client_reference` | string | nu | Referința ta internă (cod comandă etc.). O returnăm în `GET` și o afișăm peste tot (panou, emailuri). |

**Exemplu de cerere**

```bash
curl -X POST "https://api.smartship.ro/transport-offer" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipient":{"name":"Fabrica X SRL","address":"Str. Industriei 5","email":"receptie@fabricax.ro","city":253300,"phone":"0731234567","country":"RO","sector":0},"sender":{"name":"Depozit Central SRL","address":"Str. Logisticii 10","email":"expeditii@depozit.ro","city":252424,"phone":"0721234567","country":"RO","sector":0},"content":{"weight":900,"parcels":2,"length":200,"width":120,"height":150,"truck_type":"prelata","groupage":true,"adr":false,"temperature_controlled":false,"budget":1500,"pickup_deadline":"1-2 zile","delivery_deadline":"3-5 zile","message":"Marfă paletizată, descărcare cu stivuitor.","client_reference":"CMD-4821"}}'
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "message": "Solicitare înregistrată.",
    "ref": "OFT-2026-00123",
    "request_status": "new"
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `999` | Erori de validare (câmpul `erori` le listează). |
| `422` | Greutate sub pragul minim pentru solicitare de ofertă transport (marfă grea). Câmpul `min_weight` indică pragul. Sub prag, folosește `/cost` + `/awb/new`. |
| `301` | Cheie API invalidă. |

### GET /transport-offer/{ref} — Verifică oferta de transport

Întoarce starea solicitării și oferta primită (când e gata). Interoghează oricând ca să vezi dacă echipa a revenit cu o ofertă. `request_status`: `new, in_review, offered, accepted, rejected` (ai refuzat oferta), `declined` (SmartShip nu a putut oferi o variantă), `cancelled, expired, completed`. La `rejected`/`declined`, `resolution_message` conține motivul (dacă a fost dat). Când `offer.acceptable = true`, poți accepta.

**Exemplu de cerere**

```bash
curl -X GET "https://api.smartship.ro/transport-offer/{ref}" \
  -H "X-API-KEY: YOUR_API_KEY"
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "ref": "OFT-2026-00123",
    "client_reference": "CMD-4821",
    "request_status": "offered",
    "resolution_message": null,
    "created_at": "2026-08-13 10:20:00",
    "shipment": {
        "weight": 900,
        "parcels": 2,
        "dimensions": {
            "length": 200,
            "width": 120,
            "height": 150
        },
        "sender_city": 252424,
        "recipient_city": 253300,
        "truck_type": "prelata",
        "groupage": true,
        "adr": false,
        "temperature_controlled": false
    },
    "offer": {
        "price": 1500,
        "carrier": "Transportator Partener SRL",
        "delivery_term": "3-5 zile lucrătoare",
        "valid_until": "2026-08-20",
        "message": "Preț valabil pentru încărcare paletizată.",
        "expired": false,
        "acceptable": true
    },
    "awb": null
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `404` | Solicitarea nu există (sau nu e a contului tău). |

### POST /transport-offer/{ref}/accept — Acceptă oferta de transport

Acceptă oferta primită. Se emite automat un AWB SmartShip Delivery pentru expediere și se scade **prețul ofertei** din creditul contului (verificat înainte). Idempotent: re-apelarea întoarce același AWB. Răspunsul conține AWB-ul și link-ul de tracking.

**Exemplu de răspuns**

```json
{
    "status": 200,
    "message": "Ofertă acceptată. AWB emis.",
    "awb": "SMA3170895",
    "tracking_url": "https://smartship.ro/t/aB3xK9mQw2",
    "cost": 1500
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `409` | Nu există o ofertă activă de acceptat. |
| `410` | Oferta a expirat. |
| `601` | Credite insuficiente pentru prețul ofertei. |

### POST /transport-offer/{ref}/reject — Refuză oferta de transport

Refuză oferta primită. Opțional poți trimite `reason` (motivul) în body.

**Câmpuri suplimentare**

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `reason` | string | nu | Motivul refuzului (opțional). |

**Exemplu de cerere**

```bash
curl -X POST "https://api.smartship.ro/transport-offer/{ref}/reject" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Am găsit o variantă mai avantajoasă."}'
```

**Exemplu de răspuns**

```json
{
    "status": 200,
    "message": "Ofertă refuzată."
}
```

**Coduri de eroare**

| Cod | Semnificație |
|---|---|
| `409` | Oferta nu mai poate fi refuzată. |

---

Ai contract direct cu un curier și vrei să emiți pe el prin SmartShip? Vezi [documentația pentru contract propriu (BYOC)](https://smartship.ro/api-docs/byoc). (https://smartship.ro/api-docs/byoc/markdown)
