{
    "openapi": "3.1.0",
    "info": {
        "title": "SmartShip API — Own contract (BYOC)",
        "version": "2026-11-13",
        "description": "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).\n\n**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.\n\n**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)\n\n**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.\n\n**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.\n\n**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.",
        "contact": {
            "name": "SmartShip",
            "url": "https://smartship.ro/contact"
        }
    },
    "externalDocs": {
        "url": "https://smartship.ro/api-docs/byoc"
    },
    "servers": [
        {
            "url": "https://api.smartship.ro"
        }
    ],
    "security": [
        {
            "ApiKey": []
        }
    ],
    "paths": {
        "/cost": {
            "post": {
                "operationId": "cost",
                "summary": "Estimate delivery cost",
                "description": "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.\n\nError codes (the `status` field):\n- `999`: Validation errors. The `erori` field lists the problems (incomplete name, invalid phone, missing locality, etc.).\n- `201`: Invalid IBAN (when `cash_on_delivery` > 0).\n- `612`: `curier_preferat = 12` (easybox) without a valid `locker_id`.\n- `613`: `personal_drop_off: 1` with a `curier_preferat` other than SameDay (2) or easybox (12).\n- `301`: Invalid API key.",
                "tags": [
                    "cost"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderRecipient"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/SenderRecipient"
                                    },
                                    "content": {
                                        "$ref": "#/components/schemas/Content"
                                    },
                                    "show_byoc": {
                                        "type": "integer",
                                        "description": "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": {
                                        "type": "integer",
                                        "description": "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."
                                    }
                                },
                                "required": [
                                    "sender",
                                    "recipient",
                                    "content"
                                ]
                            },
                            "example": {
                                "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
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "999",
                        "description": "Validation errors. The `erori` field lists the problems (incomplete name, invalid phone, missing locality, etc.)."
                    },
                    {
                        "status": "201",
                        "description": "Invalid IBAN (when `cash_on_delivery` > 0)."
                    },
                    {
                        "status": "612",
                        "description": "`curier_preferat = 12` (easybox) without a valid `locker_id`."
                    },
                    {
                        "status": "613",
                        "description": "`personal_drop_off: 1` with a `curier_preferat` other than SameDay (2) or easybox (12)."
                    },
                    {
                        "status": "301",
                        "description": "Invalid API key."
                    }
                ]
            }
        },
        "/awb/new": {
            "post": {
                "operationId": "awbNew",
                "summary": "Create AWB",
                "description": "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.\n\nError codes (the `status` field):\n- `601`: Invalid `courier_id` — not in the accepted courier list.\n- `602`: Courier not available at the moment.\n- `603`: No courier available for the given data.\n- `605`: Not enough credits. The response includes your available credit and the required cost.\n- `606`: The chosen courier does not support cash on delivery (e.g. FedEx).\n- `806`: easybox: missing or invalid `locker_id`.\n- `613`: `personal_drop_off: 1` with a `courier_id` other than SameDay (2) or easybox (12).\n- `6589`: easybox: the chosen locker is currently unavailable.\n- `6590`: easybox: the chosen locker does not support COD payment — choose another locker or remove cash on delivery.\n- `9855`: The cost could not be calculated for the chosen courier (check the data / route availability).\n- `999`: Validation errors — see the `erori` field.\n- `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).\n- `5014, 5015, 5016, 50111`: DPD rejected the shipment. The response contains only `status` and `message`.\n- `4001`: The courier in `courier_id` is not available on own contract (see the list above).\n- `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).\n- `4003`: You have no connected contract for this courier — add it in Own Couriers.\n- `4004`: You sent `courier_id: 12` (easybox) on BYOC — use `courier_id: 2` + `locker_id`.\n- `4005`: `personal_drop_off: 1` is not available on BYOC.\n- `4030`: Insufficient balance for the BYOC fee (below the allowed limit) — top up your account.\n- `4050`: Komy (35) with cash on delivery — Komy does not accept COD.\n- `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.\n- `4043, 4044, 4045`: FANbox: invalid `locker_id` / over 30 kg / more than one parcel.",
                "tags": [
                    "awb"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderRecipient"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/SenderRecipient"
                                    },
                                    "content": {
                                        "$ref": "#/components/schemas/Content"
                                    },
                                    "courier_id": {
                                        "type": "integer",
                                        "description": "The ID of the courier the AWB is created with — see the couriers table above."
                                    },
                                    "use_own_contract": {
                                        "type": "integer",
                                        "description": "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."
                                    }
                                },
                                "required": [
                                    "sender",
                                    "recipient",
                                    "content",
                                    "courier_id"
                                ]
                            },
                            "example": {
                                "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"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "601",
                        "description": "Invalid `courier_id` — not in the accepted courier list."
                    },
                    {
                        "status": "602",
                        "description": "Courier not available at the moment."
                    },
                    {
                        "status": "603",
                        "description": "No courier available for the given data."
                    },
                    {
                        "status": "605",
                        "description": "Not enough credits. The response includes your available credit and the required cost."
                    },
                    {
                        "status": "606",
                        "description": "The chosen courier does not support cash on delivery (e.g. FedEx)."
                    },
                    {
                        "status": "806",
                        "description": "easybox: missing or invalid `locker_id`."
                    },
                    {
                        "status": "613",
                        "description": "`personal_drop_off: 1` with a `courier_id` other than SameDay (2) or easybox (12)."
                    },
                    {
                        "status": "6589",
                        "description": "easybox: the chosen locker is currently unavailable."
                    },
                    {
                        "status": "6590",
                        "description": "easybox: the chosen locker does not support COD payment — choose another locker or remove cash on delivery."
                    },
                    {
                        "status": "9855",
                        "description": "The cost could not be calculated for the chosen courier (check the data / route availability)."
                    },
                    {
                        "status": "999",
                        "description": "Validation errors — see the `erori` field."
                    },
                    {
                        "status": "301",
                        "description": "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)."
                    },
                    {
                        "status": "5014, 5015, 5016, 50111",
                        "description": "DPD rejected the shipment. The response contains only `status` and `message`."
                    },
                    {
                        "status": "4001",
                        "description": "The courier in `courier_id` is not available on own contract (see the list above)."
                    },
                    {
                        "status": "4002",
                        "description": "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)."
                    },
                    {
                        "status": "4003",
                        "description": "You have no connected contract for this courier — add it in Own Couriers."
                    },
                    {
                        "status": "4004",
                        "description": "You sent `courier_id: 12` (easybox) on BYOC — use `courier_id: 2` + `locker_id`."
                    },
                    {
                        "status": "4005",
                        "description": "`personal_drop_off: 1` is not available on BYOC."
                    },
                    {
                        "status": "4030",
                        "description": "Insufficient balance for the BYOC fee (below the allowed limit) — top up your account."
                    },
                    {
                        "status": "4050",
                        "description": "Komy (35) with cash on delivery — Komy does not accept COD."
                    },
                    {
                        "status": "4010–4014",
                        "description": "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."
                    },
                    {
                        "status": "4043, 4044, 4045",
                        "description": "FANbox: invalid `locker_id` / over 30 kg / more than one parcel."
                    }
                ]
            }
        },
        "/awb/status/{awb}": {
            "get": {
                "operationId": "awbStatus",
                "summary": "AWB status & tracking",
                "description": "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.\n\nError codes (the `status` field):\n- `301`: The AWB does not exist or does not belong to your account.",
                "tags": [
                    "awb"
                ],
                "parameters": [
                    {
                        "name": "awb",
                        "in": "path",
                        "required": true,
                        "description": "The AWB number.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "301",
                        "description": "The AWB does not exist or does not belong to your account."
                    }
                ]
            }
        },
        "/awb/order_id/{order_id}": {
            "get": {
                "operationId": "awbOrderId",
                "summary": "AWB status by order_id",
                "description": "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.",
                "tags": [
                    "awb"
                ],
                "parameters": [
                    {
                        "name": "order_id",
                        "in": "path",
                        "required": true,
                        "description": "The order ID sent in `content.order_id` at creation.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/awb/cancel/{awb}": {
            "get": {
                "operationId": "awbCancel",
                "summary": "Cancel AWB",
                "description": "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.\n\nError codes (the `status` field):\n- `301`: The AWB does not exist or does not belong to your account.\n- `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`).\n- `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.\n- `206`: The shipment can no longer be cancelled (already picked up/delivered), including Cargus shipments that have already been collected.\n- `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).",
                "tags": [
                    "awb"
                ],
                "parameters": [
                    {
                        "name": "awb",
                        "in": "path",
                        "required": true,
                        "description": "The AWB number.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "message": "AWB canceled.",
                                    "awb": "874156063265"
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "301",
                        "description": "The AWB does not exist or does not belong to your account."
                    },
                    {
                        "status": "608",
                        "description": "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`)."
                    },
                    {
                        "status": "205",
                        "description": "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."
                    },
                    {
                        "status": "206",
                        "description": "The shipment can no longer be cancelled (already picked up/delivered), including Cargus shipments that have already been collected."
                    },
                    {
                        "status": "220",
                        "description": "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)."
                    }
                ]
            }
        },
        "/awb/print/{awb}/{format}": {
            "get": {
                "operationId": "awbPrint",
                "summary": "Download label (PDF)",
                "description": "Returns the AWB label as a print-ready PDF. The response is the PDF file itself (not JSON).",
                "tags": [
                    "awb"
                ],
                "parameters": [
                    {
                        "name": "awb",
                        "in": "path",
                        "required": true,
                        "description": "The AWB number.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "format",
                        "in": "path",
                        "required": true,
                        "description": "`A4` (default) or `A6` (compact label, for label printers).",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/geolocation/counties": {
            "get": {
                "operationId": "geolocationCounties",
                "summary": "List counties",
                "description": "Returns the list of counties, with the IDs used for locality lookup.",
                "tags": [
                    "geolocation"
                ],
                "parameters": [
                    {
                        "name": "country",
                        "in": "query",
                        "required": false,
                        "description": "Country code. Default `RO`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "counties": [
                                        {
                                            "id": 1,
                                            "county": "Alba"
                                        },
                                        {
                                            "id": 2,
                                            "county": "Arad"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/geolocation/cities": {
            "get": {
                "operationId": "geolocationCities",
                "summary": "List cities",
                "description": "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.",
                "tags": [
                    "geolocation"
                ],
                "parameters": [
                    {
                        "name": "county",
                        "in": "query",
                        "required": true,
                        "description": "The county ID, from [/geolocation/counties](https://smartship.ro/api-docs#geolocation-counties).",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "loc_sel",
                        "in": "query",
                        "required": false,
                        "description": "Optional: a locality name; if found, the response also includes `city_selected` with its ID.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "county": {
                                        "id": 13,
                                        "name": "Cluj"
                                    },
                                    "city_selected": null,
                                    "cities": [
                                        {
                                            "id": 256212,
                                            "city": "Cluj-Napoca"
                                        },
                                        {
                                            "id": 256213,
                                            "city": "Apahida"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/geolocation/easybox": {
            "get": {
                "operationId": "geolocationEasybox",
                "summary": "List easybox lockers",
                "description": "Returns the list of easybox (Sameday) lockers available for delivery.",
                "tags": [
                    "geolocation"
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/geolocation/fanbox": {
            "get": {
                "operationId": "geolocationFanbox",
                "summary": "List FANbox lockers",
                "description": "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`).",
                "tags": [
                    "geolocation"
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/account/senders": {
            "get": {
                "operationId": "accountSenders",
                "summary": "Saved senders",
                "description": "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.",
                "tags": [
                    "account"
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/account/balance": {
            "get": {
                "operationId": "accountBalance",
                "summary": "Balance & credit limit",
                "description": "Returns your current account balance, credit limit and the amount available for shipping. Useful before `/awb/new` to avoid error 605 (not enough credits).",
                "tags": [
                    "account"
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "balance": -657.720000000000027284841053187847137451171875,
                                    "credit_limit": 10000,
                                    "payment_on_terms": 1,
                                    "available_for_shipping": 9342.280000000000654836185276508331298828125,
                                    "currency": "RON"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/awbs": {
            "get": {
                "operationId": "awbsList",
                "summary": "List shipments",
                "description": "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.",
                "tags": [
                    "awbs"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number. Default 1.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Results per page. Default 50, max 100.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "required": false,
                        "description": "Filter by status (see list above).",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "date_from",
                        "in": "query",
                        "required": false,
                        "description": "Date range, `YYYY-MM-DD` format.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "date_to",
                        "in": "query",
                        "required": false,
                        "description": "Date range, `YYYY-MM-DD` format.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "order_id",
                        "in": "query",
                        "required": false,
                        "description": "Filter by your order ID.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "q",
                        "in": "query",
                        "required": false,
                        "description": "Text search (minimum 2 characters) across AWB number, recipient name, recipient city and order ID.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "courier",
                        "in": "query",
                        "required": false,
                        "description": "Filter by courier — the numeric ID returned in the `courier_id` field.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/pickup/availability/{awb}": {
            "get": {
                "operationId": "pickupAvailability",
                "summary": "FedEx pickup availability",
                "description": "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).",
                "tags": [
                    "pickup"
                ],
                "parameters": [
                    {
                        "name": "awb",
                        "in": "path",
                        "required": true,
                        "description": "The FedEx AWB number.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                            ]
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/pickup/{awb}": {
            "post": {
                "operationId": "pickupSchedule",
                "summary": "Schedule FedEx pickup",
                "description": "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.\n\nError codes (the `status` field):\n- `302`: The AWB is not a FedEx shipment.\n- `305`: A pickup is already scheduled for this AWB.\n- `998`: FedEx did not confirm — check the interval against /pickup/availability.",
                "tags": [
                    "pickup"
                ],
                "parameters": [
                    {
                        "name": "awb",
                        "in": "path",
                        "required": true,
                        "description": "The FedEx AWB number.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "pickup_date": {
                                        "type": "string",
                                        "description": "Pickup day, `YYYY-MM-DD` format."
                                    },
                                    "ready_time": {
                                        "type": "string",
                                        "description": "Time from which the parcel is ready, `HH:MM` format."
                                    },
                                    "latest_time": {
                                        "type": "string",
                                        "description": "Latest available time, `HH:MM` format."
                                    }
                                },
                                "required": [
                                    "pickup_date",
                                    "ready_time",
                                    "latest_time"
                                ]
                            },
                            "example": {
                                "pickup_date": "2026-07-10",
                                "ready_time": "12:00",
                                "latest_time": "18:00"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "302",
                        "description": "The AWB is not a FedEx shipment."
                    },
                    {
                        "status": "305",
                        "description": "A pickup is already scheduled for this AWB."
                    },
                    {
                        "status": "998",
                        "description": "FedEx did not confirm — check the interval against /pickup/availability."
                    }
                ]
            }
        },
        "/invoices": {
            "get": {
                "operationId": "invoices",
                "summary": "Invoices",
                "description": "Returns the invoices issued to your account, paginated, with a public PDF link — for accounting reconciliation alongside [/payouts](https://smartship.ro/api-docs#payouts).",
                "tags": [
                    "invoices"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number. Default 1.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Results per page. Default 50, max 100.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payouts": {
            "get": {
                "operationId": "payouts",
                "summary": "List COD payouts",
                "description": "Returns the cash-on-delivery payouts transferred to your account, paginated. Each payout has a number, date, total value and destination IBAN.",
                "tags": [
                    "payouts"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "required": false,
                        "description": "Page number. Default 1.",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "required": false,
                        "description": "Results per page. Default 50, max 100.",
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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
                                        }
                                    ]
                                }
                            }
                        }
                    }
                }
            }
        },
        "/payouts/{number}": {
            "get": {
                "operationId": "payoutsDetail",
                "summary": "Payout details",
                "description": "Returns the details of a payout: its component lines with the AWB, recipient and amount of each collected COD included.",
                "tags": [
                    "payouts"
                ],
                "parameters": [
                    {
                        "name": "number",
                        "in": "path",
                        "required": true,
                        "description": "The payout number, from [/payouts](https://smartship.ro/api-docs#payouts). E.g. `PN472375`.",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/transport-offer": {
            "post": {
                "operationId": "transportOfferCreate",
                "summary": "Request a transport offer (heavy freight)",
                "description": "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.\n\nError codes (the `status` field):\n- `999`: Validation errors (listed in `erori`).\n- `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`.\n- `301`: Invalid API key.",
                "tags": [
                    "transport-offer"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "sender": {
                                        "$ref": "#/components/schemas/SenderRecipient"
                                    },
                                    "recipient": {
                                        "$ref": "#/components/schemas/SenderRecipient"
                                    },
                                    "content": {
                                        "allOf": [
                                            {
                                                "$ref": "#/components/schemas/Content"
                                            },
                                            {
                                                "type": "object",
                                                "properties": {
                                                    "weight": {
                                                        "type": "number",
                                                        "description": "Total weight (kg)."
                                                    },
                                                    "parcels": {
                                                        "type": "integer",
                                                        "description": "Number of parcels/pallets. Default 1."
                                                    },
                                                    "length": {
                                                        "type": "integer",
                                                        "description": "Dimensions (cm)."
                                                    },
                                                    "width": {
                                                        "type": "integer",
                                                        "description": "Dimensions (cm)."
                                                    },
                                                    "height": {
                                                        "type": "integer",
                                                        "description": "Dimensions (cm)."
                                                    },
                                                    "truck_type": {
                                                        "type": "string",
                                                        "description": "Desired truck type: `box, prelata, platforma, basculanta, cisterna, container, agabaritic, autotransportator, cap_tractor`."
                                                    },
                                                    "groupage": {
                                                        "type": "boolean",
                                                        "description": "Accepts groupage / ADR goods / requires temperature control."
                                                    },
                                                    "adr": {
                                                        "type": "boolean",
                                                        "description": "Accepts groupage / ADR goods / requires temperature control."
                                                    },
                                                    "temperature_controlled": {
                                                        "type": "boolean",
                                                        "description": "Accepts groupage / ADR goods / requires temperature control."
                                                    },
                                                    "budget": {
                                                        "type": "number",
                                                        "description": "Estimated budget (RON), a hint for the offer."
                                                    },
                                                    "pickup_deadline": {
                                                        "type": "string",
                                                        "description": "Desired pickup/delivery terms (free text)."
                                                    },
                                                    "delivery_deadline": {
                                                        "type": "string",
                                                        "description": "Desired pickup/delivery terms (free text)."
                                                    },
                                                    "message": {
                                                        "type": "string",
                                                        "description": "Extra details for the team."
                                                    },
                                                    "client_reference": {
                                                        "type": "string",
                                                        "description": "Your internal reference (order code, etc.). Returned in `GET` and shown everywhere (panel, emails)."
                                                    }
                                                }
                                            }
                                        ]
                                    }
                                },
                                "required": [
                                    "sender",
                                    "recipient",
                                    "content"
                                ]
                            },
                            "example": {
                                "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"
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "message": "Solicitare înregistrată.",
                                    "ref": "OFT-2026-00123",
                                    "request_status": "new"
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "999",
                        "description": "Validation errors (listed in `erori`)."
                    },
                    {
                        "status": "422",
                        "description": "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`."
                    },
                    {
                        "status": "301",
                        "description": "Invalid API key."
                    }
                ]
            }
        },
        "/transport-offer/{ref}": {
            "get": {
                "operationId": "transportOfferGet",
                "summary": "Check the transport offer",
                "description": "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.\n\nError codes (the `status` field):\n- `404`: Request not found (or not yours).",
                "tags": [
                    "transport-offer"
                ],
                "parameters": [
                    {
                        "name": "ref",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "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
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "404",
                        "description": "Request not found (or not yours)."
                    }
                ]
            }
        },
        "/transport-offer/{ref}/accept": {
            "post": {
                "operationId": "transportOfferAccept",
                "summary": "Accept the transport offer",
                "description": "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.\n\nError codes (the `status` field):\n- `409`: No active offer to accept.\n- `410`: The offer has expired.\n- `601`: Not enough credit for the offer price.",
                "tags": [
                    "transport-offer"
                ],
                "parameters": [
                    {
                        "name": "ref",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "message": "Ofertă acceptată. AWB emis.",
                                    "awb": "SMA3170895",
                                    "tracking_url": "https://smartship.ro/t/aB3xK9mQw2",
                                    "cost": 1500
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "409",
                        "description": "No active offer to accept."
                    },
                    {
                        "status": "410",
                        "description": "The offer has expired."
                    },
                    {
                        "status": "601",
                        "description": "Not enough credit for the offer price."
                    }
                ]
            }
        },
        "/transport-offer/{ref}/reject": {
            "post": {
                "operationId": "transportOfferReject",
                "summary": "Reject the transport offer",
                "description": "Rejects the offer. You may optionally send a `reason` in the body.\n\nError codes (the `status` field):\n- `409`: The offer can no longer be rejected.",
                "tags": [
                    "transport-offer"
                ],
                "parameters": [
                    {
                        "name": "ref",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "reason": {
                                        "type": "string",
                                        "description": "Reason for rejection (optional)."
                                    }
                                }
                            },
                            "example": {
                                "reason": "Am găsit o variantă mai avantajoasă."
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "JSON response. Check `status`: 200 = success.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Response"
                                },
                                "example": {
                                    "status": 200,
                                    "message": "Ofertă refuzată."
                                }
                            }
                        }
                    }
                },
                "x-error-codes": [
                    {
                        "status": "409",
                        "description": "The offer can no longer be rejected."
                    }
                ]
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKey": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-KEY",
                "description": "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)."
            }
        },
        "schemas": {
            "SenderRecipient": {
                "type": "object",
                "description": "The sender / recipient objects",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "First and last name (or company name). At least two words."
                    },
                    "address": {
                        "type": "string",
                        "description": "Full street address: street, number, details."
                    },
                    "email": {
                        "type": "string",
                        "description": "Email address. The recipient receives tracking notifications at this address."
                    },
                    "city": {
                        "type": "integer",
                        "description": "The locality ID, obtained from [/geolocation/cities](https://smartship.ro/api-docs#geolocation-cities). Send the numeric ID, not the name."
                    },
                    "phone": {
                        "type": "string",
                        "description": "Valid phone number (10 digits, Romanian format)."
                    },
                    "country": {
                        "type": "string",
                        "description": "Country code. For domestic shipments: `RO`."
                    },
                    "sector": {
                        "type": "integer",
                        "description": "Required only for Bucharest: the district (sector), value 1–6. For all other localities send 0."
                    }
                },
                "required": [
                    "name",
                    "address",
                    "city",
                    "phone",
                    "country"
                ]
            },
            "Content": {
                "type": "object",
                "description": "The content object",
                "properties": {
                    "package_content": {
                        "type": "string",
                        "description": "Description of the parcel contents (printed on the AWB)."
                    },
                    "parcels": {
                        "type": "integer",
                        "description": "Number of parcels. For parcels with different dimensions use `parcels_multiple`."
                    },
                    "weight": {
                        "type": "number",
                        "description": "Total weight in kg. Billing uses the greater of physical and volumetric weight (L×W×H / 6000 per parcel)."
                    },
                    "cash_on_delivery": {
                        "type": "number",
                        "description": "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": {
                        "type": "integer",
                        "description": "Parcel dimensions in cm."
                    },
                    "width": {
                        "type": "integer",
                        "description": "Parcel dimensions in cm."
                    },
                    "height": {
                        "type": "integer",
                        "description": "Parcel dimensions in cm."
                    },
                    "insurance": {
                        "type": "number",
                        "description": "Declared / insured value in RON. 0 = no insurance."
                    },
                    "iban": {
                        "type": "string",
                        "description": "IBAN for the COD payout. Required when `cash_on_delivery` > 0. The IBAN is validated on every request."
                    },
                    "open_package": {
                        "type": "integer",
                        "description": "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": {
                        "type": "string",
                        "description": "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": {
                        "type": "integer",
                        "description": "Only for `/cost`: when set, the estimate is returned only for this courier (see the couriers table). 0 or missing = all couriers."
                    },
                    "parcels_multiple": {
                        "type": "array",
                        "description": "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.",
                        "items": {
                            "type": "object"
                        }
                    },
                    "dpd_shipment_note": {
                        "type": "string",
                        "description": "DPD only: extra note printed on the label. Max. 200 characters."
                    },
                    "locker_id": {
                        "type": "integer",
                        "description": "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": {
                        "type": "integer",
                        "description": "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": {
                        "type": "integer",
                        "description": "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": {
                        "type": "integer",
                        "description": "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."
                    }
                },
                "required": [
                    "package_content",
                    "parcels",
                    "weight",
                    "length",
                    "width",
                    "height"
                ]
            },
            "Response": {
                "type": "object",
                "description": "Every response has `status`: 200 = success, anything else is an error explained in `message`.",
                "properties": {
                    "status": {
                        "type": "integer"
                    },
                    "message": {
                        "type": "string"
                    },
                    "erori": {
                        "type": "array",
                        "items": {
                            "type": "object"
                        },
                        "description": "Only for error 999: the list of validation problems."
                    }
                },
                "required": [
                    "status"
                ],
                "additionalProperties": true
            }
        }
    }
}