# SmartShip API — Own contract (BYOC)

> Generated automatically from the official documentation: https://smartship.ro/api-docs/byoc · Base URL: `https://api.smartship.ro` · Auth: header `X-API-KEY`

BYOC ("Bring Your Own Contract") means you ship through SmartShip on **your own direct contract with the courier**: the AWB is created in your courier account, at your negotiated price. SmartShip provides the platform, the API, tracking and labels. This page covers **only what is different**; everything else (authentication, the `sender` / `recipient` / `content` objects, status, print, cancellation, payouts) works exactly as in the [standard documentation](https://smartship.ro/api-docs).

## Requirements

1) **BYOC enabled on your account**, in the platform: **Own Couriers**. 2) **Your courier account connected** in the same section (username, password / courier API key). The right contract is picked automatically from `courier_id` and your account — you never send a contract ID.

## Couriers available on BYOC

- `1` Cargus
- `2` SameDay (including easybox delivery, see below)
- `3` FanCourier (including FANbox delivery)
- `5` DragonStar
- `6` DPD
- `14` PTT Express
- `34` Transilvania Post
- `35` Komy (no cash on delivery)

## How to use your own contract

The fields below go at the **top level** of the request, not inside `content`. **Without `use_own_contract: 1`, the AWB is created on the SmartShip contract at standard pricing** — switching to your contract is never automatic.

| Field | Type | Required | Description |
|---|---|---|---|
| `show_byoc` | integer | no | On [/cost](https://smartship.ro/api-docs#cost): 1 = also return the prices on your contracts. The same courier may appear twice (your contract and the SmartShip one); your lines have `own_contract: true`. Default 0. |
| `only_byoc` | integer | no | On [/cost](https://smartship.ro/api-docs#cost): 1 = ONLY your contracts + SmartShip Delivery (16, if it covers the route). Much faster, since SmartShip accounts are not quoted. Default 0. |
| `use_own_contract` | integer | no | On [/awb/new](https://smartship.ro/api-docs#awb-new): 1 = create the AWB on your contract with the courier in `courier_id`. Default 0. |

## Locker delivery on your own contract

**easybox:** on BYOC there is no separate easybox courier. Create the AWB with `courier_id: 2` (SameDay) + `use_own_contract: 1` + `content.locker_id` from [/geolocation/easybox](https://smartship.ro/api-docs#geolocation-easybox) — delivery switches to the locker automatically. With `courier_id: 12` on BYOC you get error `4004`.

**FANbox:** `courier_id: 3` (FanCourier) + `use_own_contract: 1` + `content.locker_id` from [/geolocation/fanbox](https://smartship.ro/api-docs#geolocation-fanbox). Max 30 kg and a single parcel per AWB.

## Differences from the SmartShip contract

- The `/awb/new` response contains `own_contract: true`, and `cost` is the courier's real cost on your contract.
- **Exchange parcel** (`swap: 1`): on BYOC only with PTT Express (14).
- **Personal drop-off** (`personal_drop_off`) is not available on BYOC — error `4005`.
- **Komy (35)** does not accept cash on delivery: with `cash_on_delivery` > 0 you get `4050`, and it is not returned by `/cost` either.

## BYOC-only error codes

| Code | Meaning |
|---|---|
| `4001` | The courier in `courier_id` is not available on own contract (see the list above). |
| `4002` | BYOC is not active on the account. The `cod` field gives the reason: `NO_SUBSCRIPTION`, `GRACE_PERIOD` (failed payment), `NOT_STARTED`, `EXPIRED`, `LIMIT_REACHED` (monthly plan limit). |
| `4003` | You have no connected contract for this courier — add it in Own Couriers. |
| `4004` | You sent `courier_id: 12` (easybox) on BYOC — use `courier_id: 2` + `locker_id`. |
| `4005` | `personal_drop_off: 1` is not available on BYOC. |
| `4030` | Insufficient balance for the BYOC fee (below the allowed limit) — top up your account. |
| `4050` | Komy (35) with cash on delivery — Komy does not accept COD. |
| `4010–4014` | The courier rejected the AWB on your contract (e.g. SameDay authentication failed, unknown locality, PTT Express / Transilvania Post error). The `courier_error` field contains the courier's response. |
| `4043, 4044, 4045` | FANbox: invalid `locker_id` / over 30 kg / more than one parcel. |

## Examples

### Quote on your contracts only (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}}'
```

### Create an AWB on your DPD contract

```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
}
```

### FANbox delivery on your FanCourier contract

```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"}}'
```

## BYOC-only endpoints

### GET /geolocation/fanbox — List FANbox lockers

Returns the list of FANbox (FAN Courier) lockers available for locker delivery. Use the `locker_id` from here when creating an AWB on your own FanCourier contract (`courier_id: 3` + `use_own_contract: 1` + `content.locker_id`).

**Example request**

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

---

The rest of the API (authentication, objects, status, print, cancel, payouts) is identical to the standard documentation: https://smartship.ro/api-docs/markdown?lang=en · OpenAPI: https://smartship.ro/api-docs/openapi-byoc.json
