# 📦 Balíkobot API #### One integration. **many carriers.** Create shipments, print labels, order pickups and track parcels across Czechia, Slovakia and Europe — all through a single, consistent REST API. > #### 👋 New here? Start in three steps > > 1. Grab your **Test** API key and Login from your Balíkobot client zone. > 2. Call `/info/whoami` to confirm your credentials and see which carriers are active. > 3. Create your first shipment with a carrier `/{carrier}/add` endpoint, then print the label. Balíkobot is a logistics gateway that hides the complexity of every carrier behind one uniform HTTP interface. Instead of building and maintaining a separate integration for Česká pošta, DPD, PPL, GLS, Zásilkovna, DHL, UPS, FedEx and dozens more, you talk to **one** API and Balíkobot does the carrier-specific work for you. --- ## Why Balíkobot Add a package for any carrier using the same request shape — only the endpoint slug and a few carrier-specific attributes change. Switch or add carriers without rewriting your integration. Test API keys behave exactly like production. Depending on the carrier, requests return mock data or hit the carrier's real test environment — so you can validate your flow end to end before going live. Create shipments, generate labels, order pickups (order pickup / B2A / B2C), fetch proof of delivery and get transport-cost estimates — all covered by the API. Unified tracking statuses across all carriers mean you write your delivery-state logic once. No more mapping 40 different carrier status vocabularies. --- ## Base URL & Protocol All communication uses resource-oriented URLs over HTTPS. The production base URL is: ``` https://apiv2.balikobot.cz ``` > #### ⚠️ HTTPS only, 30-second timeout > > - All requests **must** use HTTPS. Plain HTTP requests receive no response. > - Every method responds within **30 seconds**; otherwise you get a `504 Gateway Timeout`. --- ## Authentication The API uses **HTTP Basic Auth**. Use your API **Login** as the username and your API **Key** as the password, and send this header with every request. The fastest way to verify your credentials is the `whoami` endpoint — it returns your sender data, whether your keys are test or production, and the carriers active for your account. ```json http { "method": "get", "url": "https://apiv2.balikobot.cz/info/whoami", "headers": { "Authorization": "Basic " } } ``` > #### 🚀 Going to production > > Once your configuration is finalized in the client zone (carrier forms, store management), simply swap your **Test** API key for your **Production** key. No code changes required. --- ## Your First Shipment Every carrier exposes an `/{carrier}/add` endpoint that accepts the same base request structure. The example below creates a package with DPD. ```bash curl -X POST 'https://apiv2.balikobot.cz/dpd/add' \ -u 'YOUR_LOGIN:YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "packages": [ { "eid": "order-2026-0001", "service_type": "1", "rec_name": "Jan Novak", "rec_street": "Korunni 123", "rec_city": "Praha", "rec_zip": "12000", "rec_country": "CZ", "rec_email": "jan.novak@example.com" } ] }' ``` ```php [[ 'eid' => 'order-2026-0001', 'service_type' => '1', 'rec_name' => 'Jan Novak', 'rec_street' => 'Korunni 123', 'rec_city' => 'Praha', 'rec_zip' => '12000', 'rec_country' => 'CZ', 'rec_email' => 'jan.novak@example.com', ]], ]; $ch = curl_init('https://apiv2.balikobot.cz/dpd/add'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_USERPWD => 'YOUR_LOGIN:YOUR_API_KEY', CURLOPT_HTTPHEADER => ['Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_RETURNTRANSFER => true, ]); $response = json_decode(curl_exec($ch), true); ``` ```json http { "method": "post", "url": "https://apiv2.balikobot.cz/dpd/add", "headers": { "Content-Type": "application/json" }, "body": { "packages": [ { "eid": "order-2026-0002", "order_number": 1, "service_type": "1", "weight": 5.0, "price": 1500, "rec_name": "Jan Novak", "rec_street": "Korunni 123", "rec_city": "Praha", "rec_zip": "12000", "rec_country": "CZ" } ] } } ``` A successful `add` returns a package/carrier ID and a label URL you can print. From there you can order a pickup and start tracking. --- ## Multi-piece Shipments Need to send several packages to **one recipient as a single shipment**? Group them with a shared **`eid`** and number the pieces with **`order_number`**: - All pieces share the **same `eid`**. - **`order_number`** is the piece sequence, from `1` to `127`. The **main package must be `order_number = 1`**; further pieces are `2`, `3`, … Each piece must be added in order — piece 1 has to exist before piece 2. - Where do price and cod_price go? This depends on the carrier: - Totals on the main record — most grouped-consignment carriers expect the total price and total cod_price on the main package (order_number = 1) only. - Split across pieces — some carriers (e.g. DHL DE) require the amount divided across individual pieces: state each piece's own price / cod_price on its own order_number. - Always check the carrier's page in the documentation before relying on either behaviour. - A grouped shipment must use **one `service_type`** for all pieces. - Send **all pieces in a single request** (as multiple objects in the `packages` array). Some carriers *require* this and reject pieces split across requests. ```json http { "method": "post", "url": "https://apiv2.balikobot.cz/dpd/add", "headers": { "Content-Type": "application/json" }, "body": { "packages": [ { "eid": "order-2026-0002", "order_number": 1, "service_type": "1", "weight": 5.0, "price": 1500, "rec_name": "Jan Novak", "rec_street": "Korunni 123", "rec_city": "Praha", "rec_zip": "12000", "rec_country": "CZ" }, { "eid": "order-2026-0002", "order_number": 2, "service_type": "1", "weight": 8.0, "rec_name": "Jan Novak", "rec_street": "Korunni 123", "rec_city": "Praha", "rec_zip": "12000", "rec_country": "CZ" } ] } } ``` > #### 📦 Ordering & cancelling a multi-piece shipment > > - When ordering transport (`order`), always send **all `package_id`s that share an `eid`** in the same request — otherwise the data will be inconsistent with the carrier and the shipment may not be delivered. > - When cancelling (`drop`), remove pieces **from the last one first** — you cannot delete a piece that is not the last remaining part of the shipment. > #### 🚚 Support varies by carrier > > Not every carrier supports multi-piece shipments, and pallet/cargo carriers use `eid` + `order_number` together with `mu_type` (manipulation-unit type) and `pieces_count`. Check the carrier's page in the documentation for its exact rules. --- ## The Shipment Lifecycle Every integration follows the same handful of methods, regardless of carrier. Start with the **skeleton flow** — that's all most integrations ever need. Reach for the **full flow** when you want pickup points, dangerous-goods units, service validation or explicit label control. The happy path — four methods cover the whole journey from order to delivery. ``` add → order → track ( drop = cancel ) ``` 1. **`/{carrier}/add`** — create the package(s). `packages` is always an array, so you can batch. Returns a package/carrier ID **and** a label URL. 2. **`/{carrier}/drop`** *(optional)* — cancel a package you added by mistake, before it has been ordered. 3. **`/{carrier}/order`** — hand the created package(s) over to the carrier (order transport / collection). 4. **`/{carrier}/track`** — follow the shipment through the [unified tracking statuses](#tracking-statuses) until it's delivered. The complete picture. Preparatory methods are **read-only lookups** you call *before* `add` to build a valid request; labels are optional because `add` already returns a label URL. **① Preparation (optional, read-only)** - **`/info/whoami`** — verify keys and list active carriers - **`/{carrier}/branches`** · **`/{carrier}/fullbranches`** — pickup points / parcel boxes for branch & box delivery - **`/{carrier}/services`** · **`/{carrier}/activatedservices`** — available services and allowed attributes - **`/{carrier}/adrunits`** — ADR (dangerous-goods) unit codes - **`/{carrier}/manipulationunits`** · **`/{carrier}/countries4service`** · **`/{carrier}/zipcodes`** — further lookups **② Core sequence** 1. **`/{carrier}/add`** — create the package(s). 2. **`/{carrier}/drop`** *(optional)* — cancel a package before it's ordered. 3. **`/{carrier}/labels`** *(optional)* — (re)generate label(s); `add` already returns a label URL. 4. **`/{carrier}/order`** — order transport / collection. Cargo & pallet carriers use **`b2a`** / **`b2c`** instead. 5. **`/{carrier}/track`** (full history) or **`/{carrier}/trackstatus`** (latest status only) — monitor delivery. 6. **`/{carrier}/pod`** — retrieve proof of delivery once delivered. > #### 🗂️ Multiple API profiles > > You may need several API access profiles for: contracts with carriers in different countries, multiple shipping locations, multiple accounts or contracts with one carrier, or different label variations. --- ## Supported Carriers Call `/info/carriers` at any time for the live list, including each carrier's name, slug and `add` endpoint. --- ## Data Format Standards The following standards are used consistently throughout the API: | Standard | Format | Examples | Used in fields | |---|---|---|---| | **Country codes** — [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) | Two-letter uppercase | `CZ`, `SK`, `DE`, `PL` | `rec_country`, `content_country` | | **Currency codes** — [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) | Three-letter uppercase | `CZK`, `EUR`, `PLN` | `cod_currency`, `ins_currency` | > #### 🔎 Look up a code > > - **Country codes** — search the official [ISO Online Browsing Platform (OBP)](https://www.iso.org/obp/ui/#search/code/). > - **Currency codes** — see the [ISO 4217 currency code list](https://www.iso.org/iso-4217-currency-codes.html). --- ## Status Codes All methods return the same error shape: ```json { "status": 400, "message": "..." } ``` | Status | Meaning | | |--------|---------|---| | 200 | OK — the operation was successful. | 🟢 | | 208 | An item with this ID already exists. The returned data belongs to the original record. | 🟢 | | 400 | The operation was not successful; please check the specific data. | 🔴 | | 401 | Authentication failed or API key is missing. | 🔴 | | 403 | The carrier is not activated for the keys being used. | 🔴 | | 404 | The shipment does not exist or has already been processed. | 🔴 | | 405 | The package with the given ID has already been sent for collection. | 🟡 | | 406 | No data was processed or the data cannot be accepted. | 🔴 | | 409 | Conflict with the carrier's configuration or received data (e.g. two mutually exclusive attributes). | 🔴 | | 413 | The data format is invalid. | 🔴 | | 423 | This feature is only available for Production API keys. | 🔴 | | 426 | Too many requests; the carrier's call limit has been exceeded. | 🟡 | | 501 | The carrier's technology has not been implemented yet. | 🔴 | | 503 | The carrier's technology is temporarily unavailable; the request will be processed later. | 🟡 | --- ## Tracking Statuses Balíkobot normalizes every carrier's tracking vocabulary into a single set of statuses. **V2** is the current, granular model; **V1** remains for backward compatibility. | Status | Meaning | | |--------|---------|---| | -1 | The shipment has not yet been handed over to the carrier. | ⚫ | | 0.1 | Error on the carrier's side. | 🔴 | | 0.2 | Error on the recipient's side. | 🔴 | | 0.3 | Error on the sender's side. | 🔴 | | 1.1 | The shipment has been picked up. | 🟢 | | 1.2 | The shipment has been delivered to the recipient. | 🟢 | | 2.1 | The shipment has been accepted for transport. | 🟡 | | 2.2 | The shipment is in transit. | 🟡 | | 2.3 | The shipment is ready for pickup. | 🟡 | | 2.4 | The shipment is on its way back to the sender. | 🟠 | | 2.5 | The shipment has been handed to the final carrier. | 🟡 | | 3.1 | Cancelled by the carrier. | 🔴 | | 3.2 | Cancelled by the recipient. | 🔴 | | 3.3 | Cancelled by the sender. | 🔴 | | 4 | The shipment has been returned to the sender. | 🟠 | | 5 | The cash-on-delivery amount has been credited to the sender's account. | 🟢 | | Status | Meaning | | |--------|---------|---| | -1 | The shipment has not yet been handed over to the carrier. | ⚫ | | 0 | The shipment was not delivered — refused by the recipient or a carrier error. | 🔴 | | 1 | The shipment has been delivered to the recipient. | 🟢 | | 2 | The shipment is being delivered / ready for pickup. | 🟡 | | 3 | The shipment has been cancelled. | 🔴 | | 4 | The shipment has been returned to the sender. | 🟠 | --- ## Where to Go Next Browse every endpoint, request and response schema in the API reference — the full **Balíkobot API v2.0.0** OpenAPI documentation collection. Carrier-specific attributes, service types and label handling to guide your integration end to end. [Open the Balíkobot API Integration Manual V2 →](https://heurekagroup.atlassian.net/wiki/spaces/BBD/pages/8326840336/Balikobot+API+Integration+Manual+V2) New carriers, methods, attributes and breaking changes as they ship — a readable summary you can mirror into your own release notes. [Open the BB API Changelog →](https://heurekagroup.atlassian.net/wiki/spaces/BBD/pages/8279326780/BB+API+CHANGELOG) Import the *Balíkobot – API methods* collection to fire requests against the test environment right away. --- > #### 💬 We're here to help > > If your e-commerce platform is a Balíkobot partner, contact us for your client-zone access. Not a partner yet? Reach out — we'll get you set up.