# SmartShip API — Contract propriu (BYOC)

> Generat automat din documentația oficială: https://smartship.ro/api-docs/byoc · Base URL: `https://api.smartship.ro` · Autentificare: header `X-API-KEY`

BYOC („Bring Your Own Contract”) înseamnă că emiți prin SmartShip pe **contractul tău direct cu curierul**: AWB-ul se creează în contul tău de la curier, la prețul negociat de tine. SmartShip îți dă platforma, API-ul, urmărirea și etichetele. Pagina descrie **doar ce este diferit**; tot restul (autentificare, obiectele `sender` / `recipient` / `content`, status, print, anulare, decontări) funcționează exact ca în [documentația standard](https://smartship.ro/api-docs).

## Ce îți trebuie

1) **BYOC activ pe cont**, din platformă: **Curieri Proprii**. 2) **Contul tău de curier conectat** în aceeași secțiune (utilizator, parolă / cheie API de la curier). Contractul potrivit se alege automat după `courier_id` și contul tău — nu trimiți niciun ID de contract.

## Curieri disponibili pe BYOC

- `1` Cargus
- `2` SameDay (inclusiv livrare la easybox, vezi mai jos)
- `3` FanCourier (inclusiv livrare la FANbox)
- `5` DragonStar
- `6` DPD
- `14` PTT Express
- `34` Transilvania Post
- `35` Komy (fără ramburs)

## Cum alegi contractul propriu

Câmpurile de mai jos se trimit la **nivelul principal** al cererii, nu în `content`. **Fără `use_own_contract: 1`, AWB-ul se emite pe contractul SmartShip, cu tariful standard** — trecerea pe contractul tău nu se face automat.

| Câmp | Tip | Obligatoriu | Descriere |
|---|---|---|---|
| `show_byoc` | integer | nu | La [/cost](https://smartship.ro/api-docs#cost): 1 = adaugă în răspuns și prețurile pe contractele tale. Același curier poate apărea de două ori (contractul tău și cel SmartShip); liniile tale au `own_contract: true`. Implicit 0. |
| `only_byoc` | integer | nu | La [/cost](https://smartship.ro/api-docs#cost): 1 = DOAR contractele tale + SmartShip Delivery (16, dacă acoperă ruta). Răspuns mult mai rapid, fiindcă nu mai cotăm conturile SmartShip. Implicit 0. |
| `use_own_contract` | integer | nu | La [/awb/new](https://smartship.ro/api-docs#awb-new): 1 = emite AWB-ul pe contractul tău la curierul din `courier_id`. Implicit 0. |

## Livrare la locker pe contract propriu

**easybox:** pe BYOC nu există un curier separat pentru easybox. Emiți cu `courier_id: 2` (SameDay) + `use_own_contract: 1` + `content.locker_id` din [/geolocation/easybox](https://smartship.ro/api-docs#geolocation-easybox) — livrarea comută automat la locker. Cu `courier_id: 12` pe BYOC primești eroarea `4004`.

**FANbox:** `courier_id: 3` (FanCourier) + `use_own_contract: 1` + `content.locker_id` din [/geolocation/fanbox](https://smartship.ro/api-docs#geolocation-fanbox). Maxim 30 kg și un singur colet pe AWB.

## Ce este diferit față de contractul SmartShip

- Răspunsul la `/awb/new` conține `own_contract: true`, iar `cost` este costul real de la curier, pe contractul tău.
- **Colet la schimb** (`swap: 1`): pe BYOC doar la PTT Express (14).
- **Predare personală** (`personal_drop_off`) nu este disponibilă pe BYOC — eroarea `4005`.
- **Komy (35)** nu acceptă ramburs: cu `cash_on_delivery` > 0 primești `4050` și nu apare nici la `/cost`.

## Coduri de eroare doar pe BYOC

| Cod | Semnificație |
|---|---|
| `4001` | Curierul din `courier_id` nu este disponibil pe contract propriu (vezi lista de mai sus). |
| `4002` | BYOC nu este activ pe cont. Câmpul `cod` spune motivul: `NO_SUBSCRIPTION`, `GRACE_PERIOD` (plată eșuată), `NOT_STARTED`, `EXPIRED`, `LIMIT_REACHED` (limita lunară a planului). |
| `4003` | Nu ai un contract conectat pentru acest curier — adaugă-l în Curieri Proprii. |
| `4004` | Ai trimis `courier_id: 12` (easybox) pe BYOC — folosește `courier_id: 2` + `locker_id`. |
| `4005` | `personal_drop_off: 1` nu este disponibil pe BYOC. |
| `4030` | Sold insuficient pentru taxa BYOC (sub limita permisă) — alimentează contul. |
| `4050` | Komy (35) cu ramburs — Komy nu acceptă ramburs. |
| `4010–4014` | Curierul a refuzat emiterea pe contractul tău (ex. autentificare SameDay eșuată, localitate neidentificată, eroare PTT Express / Transilvania Post). Câmpul `courier_error` conține răspunsul curierului. |
| `4043, 4044, 4045` | FANbox: `locker_id` invalid / peste 30 kg / mai mult de un colet. |

## Exemple

### Estimare doar pe contractele tale (only_byoc)

```bash
curl -X POST "https://api.smartship.ro/cost" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"only_byoc":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","parcels":1,"weight":2,"cash_on_delivery":0,"length":30,"width":20,"height":10,"insurance":0,"iban":"","open_package":0}}'
```

### Emitere pe contractul tău DPD

```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":6,"use_own_contract":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","parcels":1,"weight":2,"cash_on_delivery":150,"iban":"RO49AAAA1B31007593840000","length":30,"width":20,"height":10,"insurance":0,"open_package":0,"order_id":"CMD-4821"}}'
```

```json
{
    "status": 200,
    "message": "AWB created (BYOC).",
    "awb": "81396540190",
    "courier_id": 6,
    "courier_name": "DPD",
    "cost": 16.6099999999999994315658113919198513031005859375,
    "cost_fara_tva": 13.730000000000000426325641456060111522674560546875,
    "pdf_link": "https://smartship.ro/api/CHEIA_TA_API/print/81396540190",
    "tracking_url": "https://smartship.ro/t/aB3xK9mQw2",
    "own_contract": true
}
```

### Emitere la FANbox, pe contractul tău FanCourier

```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":3,"use_own_contract":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":"Cosmetice","parcels":1,"weight":2,"cash_on_delivery":0,"length":30,"width":20,"height":10,"insurance":0,"open_package":0,"locker_id":"FAN0968"}}'
```

## Endpoint-uri disponibile doar pe BYOC

### GET /geolocation/fanbox — Listă lockere FANbox

Returnează lista lockerelor FANbox (FAN Courier) disponibile pentru livrare la locker. Folosește `locker_id` de aici la emiterea pe contract propriu FanCourier (`courier_id: 3` + `use_own_contract: 1` + `content.locker_id`).

**Exemplu de cerere**

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

---

Restul API-ului (autentificare, obiecte, status, print, anulare, decontări) este identic cu documentația standard: https://smartship.ro/api-docs/markdown · OpenAPI: https://smartship.ro/api-docs/openapi-byoc.json
