# SmartShip API — API Documentation

> Generated automatically from the official documentation: https://smartship.ro/api-docs · Base URL: `https://api.smartship.ro` · OpenAPI: https://smartship.ro/api-docs/openapi.json

Welcome to the SmartShip.ro API documentation. The API lets you estimate delivery costs across all couriers, create AWBs, track parcels, cancel shipments, download labels and retrieve cash-on-delivery payouts — straight from your application. All requests and responses use JSON.

## Authentication

All requests are authenticated with your API key, sent in the `X-API-KEY` header. You can find your key in the platform: **My account → Settings → API**. Treat the key like a password — never expose it in client-side code (browser, mobile apps).

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

## Recommended integration flow

**1. Localities:** sender and recipient are sent with the numeric locality ID (`city`), taken from [/geolocation/counties](https://smartship.ro/api-docs#geolocation-counties) and [/geolocation/cities](https://smartship.ro/api-docs#geolocation-cities). Senders saved in your account are available at [/account/senders](https://smartship.ro/api-docs#account-senders).

**2. Price:** [/cost](https://smartship.ro/api-docs#cost) returns the available couriers with VAT-inclusive prices, sorted ascending. Pick one (or let your customer choose).

**3. AWB:** [/awb/new](https://smartship.ro/api-docs#awb-new) with the `courier_id` from step 2 and the same data. The response contains `awb`, `pdf_link` (the label) and `tracking_url` (the tracking page for the recipient). Also send `order_id` so you can find the AWB by your order later.

**4. Label and pickup:** download the label from `pdf_link` or [/awb/print](https://smartship.ro/api-docs#awb-print). For couriers where pickup is not ordered automatically, check and book it with [/pickup/availability](https://smartship.ro/api-docs#pickup-availability) and [/pickup](https://smartship.ro/api-docs#pickup-schedule).

**5. Tracking and money:** status via [/awb/status](https://smartship.ro/api-docs#awb-status) (or the list via [/awbs](https://smartship.ro/api-docs#awbs-list)), and collected cash on delivery via [/payouts](https://smartship.ro/api-docs#payouts).

**Responses and errors:** every JSON response has a `status` field — `200` means success, any other value is an error explained in `message` (for validation errors `999`, the full list is in `erori`). Always check the JSON `status`, not just the HTTP code. The possible codes are listed for each endpoint.

## Available couriers

The table below is generated automatically from the platform and reflects the currently active couriers and their rules. The ID in the first column is used for `courier_id` (AWB creation) and `curier_preferat` (cost estimation).

| ID | Courier | Max weight | Max / parcel | COD | Pallets |
|---|---|---|---|---|---|
| 1 | Cargus | 200 kg | 31 kg | yes | no |
| 2 | SameDay | 200 kg | 31 kg | yes | no |
| 5 | DragonStar | 2000 kg | 2000 kg | yes | yes |
| 8 | PTT Express | 800 kg | 31 kg | yes | no |
| 12 | SameDay EasyBox | 30 kg | 20 kg | yes | no |
| 14 | PTT Express | 2000 kg | 2000 kg | yes | yes |
| 16 | SmartShip Delivery | 10000 kg | 10000 kg | yes | yes |
| 19 | FedEx | 200 kg | 68 kg | no | no |

## Common objects

### The sender / recipient objects

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | First and last name (or company name). At least two words. |
| `address` | string | yes | Full street address: street, number, details. |
| `email` | string | no | Email address. The recipient receives tracking notifications at this address. |
| `city` | integer | yes | The locality ID, obtained from [/geolocation/cities](https://smartship.ro/api-docs#geolocation-cities). Send the numeric ID, not the name. |
| `phone` | string | yes | Valid phone number (10 digits, Romanian format). |
| `country` | string | yes | Country code. For domestic shipments: `RO`. |
| `sector` | integer | no | Required only for Bucharest: the district (sector), value 1–6. For all other localities send 0. |

### The content object

| Field | Type | Required | Description |
|---|---|---|---|
| `package_content` | string | yes | Description of the parcel contents (printed on the AWB). |
| `parcels` | integer | yes | Number of parcels. For parcels with different dimensions use `parcels_multiple`. |
| `weight` | number | yes | Total weight in kg. Billing uses the greater of physical and volumetric weight (L×W×H / 6000 per parcel). |
| `cash_on_delivery` | number | no | Cash on delivery amount in RON. 0 = no COD. Note: some couriers (e.g. FedEx) do not support COD and will not be returned in estimates. |
| `length / width / height` | integer | yes | Parcel dimensions in cm. |
| `insurance` | number | no | Declared / insured value in RON. 0 = no insurance. |
| `iban` | string | no | IBAN for the COD payout. Required when `cash_on_delivery` > 0. The IBAN is validated on every request. |
| `open_package` | integer | no | 1 = the recipient may open the parcel on delivery (where the courier supports it). Default 0. **Not available for locker delivery** (there is no courier present to open the parcel): if you send `open_package: 1` together with `locker_id`, the option is ignored. |
| `order_id` | string | no | Your internal order ID. You can later look up the AWB by it via [/awb/order_id/{order_id}](https://smartship.ro/api-docs#awb-order-id). |
| `curier_preferat` | integer | no | Only for `/cost`: when set, the estimate is returned only for this courier (see the couriers table). 0 or missing = all couriers. |
| `parcels_multiple` | array | no | Multiple parcels with different dimensions: a list of `{"weight": 2, "length": 30, "width": 20, "height": 10}` objects. When present, it takes precedence over `parcels`/`weight`/the simple dimensions. |
| `dpd_shipment_note` | string | no | DPD only: extra note printed on the label. Max. 200 characters. |
| `locker_id` | integer | no | For delivery to a **SameDay easybox locker (courier 12)**: the locker ID, from [/geolocation/easybox](https://smartship.ro/api-docs#geolocation-easybox). Without `locker_id`, easybox is not returned in estimates and cannot be used for AWB creation. **When you send `locker_id`, `/cost` returns ONLY the locker option** (all other couriers deliver to an address, so they are not options for the same shipment; this rule also overrides `curier_preferat`). To compare home vs locker delivery, make two calls: one with `locker_id`, one without. If `locker_id` is not valid, the request fails with `612` — address delivery is not quoted as a fallback. The parcel is delivered to the locker, not to the recipient's address (max 30 kg). |
| `personal_drop_off` | integer | no | 1 = **personal drop-off**: you take the parcel to a SameDay easybox or pickup point yourself, no courier collects it from the sender address. Available only for **SameDay (2)** and **SameDay easybox (12)**. On `/cost`, with `personal_drop_off: 1` only these options are returned, priced for personal drop-off. Default 0. See [Locker delivery and personal drop-off](https://smartship.ro/api-docs#livrare-locker). |
| `swap` | integer | no | Only for `/awb/new`: 1 = **exchange parcel** (the courier delivers the parcel and collects another one back). The cost is doubled (outbound + return). Accepted by **PTT Express (14)** and **SmartShip Delivery (16)**. Couriers that do not support it reject the request with error `699`. Default 0. |
| `nocom` | integer | no | Only for `/awb/new`: 1 = do NOT automatically order the courier pickup (applies to FanCourier, DragonStar and PTT Express, where pickup is ordered automatically at creation). Useful if you already have a scheduled daily pickup. Default 0. |

## Locker delivery and personal drop-off

These are two independent options that can be combined: **locker delivery** (the recipient collects the parcel from a locker instead of receiving it at home) and **personal drop-off** (you, the sender, take the parcel to a SameDay easybox or pickup point instead of having a courier collect it).

**easybox delivery, in 3 steps:** 1) get the locker ID from [/geolocation/easybox](https://smartship.ro/api-docs#geolocation-easybox); 2) call [/cost](https://smartship.ro/api-docs#cost) with `content.locker_id` — the response contains only the `courier_id: 12` option; 3) create the AWB with [/awb/new](https://smartship.ro/api-docs#awb-new), using `courier_id: 12` and the same `content.locker_id`. The parcel goes to the locker (max 30 kg) and `open_package` is ignored. If you send cash on delivery, the locker must accept COD payment (otherwise error `6590`).

**Personal drop-off:** send `content.personal_drop_off: 1` on both `/cost` and `/awb/new`. It is available for **SameDay (2)** and **SameDay easybox (12)**, and the price is the personal drop-off price. No courier pickup is ordered: after the AWB is created, take the parcel with its AWB to a SameDay easybox or pickup point. With any other courier you get error `613`.

**Create AWB: personal drop-off + easybox delivery**

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

## Using the API with AI (ChatGPT, Claude, Cursor)

**To have an AI write the integration for you**, give it one of the formats below (generated automatically from the same source as this page, so always up to date): the [OpenAPI specification](https://smartship.ro/api-docs/openapi.json) (best for code generation), the [Markdown documentation](https://smartship.ro/api-docs/markdown?lang=en) (single language, no duplication) or the **“Copy for AI”** button at the top of the page. For your own contract there are [OpenAPI BYOC](https://smartship.ro/api-docs/openapi-byoc.json) and [Markdown BYOC](https://smartship.ro/api-docs/byoc/markdown?lang=en). The summary for AI models is at [/llms.txt](https://smartship.ro/llms.txt).

**AI connector (MCP), no code:** you can connect your SmartShip account directly to Claude, ChatGPT or any MCP-compatible app and work in plain language: “where is parcel X?”, “which parcels have problems?”, “how much is a 5 kg parcel to Cluj?”, “create an AWB for order 1234”, “cancel AWB Y”. The assistant can track parcels, look up orders, list shipments, compare rates (including parcels of different sizes, insurance, easybox and personal drop-off), show balance, invoices and payouts, find easybox lockers, download labels, and also **create AWBs, cancel AWBs not yet picked up and schedule FedEx pickups**.

**How to enable it:** in your SmartShip account, [Account settings → AI connector](https://smartship.ro/contul-meu/setari) → “Enable the AI connector”. You get a `https://mcp.smartship.ro/c/…` link that identifies your account, so treat it like a password (there you can regenerate it, disable it or switch it to read-only at any time). In Claude: Settings → Connectors → Add custom connector and paste the link. In Claude Code: `claude mcp add --transport http smartship https://mcp.smartship.ro/c/YOUR_LINK`. In other apps, add it as an HTTP MCP server (or via `npx mcp-remote` with the same URL).

**Safety:** creating, cancelling and pickup scheduling happen in two steps — the assistant first shows you a summary (sender, recipient, courier, cost) and acts only after you explicitly confirm in the chat. The sender can only be one of the senders saved in your account, COD is paid only into an IBAN of your account, the price is re-checked at confirmation, and an order that already has an active AWB does not get another one unless you explicitly ask.

## Endpoints

### POST /cost — Estimate delivery cost

Returns the delivery cost for every courier available for the given data, sorted by price ascending. Prices include your account discount and are expressed in RON, **VAT included** (the `cost` field). For convenience we also return `cost_fara_tva` (net of VAT). Each courier also includes `ramburs_delay` — the estimated time until the COD payout (`median` and `p75`, in days from delivery), computed from previous deliveries; `null` when we lack enough data. Couriers that cannot fulfil the request (weight, COD or route rules) are omitted from the response.

Body: the common `sender`, `recipient` and `content` objects (see “Common objects”).

**Example request**

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

**Example with multiple parcels of different dimensions (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
            }
        ]
    }
}
```

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `999` | Validation errors. The `erori` field lists the problems (incomplete name, invalid phone, missing locality, etc.). |
| `201` | Invalid IBAN (when `cash_on_delivery` > 0). |
| `612` | `curier_preferat = 12` (easybox) without a valid `locker_id`. |
| `613` | `personal_drop_off: 1` with a `curier_preferat` other than SameDay (2) or easybox (12). |
| `301` | Invalid API key. |

### POST /awb/new — Create AWB

Creates an AWB with the courier chosen via `courier_id`. The cost is calculated exactly like `/cost` and deducted from your account credit (or added to your invoice if you pay on terms). Recommended flow: call `/cost` first and pick the courier from the response.

Body: the common `sender`, `recipient` and `content` objects (see “Common objects”).

**Additional fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `courier_id` | integer | yes | The ID of the courier the AWB is created with — see the couriers table above. |

**Example request**

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

**Example with multiple parcels of different dimensions (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
            }
        ]
    }
}
```

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `601` | Invalid `courier_id` — not in the accepted courier list. |
| `602` | Courier not available at the moment. |
| `603` | No courier available for the given data. |
| `605` | Not enough credits. The response includes your available credit and the required cost. |
| `606` | The chosen courier does not support cash on delivery (e.g. FedEx). |
| `806` | easybox: missing or invalid `locker_id`. |
| `613` | `personal_drop_off: 1` with a `courier_id` other than SameDay (2) or easybox (12). |
| `6589` | easybox: the chosen locker is currently unavailable. |
| `6590` | easybox: the chosen locker does not support COD payment — choose another locker or remove cash on delivery. |
| `9855` | The cost could not be calculated for the chosen courier (check the data / route availability). |
| `999` | Validation errors — see the `erori` field. |
| `301` | The AWB was not created. The `err` field contains the courier's response (without the data we sent: `fields` for Cargus and `datasend` for SameDay no longer appear). |
| `5014, 5015, 5016, 50111` | DPD rejected the shipment. The response contains only `status` and `message`. |

### GET /awb/status/{awb} — AWB status & tracking

Returns the current status and tracking history for an AWB created through your account. Main statuses: 0 = created (not picked up), 1 = in transit, 2 = delivered, 5/6 = returned, 10 = cancelled.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `awb (path)` | string | yes | The AWB number. |

**Example request**

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

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `301` | The AWB does not exist or does not belong to your account. |

### GET /awb/order_id/{order_id} — AWB status by order_id

Same as [/awb/status](https://smartship.ro/api-docs#awb-status), but looks up the AWB by the `order_id` sent at creation — useful when your system does not store the AWB number.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `order_id (path)` | string | yes | The order ID sent in `content.order_id` at creation. |

**Example request**

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

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

Cancels an AWB created through your account. The cancellation is propagated to the courier and the cost is refunded to your account credit only once, and only after the courier confirms the cancellation. If the courier rejects it or does not respond, the AWB stays active and nothing is refunded. An AWB already picked up by the courier can no longer be cancelled.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `awb (path)` | string | yes | The AWB number. |

**Example request**

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

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `301` | The AWB does not exist or does not belong to your account. |
| `608` | The courier rejected the cancellation (e.g. the parcel was already picked up) or did not respond; the AWB stays active and nothing is refunded. The reason is in the `message` field (the response no longer contains the raw `res`, `res_dragon`, `err` fields). A DPD rejection also returns `608`, with the message "Expedierea nu se poate anula. Mesaj DPD: …" (it used to come with status `200`). |
| `205` | The AWB is already cancelled (applies to all couriers). The request is not sent to the courier again and the cost is not refunded a second time. |
| `206` | The shipment can no longer be cancelled (already picked up/delivered), including Cargus shipments that have already been collected. |
| `220` | Cancellation for this courier is not available via the API. Example: **PTT Express (14)**, which does not allow cancelling an issued AWB; the AWB stays active and the cost is not refunded (the `200` response with `warning: ptt_no_api_cancel` no longer exists). |

### GET /awb/print/{awb}/{format} — Download label (PDF)

Returns the AWB label as a print-ready PDF. The response is the PDF file itself (not JSON).

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `awb (path)` | string | yes | The AWB number. |
| `format (path)` | string | no | `A4` (default) or `A6` (compact label, for label printers). |

**Example request**

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

### GET /geolocation/counties — List counties

Returns the list of counties, with the IDs used for locality lookup.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `country (query)` | string | no | Country code. Default `RO`. |

**Example request**

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

**Example response**

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

### GET /geolocation/cities — List cities

Returns the localities in a county. The locality ID is what you send in the `city` field for sender/recipient. Recommendation: sync the list once a day, not on every request.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `county (query)` | integer | yes | The county ID, from [/geolocation/counties](https://smartship.ro/api-docs#geolocation-counties). |
| `loc_sel (query)` | string | no | Optional: a locality name; if found, the response also includes `city_selected` with its ID. |

**Example request**

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

**Example response**

```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 easybox lockers

Returns the list of easybox (Sameday) lockers available for delivery.

**Example request**

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

### GET /account/senders — Saved senders

Returns the senders saved in your account (pickup addresses). For a single sender: `/account/senders/{id}` — the response contains a `sender` object instead of the `senders` list.

**Example request**

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

**Example response**

```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 — Balance & credit limit

Returns your current account balance, credit limit and the amount available for shipping. Useful before `/awb/new` to avoid error 605 (not enough credits).

**Example request**

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

**Example response**

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

### GET /awbs — List shipments

Returns your shipments, paginated, with filters — for ERP reconciliation and sync. Statuses: 0 = created, 1 = in transit, 2 = delivered, 5 = refused, 6 = returned, 10 = cancelled.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `page (query)` | integer | no | Page number. Default 1. |
| `per_page (query)` | integer | no | Results per page. Default 50, max 100. |
| `status (query)` | integer | no | Filter by status (see list above). |
| `date_from / date_to (query)` | string | no | Date range, `YYYY-MM-DD` format. |
| `order_id (query)` | string | no | Filter by your order ID. |
| `q (query)` | string | no | Text search (minimum 2 characters) across AWB number, recipient name, recipient city and order ID. |
| `courier (query)` | integer | no | Filter by courier — the numeric ID returned in the `courier_id` field. |

**Example request**

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

**Example response**

```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} — FedEx pickup availability

For FedEx AWBs: returns the days and time intervals available for scheduling the parcel pickup from the sender. Use the returned values with [POST /pickup/{awb}](https://smartship.ro/api-docs#pickup-schedule).

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `awb (path)` | string | yes | The FedEx AWB number. |

**Example request**

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

**Example response**

```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} — Schedule FedEx pickup

Schedules the FedEx parcel pickup from the sender address, on the chosen day and interval (from [/pickup/availability](https://smartship.ro/api-docs#pickup-availability)). Max one pickup per AWB. The sender receives an email confirmation.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `awb (path)` | string | yes | The FedEx AWB number. |

**Additional fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `pickup_date` | string | yes | Pickup day, `YYYY-MM-DD` format. |
| `ready_time` | string | yes | Time from which the parcel is ready, `HH:MM` format. |
| `latest_time` | string | yes | Latest available time, `HH:MM` format. |

**Example request**

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

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `302` | The AWB is not a FedEx shipment. |
| `305` | A pickup is already scheduled for this AWB. |
| `998` | FedEx did not confirm — check the interval against /pickup/availability. |

### GET /invoices — Invoices

Returns the invoices issued to your account, paginated, with a public PDF link — for accounting reconciliation alongside [/payouts](https://smartship.ro/api-docs#payouts).

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `page (query)` | integer | no | Page number. Default 1. |
| `per_page (query)` | integer | no | Results per page. Default 50, max 100. |

**Example request**

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

**Example response**

```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 COD payouts

Returns the cash-on-delivery payouts transferred to your account, paginated. Each payout has a number, date, total value and destination IBAN.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `page (query)` | integer | no | Page number. Default 1. |
| `per_page (query)` | integer | no | Results per page. Default 50, max 100. |

**Example request**

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

**Example response**

```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} — Payout details

Returns the details of a payout: its component lines with the AWB, recipient and amount of each collected COD included.

**Parameters**

| Field | Type | Required | Description |
|---|---|---|---|
| `number (path)` | string | yes | The payout number, from [/payouts](https://smartship.ro/api-docs#payouts). E.g. `PN472375`. |

**Example request**

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

**Example response**

```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 — Request a transport offer (heavy freight)

For heavy/oversized freight (above the standard threshold), where ordinary couriers do not fit, you can request a dedicated transport offer. You send the shipment details + transport parameters and the SmartShip team returns an offer (price, carrier, term). Poll the status with `GET /transport-offer/{ref}` and accept/reject once the offer is ready. On acceptance a SmartShip Delivery AWB is created automatically and the offer price is deducted from your credit.

Body: the common `sender`, `recipient` and `content` objects (see “Common objects”).

**Additional fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `content.weight` | number | yes | Total weight (kg). |
| `content.parcels` | integer | no | Number of parcels/pallets. Default 1. |
| `content.length/width/height` | integer | no | Dimensions (cm). |
| `content.truck_type` | string | no | Desired truck type: `box, prelata, platforma, basculanta, cisterna, container, agabaritic, autotransportator, cap_tractor`. |
| `content.groupage / adr / temperature_controlled` | boolean | no | Accepts groupage / ADR goods / requires temperature control. |
| `content.budget` | number | no | Estimated budget (RON), a hint for the offer. |
| `content.pickup_deadline / delivery_deadline` | string | no | Desired pickup/delivery terms (free text). |
| `content.message` | string | no | Extra details for the team. |
| `content.client_reference` | string | no | Your internal reference (order code, etc.). Returned in `GET` and shown everywhere (panel, emails). |

**Example request**

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

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `999` | Validation errors (listed in `erori`). |
| `422` | Weight below the minimum threshold for a transport offer request (heavy freight). The `min_weight` field shows the threshold. Below it, use `/cost` + `/awb/new`. |
| `301` | Invalid API key. |

### GET /transport-offer/{ref} — Check the transport offer

Returns the request status and the offer (once ready). Poll it anytime to see whether the team returned an offer. `request_status`: `new, in_review, offered, accepted, rejected` (you rejected the offer), `declined` (SmartShip could not provide an option), `cancelled, expired, completed`. For `rejected`/`declined`, `resolution_message` holds the reason (if given). When `offer.acceptable = true`, you can accept.

**Example request**

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

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `404` | Request not found (or not yours). |

### POST /transport-offer/{ref}/accept — Accept the transport offer

Accepts the offer. A SmartShip Delivery AWB is created automatically and the **offer price** is deducted from your account credit (checked beforehand). Idempotent: calling again returns the same AWB. The response contains the AWB and the tracking link.

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `409` | No active offer to accept. |
| `410` | The offer has expired. |
| `601` | Not enough credit for the offer price. |

### POST /transport-offer/{ref}/reject — Reject the transport offer

Rejects the offer. You may optionally send a `reason` in the body.

**Additional fields**

| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | string | no | Reason for rejection (optional). |

**Example request**

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

**Example response**

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

**Error codes**

| Code | Meaning |
|---|---|
| `409` | The offer can no longer be rejected. |

---

Do you have a direct contract with a courier and want to ship on it through SmartShip? See the [own contract (BYOC) documentation](https://smartship.ro/api-docs/byoc). (https://smartship.ro/api-docs/byoc/markdown?lang=en)
