Conformance with the BOX NOW documents
Part of the BOX NOW Lockers documentation. Previous: Developer notes.
Sources (public, checked 2026-11-08): “API Integration manual BOX NOW - EN” (Partner API, boxnow.bg/media/PDF, cover version 1.65, file v1.69), “Webhook Based Parcel Tracking Guide” v1.4 (boxnow.bg/media/PDF), the BOX NOW map widget client script widget-cdn.boxnow.<country>/map-widget/client/v5.js. The developer portal dev.boxnow.gr requires a login and was not used.
| Document rule | Add-on |
|---|---|
OAuth 2.0 client credentials, POST /api/v1/auth-sessions JSON, Bearer token, expires_in 3600 (4.1) |
Api::token(); token cached encrypted until 60 s before expiry; one new login on 401. |
| Stage and Production environments (2) | Separate credentials per environment, mode switch. |
Origins GET /origins with locationType warehouse / any-apm (4.2) |
Test connection lists warehouses; origin id or any-apm. |
Destinations / location list locationapi-* “for better performance” (4.3, 4.3.1) |
Daily copy of the locker list; server check of the chosen id; built-in list. |
| Max parcel 60 x 45 x 36 cm, 20 kg; “implement filtering of shipping methods” (4.3) | Method hidden over 20 kg or for boxes that do not fit. |
POST /delivery-requests fields (4.4, 7.3.1); weight unknown = 1 |
Payload with only documented fields; unit tests and mock check them. |
| Item ids are eShop unique ids; parcels ids are BOX NOW’s (4.4) | Item id <orderNumber>-<n>; parcel ids stored per parcel. |
| P410 order number conflict (3) | Stable order number written before the call; P410 = adopt through GET /parcels?orderNumber=. |
| P405 international phone, P406 size for AnyAPM, P408 COD range (0, 5000), P411 COD not allowed (3) | Checked before sending; refusals shown with the code. |
Only allowReturn can be modified (4.5, 7.3.5) |
“Allow / Do not allow returns” per delivery. |
GET /parcels states and events (4.6) |
Polling as a safety net; events mapped to states. |
Labels /parcels/{id}/label.{pdf,zpl}, dpi 200/300, all labels /delivery-requests/{orderNumber}/label.{type} (5.0, 7.4) |
PDF or ZPL; one or all parcels. |
POST /parcels/{id}:cancel, cancelling a cancelled parcel has no effect, P420 (7.5.2) |
Cancel per parcel; refusals reported. |
POST /delivery-requests:customerReturns (7.3.3), P412 |
Customer return with the return location; label from the answer. |
X-PartnerID for multi-partner accounts, P440 / P441, GET /entrusted-partners (3, 7.6) |
Optional partner id field; P440 hint. |
Widget: script, _bn_map_widget_config, parentElement, afterSelect with boxnowLockerId; widget talks to Production only (6.1) |
Official script of the account’s country; Stage uses the list. |
Webhook: CloudEvents, one URL per partner, rely on event, use data.time to discard older updates, retries until 200 (guide) |
Keyed URL per account, idempotent by event id, ordered by data.time, never backwards, 200 at once. |
| Tracking page | https://t.boxnow.<country>/?track=<parcel id> (the link of the official BOX NOW plugins). |