Postman Collection for API NovaPost v.1.0 methods
\nRegistration:
\nEmail servicedesk@novapost.com to register a user for the API.
\nDuring the registration process, you will receive an API access key.
\nAuthentication:
\nSet provided API key as a value in Collection Variables .
\nExecuting \"Generate a temporary JWT-token\" request will generate and set your JWT token as a Collection Variable .
\nJWT Token will have a lifetime of 1 hour and further will need a refresh by running the \"Generate a temporary JWT-token\" request again.
\nJWT-token needs to be used for each API request, this collection was configured to use Collection Variable .
\nEndpoint Definition:
\nhttps://api.novapost.com/v.1.0 - Production environment
\nhttps://api-stage.novapost.pl/v.1.0 - Test environment
\nOverview:
The Nova Post API uses secure authentication mechanisms to protect API access and ensure data integrity. To interact with the API, you must generate a JWT (JSON Web Token) using your API key.
Purpose:
Authorization ensures that only authorized users or applications can access the Nova Post API endpoints. JWT tokens enable stateless authentication, allowing users to make secure API calls without needing repeated reauthentication.
Response:
\nOn success, the server returns a JWT token with a limited lifespan.
\nThe token must be included in the Authorization header (as a Bearer token) for subsequent requests (will be done automatically within current collection using collection variables if request was successful).
Sample Response:
\n{\n\"jwt\": \"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...\"\n} \n\nKey Notes:
\nTokens are temporary and will expire wthin 1 hour after generation.
\nRotate or refresh tokens as needed using the same API key by re running current request.
\nAlways store tokens securely to prevent unauthorized access.
\nYour unique API key obtained from servicedesk@novapost.com
\n","type":"text/plain"},"key":"apiKey","value":""}],"variable":[]}},"response":[{"id":"492f5fc5-e49d-49ad-b554-587f2c0b2588","name":"Generate a temporary JWT-token","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/clients/authorization?apiKey=","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","clients","authorization"],"query":[{"key":"apiKey","value":"","description":"Your unique API key obtained from servicedesk@novapost.com"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 15 Jan 2025 08:26:32 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"jwt\": \"{{vault:json-web-token}}\"\n}"}],"_postman_id":"211477b3-4f61-42f7-865a-39fbc0b5293a"}],"id":"bafeaae5-863c-4a43-8ff9-4829846bd7b6","description":"GET /clients/authorization
\n\n\nThis collection was configured using variables for apiKey and jwt token.
\n
Once API key is inserted in to Collection Variables (variable apiKey, example value: fa89b64e2a9248cbbc3124e678d88ab2 ) - request in current folder needs to be executed first. All further requests will have jwt token added automatically.
This API method allows you to generate a temporary JSON Web Token (JWT) that will be stored in collection variables and will be automatically added to every subsequent request to ensure proper authentication and authorization.
\nTo utilize this method, a personal API key is required. The request for generating a temporary JWT-token should contain your API key as an authentication parameter. Upon a successful request, the response will include the temporary JWT-token, which must be securely stored and included in the header or authentication section of all subsequent requests to access API resources properly. If you need to acquire a personal API key, please contact your manager for assistance.
\n","_postman_id":"bafeaae5-863c-4a43-8ff9-4829846bd7b6","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}}},{"name":"Dictionaries","item":[{"name":"Find divisions","id":"3816a62d-d2ed-4c3e-9992-b1ef6e773196","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":"https://api-stage.novapost.pl/v.1.0/divisions?limit=5&page=1&countryCodes[]=PL","description":"This API method enables you to obtain a list of own and partner`s cargo warehouses (divisions) and parcel lockers available within countries. By providing the country code as a parameter, you can retrieve a comprehensive list of cargo warehouses and related details. The response will typically include information like warehouse name, number, address, ID, country and city details, warehouse type, and other relevant attributes. This data can be useful to generate a transportation document (shipment).
\nResponse:
On success, the API returns paginated results with information about each division, including its attributes and operational details.
Example Response:
\njsonCopy code{\n \"current_page\": 1,\n \"last_page\": 34182,\n \"per_page\": 1,\n \"total\": 34182,\n \"items\": [\n {\n \"id\": 4434,\n \"name\": \"Пункт приймання-видачі (до 30 кг): вул. Полтавська, 2\",\n \"shortName\": \"Пункт приймання-видачі (до 30 кг)\",\n \"externalId\": \"1b460dd4-1ae1-11ed-9eb1-d4f5ef0df2b8\",\n \"countryCode\": \"UA\",\n \"settlement\": {\n \"id\": 125034,\n \"name\": \"village Novoselivka\",\n \"region\": {\n \"id\": 933,\n \"name\": \"Krasnohradskyi raion\",\n \"parent\": {\n \"id\": 416,\n \"name\": \"Kharkivska oblast\"\n }\n }\n },\n \"address\": \"63336, Україна, Харківська, Берестинський, село Новоселівка, вул. Полтавська, 2\",\n \"status\": \"Working\",\n \"divisionCategory\": \"PostBranch\",\n \"publicPhones\": [\"380800500609\"],\n \"latitude\": 49.286726,\n \"longitude\": 35.130241,\n \"maxWeightPlaceSender\": 30000,\n \"maxWeightPlaceRecipient\": 30000,\n \"workSchedule\": [\n {\n \"day\": \"sunday\",\n \"from\": \"08:00\",\n \"to\": \"19:00\"\n },\n {\n \"day\": \"monday\",\n \"from\": \"08:00\",\n \"to\": \"19:00\"\n }\n ],\n \"createdAt\": \"2022-10-01T16:43:46.000000Z\"\n }\n ]\n}\n\nMax number of items to return.
\n","type":"text/plain"},"key":"limit","value":"5"},{"description":{"content":"Page number to return.
\n","type":"text/plain"},"key":"page","value":"1"},{"description":{"content":"To receive a list of cargo warehouses and parcel lockers in a certain country please choose required country code from the list. Use code, according to the ISO 3166-1 Alpha-2 standard.\nAllowed: CZ ┃ DE ┃ EE ┃ HU ┃ LT ┃ LV ┃ MD ┃ PL ┃ RO ┃ SK ┃ UA
\n","type":"text/plain"},"key":"countryCodes[]","value":"PL"},{"disabled":true,"key":"latitude","value":"52.1756469282"},{"disabled":true,"key":"longitude","value":"20.934042527"},{"disabled":true,"key":"divisionCategories[]","value":"PostBranch"},{"disabled":true,"key":"prohibitedSending","value":"false"},{"disabled":true,"key":"prohibitedIssuance","value":"false"},{"disabled":true,"key":"statuses[]","value":"Working"},{"disabled":true,"key":"settlementIds[]","value":""}],"variable":[]}},"response":[{"id":"a906b0da-c577-40ca-93bb-809c2a3b6274","name":"Find divisions","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"}],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/divisions?limit=5&page=1&countryCodes[]=PL","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","divisions"],"query":[{"key":"limit","value":"5","description":"Max number of items to return."},{"key":"page","value":"1","description":"Page number to return."},{"key":"countryCodes[]","value":"PL","description":"To receive a list of cargo warehouses and parcel lockers in a certain country please choose required country code from the list. Use code, according to the ISO 3166-1 Alpha-2 standard.\nAllowed: CZ ┃ DE ┃ EE ┃ HU ┃ LT ┃ LV ┃ MD ┃ PL ┃ RO ┃ SK ┃ UA"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 15 Jan 2025 09:05:45 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"current_page\": 1,\n \"last_page\": 6347,\n \"per_page\": 5,\n \"total\": 31732,\n \"from\": null,\n \"to\": null,\n \"items\": [\n {\n \"id\": 1,\n \"name\": \"WROCŁAW 1\",\n \"shortName\": \"WROCŁAW 1\",\n \"externalId\": \"cf909742-1bee-4c97-8d0e-16de519c3220\",\n \"source\": \"NPAX\",\n \"countryCode\": \"PL\",\n \"settlement\": {\n \"id\": 26061,\n \"name\": \"Wroclaw\",\n \"region\": {\n \"id\": 344,\n \"name\": \"Wrocław County\",\n \"parent\": {\n \"id\": 2,\n \"name\": \"Lower Silesian voivodeship\"\n }\n }\n },\n \"address\": \"50-231, Polska, Województwo dolnośląskie, Wrocław County, Wrocław, Trzebnicka, 50/1A\",\n \"number\": \"50/1\",\n \"status\": \"Working\",\n \"customerServiceAvailable\": true,\n \"divisionCategory\": \"PostBranch\",\n \"publicPhones\": [],\n \"internalPhones\": [],\n \"responsiblePerson\": \"Panchenko Artem\",\n \"partner\": null,\n \"ownerDivision\": {\n \"id\": 1832573,\n \"name\": \"Wrocław, oddział pocztowy nr1\"\n },\n \"latitude\": 51.1271131131,\n \"longitude\": 17.0360840848,\n \"distance\": null,\n \"longTermLocation\": false,\n \"maxWeightPlaceSender\": 200000,\n \"maxLengthPlaceSender\": 3000,\n \"maxWidthPlaceSender\": 1700,\n \"maxHeightPlaceSender\": 1700,\n \"maxWeightPlaceRecipient\": 200000,\n \"maxLengthPlaceRecipient\": 3000,\n \"maxWidthPlaceRecipient\": 1700,\n \"maxHeightPlaceRecipient\": 1700,\n \"prohibitedSending\": false,\n \"prohibitedIssuance\": false,\n \"maxCostPlace\": 999999,\n \"maxDeclaredCostPlace\": 999999,\n \"workSchedule\": [\n {\n \"day\": \"sunday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"monday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"tuesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"wednesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"thursday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"friday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"saturday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n }\n ],\n \"girthValue\": null,\n \"girthFormula\": null,\n \"settings\": [\n {\n \"id\": 119745,\n \"divisionId\": 1,\n \"from\": \"2025-01-09T10:26:23.390035Z\",\n \"to\": \"3024-01-09T10:26:23.390041Z\",\n \"name\": \"divisionsWithinOneLocation\",\n \"value\": \"1860229\",\n \"createdAt\": \"2022-09-29T12:40:39.000000Z\",\n \"updatedAt\": \"2025-01-09T10:26:23.460989Z\",\n \"deletedAt\": null\n }\n ],\n \"logisticsCode\": null,\n \"createdAt\": \"2022-09-29T12:40:39.000000Z\",\n \"updatedAt\": \"2025-01-09T10:26:24.535290Z\",\n \"deletedAt\": null,\n \"fullAddress\": {\n \"country\": \"Poland\",\n \"settlement\": \"Wrocław\",\n \"street\": \"Trzebnicka\",\n \"building\": \"50/1A\",\n \"note\": \"\",\n \"zipcode\": \"50-231\"\n }\n },\n {\n \"id\": 2,\n \"name\": \"WARSZAWA 2\",\n \"shortName\": \"WARSZAWA 2\",\n \"externalId\": \"b0c71d03-d446-459f-9b17-ff56ab003f96\",\n \"source\": \"NPAX\",\n \"countryCode\": \"PL\",\n \"settlement\": {\n \"id\": 22326,\n \"name\": \"Warsaw\",\n \"region\": {\n \"id\": 232,\n \"name\": \"Warszawa County\",\n \"parent\": {\n \"id\": 4,\n \"name\": \"Masovian voivodeship\"\n }\n }\n },\n \"address\": \"04-086, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Męcińska, 18\",\n \"number\": \"04/2\",\n \"status\": \"Working\",\n \"customerServiceAvailable\": true,\n \"divisionCategory\": \"PostBranch\",\n \"publicPhones\": [],\n \"internalPhones\": [],\n \"responsiblePerson\": \"Melnykova Maryna\",\n \"partner\": null,\n \"ownerDivision\": {\n \"id\": 963145,\n \"name\": \"Warszawa, oddział pocztowy nr2\"\n },\n \"latitude\": 52.2429190685,\n \"longitude\": 21.0852285118,\n \"distance\": null,\n \"longTermLocation\": false,\n \"maxWeightPlaceSender\": 200000,\n \"maxLengthPlaceSender\": 3000,\n \"maxWidthPlaceSender\": 1700,\n \"maxHeightPlaceSender\": 1700,\n \"maxWeightPlaceRecipient\": 200000,\n \"maxLengthPlaceRecipient\": 3000,\n \"maxWidthPlaceRecipient\": 1700,\n \"maxHeightPlaceRecipient\": 1700,\n \"prohibitedSending\": false,\n \"prohibitedIssuance\": false,\n \"maxCostPlace\": 999999,\n \"maxDeclaredCostPlace\": 999999,\n \"workSchedule\": [\n {\n \"day\": \"sunday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"monday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"tuesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"wednesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"thursday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"friday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"saturday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n }\n ],\n \"girthValue\": null,\n \"girthFormula\": null,\n \"settings\": [],\n \"logisticsCode\": null,\n \"createdAt\": \"2022-09-29T12:44:02.000000Z\",\n \"updatedAt\": \"2025-01-09T10:26:08.896529Z\",\n \"deletedAt\": null,\n \"fullAddress\": {\n \"country\": \"Poland\",\n \"settlement\": \"Warszawa\",\n \"street\": \"Męcińska\",\n \"building\": \"18\",\n \"note\": \"\",\n \"zipcode\": \"04-086\"\n }\n },\n {\n \"id\": 3,\n \"name\": \"RZESZÓW 1\",\n \"shortName\": \"RZESZÓW 1\",\n \"externalId\": \"1025eac5-1ae3-4a64-afc4-f653c85ce6dd\",\n \"source\": \"NPAX\",\n \"countryCode\": \"PL\",\n \"settlement\": {\n \"id\": 27011,\n \"name\": \"Rzeszow\",\n \"region\": {\n \"id\": 334,\n \"name\": \"Rzeszów County\",\n \"parent\": {\n \"id\": 11,\n \"name\": \"Subcarpathian voivodeship\"\n }\n }\n },\n \"address\": \"35-001, Polska, Województwo podkarpackie, Rzeszów County, Rzeszów, Aleja Józefa Piłsudskiego, 34\",\n \"number\": \"35/1\",\n \"status\": \"Working\",\n \"customerServiceAvailable\": true,\n \"divisionCategory\": \"PostBranch\",\n \"publicPhones\": [],\n \"internalPhones\": [],\n \"responsiblePerson\": \"Skilska Myroslava\",\n \"partner\": null,\n \"ownerDivision\": {\n \"id\": 1832574,\n \"name\": \"Rzeszów, oddział pocztowy nr1\"\n },\n \"latitude\": 50.0413969359,\n \"longitude\": 22.0038924118,\n \"distance\": null,\n \"longTermLocation\": false,\n \"maxWeightPlaceSender\": 200000,\n \"maxLengthPlaceSender\": 3000,\n \"maxWidthPlaceSender\": 1700,\n \"maxHeightPlaceSender\": 1700,\n \"maxWeightPlaceRecipient\": 200000,\n \"maxLengthPlaceRecipient\": 3000,\n \"maxWidthPlaceRecipient\": 1700,\n \"maxHeightPlaceRecipient\": 1700,\n \"prohibitedSending\": false,\n \"prohibitedIssuance\": false,\n \"maxCostPlace\": 999999,\n \"maxDeclaredCostPlace\": 999999,\n \"workSchedule\": [\n {\n \"day\": \"sunday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"monday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"tuesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"wednesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"thursday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"friday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"saturday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n }\n ],\n \"girthValue\": null,\n \"girthFormula\": null,\n \"settings\": [\n {\n \"id\": 119730,\n \"divisionId\": 3,\n \"from\": \"2025-01-09T10:25:51.118530Z\",\n \"to\": \"3024-01-09T10:25:51.118536Z\",\n \"name\": \"divisionsWithinOneLocation\",\n \"value\": \"1870544\",\n \"createdAt\": \"2022-09-29T12:47:05.000000Z\",\n \"updatedAt\": \"2025-01-09T10:25:51.191371Z\",\n \"deletedAt\": null\n }\n ],\n \"logisticsCode\": null,\n \"createdAt\": \"2022-09-29T12:47:05.000000Z\",\n \"updatedAt\": \"2025-01-09T10:25:52.169247Z\",\n \"deletedAt\": null,\n \"fullAddress\": {\n \"country\": \"Poland\",\n \"settlement\": \"Rzeszów\",\n \"street\": \"Aleja Józefa Piłsudskiego\",\n \"building\": \"34\",\n \"note\": \"\",\n \"zipcode\": \"35-001\"\n }\n },\n {\n \"id\": 4,\n \"name\": \"POZNAŃ 1\",\n \"shortName\": \"POZNAŃ 1\",\n \"externalId\": \"6f54868b-838d-4180-8fdf-d9cccfe671cd\",\n \"source\": \"NPAX\",\n \"countryCode\": \"PL\",\n \"settlement\": {\n \"id\": 23213,\n \"name\": \"Poznan\",\n \"region\": {\n \"id\": 78,\n \"name\": \"Poznan\",\n \"parent\": {\n \"id\": 3,\n \"name\": \"Greater Poland voivodeship\"\n }\n }\n },\n \"address\": \"61-866, Polska, Województwo wielkopolskie, Poznan County, Poznań, Garbary, 95\",\n \"number\": \"61/1\",\n \"status\": \"Working\",\n \"customerServiceAvailable\": true,\n \"divisionCategory\": \"PostBranch\",\n \"publicPhones\": [],\n \"internalPhones\": [],\n \"responsiblePerson\": \"Kuzmin Oleksandr\",\n \"partner\": null,\n \"ownerDivision\": {\n \"id\": 977491,\n \"name\": \"Poznań, oddział pocztowy nr1\"\n },\n \"latitude\": 52.4119103525,\n \"longitude\": 16.9384225423,\n \"distance\": null,\n \"longTermLocation\": false,\n \"maxWeightPlaceSender\": 200000,\n \"maxLengthPlaceSender\": 3000,\n \"maxWidthPlaceSender\": 1700,\n \"maxHeightPlaceSender\": 1700,\n \"maxWeightPlaceRecipient\": 200000,\n \"maxLengthPlaceRecipient\": 3000,\n \"maxWidthPlaceRecipient\": 1700,\n \"maxHeightPlaceRecipient\": 1700,\n \"prohibitedSending\": false,\n \"prohibitedIssuance\": false,\n \"maxCostPlace\": 999999,\n \"maxDeclaredCostPlace\": 999999,\n \"workSchedule\": [\n {\n \"day\": \"sunday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"monday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"tuesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"wednesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"thursday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"friday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"saturday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n }\n ],\n \"girthValue\": null,\n \"girthFormula\": null,\n \"settings\": [],\n \"logisticsCode\": null,\n \"createdAt\": \"2022-09-29T12:49:05.000000Z\",\n \"updatedAt\": \"2025-01-09T10:26:00.228210Z\",\n \"deletedAt\": null,\n \"fullAddress\": {\n \"country\": \"Poland\",\n \"settlement\": \"Poznań\",\n \"street\": \"Garbary\",\n \"building\": \"95\",\n \"note\": \"\",\n \"zipcode\": \"61-866\"\n }\n },\n {\n \"id\": 5,\n \"name\": \"KRAKÓW 1\",\n \"shortName\": \"KRAKÓW 1\",\n \"externalId\": \"35133a67-8b24-4c19-9c19-ddad01d41bc3\",\n \"source\": \"NPAX\",\n \"countryCode\": \"PL\",\n \"settlement\": {\n \"id\": 26024,\n \"name\": \"Krakow\",\n \"region\": {\n \"id\": 243,\n \"name\": \"Krakow County\",\n \"parent\": {\n \"id\": 10,\n \"name\": \"Lesser Poland Voivodeship\"\n }\n }\n },\n \"address\": \"30-001, Polska, Województwo małopolskie, Kraków County, Kraków, Kamienna, 19b\",\n \"number\": \"30/1\",\n \"status\": \"Working\",\n \"customerServiceAvailable\": true,\n \"divisionCategory\": \"PostBranch\",\n \"publicPhones\": [],\n \"internalPhones\": [],\n \"responsiblePerson\": \"Ihnatchyk Kyrylo\",\n \"partner\": null,\n \"ownerDivision\": {\n \"id\": 977487,\n \"name\": \"Kraków, oddział pocztowy nr1\"\n },\n \"latitude\": 50.0758964906,\n \"longitude\": 19.9416230983,\n \"distance\": null,\n \"longTermLocation\": false,\n \"maxWeightPlaceSender\": 200000,\n \"maxLengthPlaceSender\": 3000,\n \"maxWidthPlaceSender\": 1700,\n \"maxHeightPlaceSender\": 1700,\n \"maxWeightPlaceRecipient\": 200000,\n \"maxLengthPlaceRecipient\": 3000,\n \"maxWidthPlaceRecipient\": 1700,\n \"maxHeightPlaceRecipient\": 1700,\n \"prohibitedSending\": false,\n \"prohibitedIssuance\": false,\n \"maxCostPlace\": 999999,\n \"maxDeclaredCostPlace\": 999999,\n \"workSchedule\": [\n {\n \"day\": \"sunday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"monday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"tuesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"wednesday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"thursday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"friday\",\n \"from\": \"08:00\",\n \"to\": \"20:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n },\n {\n \"day\": \"saturday\",\n \"from\": \"09:00\",\n \"to\": \"18:00\",\n \"breakFrom\": null,\n \"breakTo\": null\n }\n ],\n \"girthValue\": null,\n \"girthFormula\": null,\n \"settings\": [],\n \"logisticsCode\": null,\n \"createdAt\": \"2022-09-29T12:51:06.000000Z\",\n \"updatedAt\": \"2025-01-09T10:25:47.703697Z\",\n \"deletedAt\": null,\n \"fullAddress\": {\n \"country\": \"Poland\",\n \"settlement\": \"Kraków\",\n \"street\": \"Kamienna\",\n \"building\": \"19b\",\n \"note\": \"\",\n \"zipcode\": \"30-001\"\n }\n }\n ]\n}"}],"_postman_id":"3816a62d-d2ed-4c3e-9992-b1ef6e773196"},{"name":"Find measurements","id":"b0654288-1528-4abd-9850-c31f52913e37","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api-stage.novapost.pl/v.1.0/dictionary/measurements?limit=25&page=1","description":"This API method allows you to retrieve a list of measurement units like pieces or meters or kilos, that you can use to specify your items by metric system. The response will include details of each measurement unit, such as the unit code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}},"urlObject":{"protocol":"https","path":["v.1.0","dictionary","measurements"],"host":["api-stage","novapost","pl"],"query":[{"description":{"content":"Max number of records to return on page.
\n","type":"text/plain"},"key":"limit","value":"25"},{"description":{"content":"Number of page to return.
\n","type":"text/plain"},"key":"page","value":"1"}],"variable":[]}},"response":[{"id":"a9e511d5-7f1a-4321-b069-b3981f0a2285","name":"Find measurements","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/dictionary/measurements?limit=25&page=1","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","dictionary","measurements"],"query":[{"key":"limit","value":"25","description":"Max number of records to return on page."},{"key":"page","value":"1","description":"Number of page to return."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 15 Jan 2025 08:33:15 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 25,\n \"total\": 21,\n \"from\": null,\n \"to\": null,\n \"items\": [\n {\n \"code\": \"cm\",\n \"name\": \"Centimeter\",\n \"shortName\": \"cm\",\n \"createdAt\": \"2022-09-29T09:16:04.000000Z\",\n \"updatedAt\": \"2023-06-29T12:48:09.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"cm2\",\n \"name\": \"Square centimeter\",\n \"shortName\": \"cm²\",\n \"createdAt\": \"2022-09-29T09:17:03.000000Z\",\n \"updatedAt\": \"2023-06-29T12:49:03.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"cm3\",\n \"name\": \"Cubic centimeter\",\n \"shortName\": \"cm³\",\n \"createdAt\": \"2022-09-29T09:19:17.000000Z\",\n \"updatedAt\": \"2023-06-29T12:49:03.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"DAY\",\n \"name\": \"Day\",\n \"shortName\": \"DAY\",\n \"createdAt\": \"2025-01-03T07:22:47.885918Z\",\n \"updatedAt\": \"2025-01-03T07:29:11.827752Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"kg\",\n \"name\": \"Kilogram\",\n \"shortName\": \"kg\",\n \"createdAt\": \"2022-09-29T09:21:04.000000Z\",\n \"updatedAt\": \"2023-06-29T12:51:03.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"km\",\n \"name\": \"Kilometer\",\n \"shortName\": \"km\",\n \"createdAt\": \"2022-09-29T09:22:04.000000Z\",\n \"updatedAt\": \"2023-06-29T12:51:03.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"l\",\n \"name\": \"Liter\",\n \"shortName\": \"l\",\n \"createdAt\": \"2022-09-29T09:23:02.000000Z\",\n \"updatedAt\": \"2023-06-29T12:53:06.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"m\",\n \"name\": \"Meters\",\n \"shortName\": \"m\",\n \"createdAt\": \"2022-09-29T09:24:04.000000Z\",\n \"updatedAt\": \"2024-05-04T13:03:01.594742Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"m2\",\n \"name\": \"Square meter\",\n \"shortName\": \"m²\",\n \"createdAt\": \"2022-09-29T09:25:19.000000Z\",\n \"updatedAt\": \"2023-06-29T12:53:06.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"m3\",\n \"name\": \"Cubic meter\",\n \"shortName\": \"m³\",\n \"createdAt\": \"2022-09-29T09:27:05.000000Z\",\n \"updatedAt\": \"2023-06-29T12:54:02.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"ml\",\n \"name\": \"Milliliter\",\n \"shortName\": \"ml\",\n \"createdAt\": \"2022-09-29T09:28:04.000000Z\",\n \"updatedAt\": \"2023-06-29T12:54:02.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"ML\",\n \"name\": \"Milliliter\",\n \"shortName\": \"ML\",\n \"createdAt\": \"2025-01-03T08:12:57.070490Z\",\n \"updatedAt\": \"2025-01-03T08:12:57.070490Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"mm\",\n \"name\": \"Millimeter\",\n \"shortName\": \"mm\",\n \"createdAt\": \"2022-09-29T09:29:02.000000Z\",\n \"updatedAt\": \"2023-06-29T12:55:10.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"mm2\",\n \"name\": \"Square millimeter\",\n \"shortName\": \"mm²\",\n \"createdAt\": \"2022-09-29T09:30:03.000000Z\",\n \"updatedAt\": \"2024-01-24T15:59:13.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"mm3\",\n \"name\": \"Cubic millimeter\",\n \"shortName\": \"mm³\",\n \"createdAt\": \"2022-10-03T10:15:44.000000Z\",\n \"updatedAt\": \"2023-06-29T12:56:06.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"package\",\n \"name\": \"Package\",\n \"shortName\": \"package\",\n \"createdAt\": \"2022-09-29T09:31:20.000000Z\",\n \"updatedAt\": \"2023-06-29T12:56:06.000000Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"piece\",\n \"name\": \"piece\",\n \"shortName\": \"pc.\",\n \"createdAt\": \"2024-12-08T17:10:10.789957Z\",\n \"updatedAt\": \"2025-01-08T10:41:34.104767Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"pieces\",\n \"name\": \"Pieces\",\n \"shortName\": \"pcs\",\n \"createdAt\": \"2022-09-29T09:33:05.000000Z\",\n \"updatedAt\": \"2024-10-17T06:33:35.799973Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"Quantity\",\n \"name\": \"Quantity\",\n \"shortName\": \"qt\",\n \"createdAt\": \"2022-09-29T11:40:05.000000Z\",\n \"updatedAt\": \"2025-01-03T13:25:08.710092Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"QUANTITY\",\n \"name\": \"Quantity\",\n \"shortName\": \"Quantity\",\n \"createdAt\": \"2024-12-23T14:00:33.731846Z\",\n \"updatedAt\": \"2024-12-23T14:00:33.731846Z\",\n \"deletedAt\": null\n },\n {\n \"code\": \"service\",\n \"name\": \"Service\",\n \"shortName\": \"service\",\n \"createdAt\": \"2024-12-02T14:50:19.058299Z\",\n \"updatedAt\": \"2025-01-02T09:46:35.901913Z\",\n \"deletedAt\": null\n }\n ]\n}"}],"_postman_id":"b0654288-1528-4abd-9850-c31f52913e37"},{"name":"Find currencies","id":"9805de36-ca7c-4300-9521-d8033a6f571b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api-stage.novapost.pl/v.1.0/dictionary/currencies?page=1&limit=100&codes[]=UAH","description":"This API method allows you to retrieve a list of currencies that are available for creating transportation documents. By making a request with this method, you can obtain a list of currencies supported by the system. The response will include details of each currency, such as the currency code, name, and any other relevant information. This data can be useful to generate a transportation document (shipment).
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}},"urlObject":{"protocol":"https","path":["v.1.0","dictionary","currencies"],"host":["api-stage","novapost","pl"],"query":[{"key":"page","value":"1"},{"key":"limit","value":"100"},{"description":{"content":"Currencies codes.
\n","type":"text/plain"},"key":"codes[]","value":"UAH"}],"variable":[]}},"response":[{"id":"e8c8356f-594a-474f-b886-8e67ea0c701d","name":"Find currencies","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/dictionary/currencies?page=1&limit=100&codes[]=UAH","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","dictionary","currencies"],"query":[{"key":"page","value":"1"},{"key":"limit","value":"100"},{"key":"codes[]","value":"UAH","description":"Currencies codes."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 15 Jan 2025 08:33:27 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 100,\n \"total\": 1,\n \"from\": null,\n \"to\": null,\n \"items\": [\n {\n \"code\": \"UAH\",\n \"numCode\": \"980\",\n \"name\": \"Hryvnia\",\n \"shortName\": \"Hryvnia\",\n \"symbol\": \"₴\",\n \"createdAt\": \"2022-09-27T11:56:05.000000Z\",\n \"updatedAt\": \"2022-09-27T11:56:05.000000Z\",\n \"deletedAt\": null\n }\n ]\n}"}],"_postman_id":"9805de36-ca7c-4300-9521-d8033a6f571b"},{"name":"Find cargo classifiers (UKT ZED)","id":"d776f987-e06a-449a-85ce-72d801c63c41","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api-stage.novapost.pl/v.1.0/dictionary/classifier?country-code=UA&fuzzy=true&keyword=book&locale=uk&size=15","description":"This API method allows you to retrieve a list of cargo classifiers (UKT ZED). Cargo classifiers are predefined categories or classifications used to categorize different types of cargo. By making a request to this method, you can obtain a list of cargo classifiers supported by the system. The response will include details of each classifier, such as the classifier ID, name, description, category, examples and any other relevant information. This data can be useful to generate a transportation document (shipment).
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}},"urlObject":{"protocol":"https","path":["v.1.0","dictionary","classifier"],"host":["api-stage","novapost","pl"],"query":[{"description":{"content":"Country code, according to the ISO 3166-1 Alpha-2 standard.
\n","type":"text/plain"},"key":"country-code","value":"UA"},{"description":{"content":"Search mechanism enables to include results that closely resemble the query terms or have some degree of similarity, expanding the search scope to include variations or similar entries.
\n","type":"text/plain"},"key":"fuzzy","value":"true"},{"description":{"content":"Search keyword.
\n","type":"text/plain"},"key":"keyword","value":"book"},{"description":{"content":"Language code according to ISO 639-1 standard.
\n","type":"text/plain"},"key":"locale","value":"uk"},{"description":{"content":"Number of matching classifiers to return.
\n","type":"text/plain"},"key":"size","value":"15"}],"variable":[]}},"response":[{"id":"ab2201dc-f4d3-4c0a-987b-48871d78aeff","name":"Find cargo classifiers (UKT ZED)","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/dictionary/classifier?country-code=UA&fuzzy=true&keyword=book&locale=uk&size=15","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","dictionary","classifier"],"query":[{"key":"country-code","value":"UA","description":"Country code, according to the ISO 3166-1 Alpha-2 standard."},{"key":"fuzzy","value":"true","description":"Search mechanism enables to include results that closely resemble the query terms or have some degree of similarity, expanding the search scope to include variations or similar entries.\n\n"},{"key":"keyword","value":"book","description":"Search keyword."},{"key":"locale","value":"uk","description":"Language code according to ISO 639-1 standard."},{"key":"size","value":"15","description":"Number of matching classifiers to return."}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 15 Jan 2025 08:33:38 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"status\": true,\n \"source\": \"tda\",\n \"error\": \"\",\n \"items\": [\n {\n \"id\": \"711ab0fa-fe12-31a9-bd30-0034824e6c11\",\n \"hsCode\": \"85249900\",\n \"category\": {\n \"en\": \"Electronics\",\n \"currentLocal\": \"Електроніка\"\n },\n \"subCategory\": {\n \"en\": \"Tablets, e-readers and accessories\",\n \"currentLocal\": \"Планшети, електронні книги та аксесуари\"\n },\n \"keywords\": {\n \"en\": \"E-book matrix, e-book stand cover, e-reader battery, e-reader backlight, e-reader case, e-book cards, e-book charger, e-book cover,\",\n \"currentLocal\": \"Матриця для електронної книги, Обкладинка підставка для електронної книги, акумулятор електронного пристрою для читання, підсвічування для електронного пристрою для читання, футляр для електронного пристрою для читання, картки для електронних книг, зарядний пристрій для електронних книг, кришка для e-book\"\n },\n \"product\": {\n \"en\": \"Accessories for the e-book\",\n \"currentLocal\": \"Комплектуючі до електронної книги\"\n },\n \"description\": {\n \"en\": \"Electrical machinery and equipment and parts thereof; sound recorders and reproducers, television image and sound recorders and reproducers, and parts and accessories of such articles | Flat panel display modules, whether or not incorporating touch-sensitive screens: | Other: | Other\",\n \"currentLocal\": \"Електричні машини, обладнання та їх частини; апаратура для запису або відтворення звуку; телевізійна апаратура для запису та відтворення зображення і звуку, їх частини та приладдя | Плоскі дисплейні модулі, незалежно від того, мають вони сенсорні екрани чи ні: | без драйверів або схем управління: | інші: | інші\"\n },\n \"exportFromUA\": true,\n \"importToUA\": true\n }\n ],\n \"pagination\": {\n \"offset\": 0,\n \"size\": 15,\n \"total\": 1\n }\n}"}],"_postman_id":"d776f987-e06a-449a-85ce-72d801c63c41"}],"id":"b01824a2-fdbb-48b5-a9f0-63f2b9ee70a2","description":"Folder contains following methods with path configured for Stage Environment:
\nhttps://api-stage.novapost.pl/v.1.0
\nFind divisions
\nFind measurements
\nFind currencies
\nFind cargo classifiers (UKT ZED)
\nThis API method allows you to retrieve the exchange rates for different currencies based on a specific amount and your own currency. By providing the amount and the currency code, you can access the current exchange rates against various other currencies. The response will include the exchange rates for the specified amount in comparison to each currency, allowing you to see currency conversions.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}},"urlObject":{"protocol":"https","path":["v.1.0","exchange-rates","conversion"],"host":["api","novapost","com"],"query":[],"variable":[]}},"response":[{"id":"e64bc9c3-ae78-4187-8a75-f768142cfa75","name":"Exchange rates","originalRequest":{"method":"POST","header":[{"key":"Accept","value":"application/json"},{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"amount\": 100,\r\n \"countryCode\": \"UA\",\r\n \"currencyCode\": \"USD\",\r\n \"date\": \"2023-10-16T00:00:00.000000Z\"\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api.novapost.com/v.1.0/exchange-rates/conversion"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 15 Jan 2025 08:29:25 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"requestCurrency\": {\n \"currencyCode\": \"USD\",\n \"amount\": 100\n },\n \"mainCurrency\": {\n \"currencyCode\": \"UAH\",\n \"amount\": 3662.16\n },\n \"convertedCurrencies\": [\n {\n \"currencyCode\": \"UAH\",\n \"amount\": 3662.16\n },\n {\n \"currencyCode\": \"THB\",\n \"amount\": 3656.67\n },\n {\n \"currencyCode\": \"HKD\",\n \"amount\": 782.95\n },\n {\n \"currencyCode\": \"IDR\",\n \"amount\": 1561688.7\n },\n {\n \"currencyCode\": \"TRY\",\n \"amount\": 2755.78\n },\n {\n \"currencyCode\": \"RON\",\n \"amount\": 472.25\n },\n {\n \"currencyCode\": \"ILS\",\n \"amount\": 386.36\n },\n {\n \"currencyCode\": \"CHF\",\n \"amount\": 91.44\n },\n {\n \"currencyCode\": \"HUF\",\n \"amount\": 36793.06\n },\n {\n \"currencyCode\": \"MXN\",\n \"amount\": 1808.12\n },\n {\n \"currencyCode\": \"RUB\",\n \"amount\": 9985.17\n },\n {\n \"currencyCode\": \"CAD\",\n \"amount\": 137.54\n },\n {\n \"currencyCode\": \"GEL\",\n \"amount\": 267.89\n },\n {\n \"currencyCode\": \"MDL\",\n \"amount\": 1823.15\n },\n {\n \"currencyCode\": \"ZAR\",\n \"amount\": 1956.6\n },\n {\n \"currencyCode\": \"NZD\",\n \"amount\": 168.27\n },\n {\n \"currencyCode\": \"SAR\",\n \"amount\": 375.59\n },\n {\n \"currencyCode\": \"IRR\",\n \"amount\": 4204546.5\n },\n {\n \"currencyCode\": \"VND\",\n \"amount\": 2433328.9\n },\n {\n \"currencyCode\": \"MYR\",\n \"amount\": 470.22\n },\n {\n \"currencyCode\": \"DZD\",\n \"amount\": 13741.69\n },\n {\n \"currencyCode\": \"SEK\",\n \"amount\": 1101.5\n },\n {\n \"currencyCode\": \"BRL\",\n \"amount\": 504.08\n },\n {\n \"currencyCode\": \"UZS\",\n \"amount\": 1219094.54\n },\n {\n \"currencyCode\": \"AED\",\n \"amount\": 367.84\n },\n {\n \"currencyCode\": \"LBP\",\n \"amount\": 1502116.49\n },\n {\n \"currencyCode\": \"EGP\",\n \"amount\": 3083.4\n },\n {\n \"currencyCode\": \"TJS\",\n \"amount\": 1097.28\n },\n {\n \"currencyCode\": \"RSD\",\n \"amount\": 11074.3\n },\n {\n \"currencyCode\": \"TMT\",\n \"amount\": 350.51\n },\n {\n \"currencyCode\": \"KGS\",\n \"amount\": 8883.78\n },\n {\n \"currencyCode\": \"AZN\",\n \"amount\": 169.84\n },\n {\n \"currencyCode\": \"CNY\",\n \"amount\": 729.83\n },\n {\n \"currencyCode\": \"NOK\",\n \"amount\": 1099.35\n },\n {\n \"currencyCode\": \"AUD\",\n \"amount\": 157.5\n },\n {\n \"currencyCode\": \"BDT\",\n \"amount\": 11016\n },\n {\n \"currencyCode\": \"INR\",\n \"amount\": 8325.55\n },\n {\n \"currencyCode\": \"MAD\",\n \"amount\": 1033.31\n },\n {\n \"currencyCode\": \"AMD\",\n \"amount\": 39397.13\n },\n {\n \"currencyCode\": \"DOP\",\n \"amount\": 5673.02\n },\n {\n \"currencyCode\": \"KRW\",\n \"amount\": 135035.4\n },\n {\n \"currencyCode\": \"BGN\",\n \"amount\": 185.89\n },\n {\n \"currencyCode\": \"TWD\",\n \"amount\": 3229.16\n },\n {\n \"currencyCode\": \"EUR\",\n \"amount\": 95.02\n },\n {\n \"currencyCode\": \"LYD\",\n \"amount\": 489.62\n },\n {\n \"currencyCode\": \"PLN\",\n \"amount\": 437.49\n },\n {\n \"currencyCode\": \"BYN\",\n \"amount\": 275.12\n },\n {\n \"currencyCode\": \"KZT\",\n \"amount\": 47825.73\n },\n {\n \"currencyCode\": \"PKR\",\n \"amount\": 28838.18\n },\n {\n \"currencyCode\": \"SGD\",\n \"amount\": 137.01\n },\n {\n \"currencyCode\": \"JPY\",\n \"amount\": 14883.2\n },\n {\n \"currencyCode\": \"IQD\",\n \"amount\": 131189.68\n },\n {\n \"currencyCode\": \"GBP\",\n \"amount\": 82.31\n },\n {\n \"currencyCode\": \"TND\",\n \"amount\": 317.18\n },\n {\n \"currencyCode\": \"CZK\",\n \"amount\": 2320.03\n },\n {\n \"currencyCode\": \"DKK\",\n \"amount\": 708.64\n }\n ]\n}"}],"_postman_id":"70786857-3159-4fcf-91db-fff93826eb7f"}],"id":"11f8273a-69c2-4842-9a0c-b01fcb6a9e62","description":"Folder contains following method with path configured for Stage Environment:
\nhttps://api-stage.novapost.pl/v.1.0
\nThis API method enables you to retrieve a list of transportation documents (shipments) that you have created. By making a request with this method, you can access the transportation documents that belongs to you or your account. The response will include details of each shipment, such as the shipment ID, number, recipient, cargo detail, and other relevant information.
\nMethod has an option to limit the number of results and paginate through the data.
\nYou may use searching by shipment id or shipment number by adding these to query params:
\nThe response will be in JSON format(response in example section below)
\nKey Response Fields:
\ncurrent_page (integer): Current page number of the results. Min: 1.
\nlast_page (integer): Total pages available in the results. Min: 1.
\nper_page (integer): Number of items per page. Min: 1.
\ntotal (integer): Total number of items available. Min: 1.
\nitems (array of object): List of shipments containing details like:
\nid (string): Unique shipment ID.
\nsender (object): Sender details including name, address, contact.
\nrecipient (object): Recipient details similar to sender.
\nparcels (array of object): Parcel details including dimensions, weight, and description.
\nservices (array of object): List of services with pricing and description.
\ntracking (object): Shipment tracking events.
\ninvoice (object): Invoice information for the shipment.
\nSearch shipments by transportation document number. Can accept either a single search number or an array of numbers for conducting the search.
\n","type":"text/plain"},"key":"numbers[]","value":"SHPL9933911419"},{"description":{"content":"Search shipments by transportation document ids.
\n","type":"text/plain"},"key":"ids[]","value":"376859"},{"description":{"content":"Max number of items to return on page.
\n","type":"text/plain"},"key":"limit","value":"1"},{"description":{"content":"Number of page to return.
\n","type":"text/plain"},"key":"page","value":"1"},{"disabled":true,"description":{"content":"Flag showing whether the shipment is included in the registry. Only for European parcels.
\n","type":"text/plain"},"key":"inRegistry","value":"true"},{"disabled":true,"description":{"content":"Number of the register that lists all shipments in the registry. Only for European parcels.
\n","type":"text/plain"},"key":"registerNumber","value":"CRPL0000004855"},{"disabled":true,"description":{"content":"DivisionId of the shipment sender.
\n","type":"text/plain"},"key":"senderDivisionId","value":"12"}],"variable":[]}},"response":[{"id":"c6e00267-bb55-484b-8c6a-563a64a975f2","name":"Example response - Find documents","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/shipments?ids[]=376859&limit=1&page=1","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","shipments"],"query":[{"key":"numbers[]","value":"SHPL9933911419","description":"Search shipments by transportation document number. Can accept either a single search number or an array of numbers for conducting the search.","disabled":true},{"key":"ids[]","value":"376859","description":"Search shipments by transportation document ids."},{"key":"limit","value":"1","description":"Max number of items to return on page."},{"key":"page","value":"1","description":"Number of page to return."},{"key":"inRegistry","value":"true","description":"Flag showing whether the shipment is included in the registry. Only for European parcels.","disabled":true},{"key":"registerNumber","value":"CRPL0000004855","description":"Number of the register that lists all shipments in the registry. Only for European parcels.","disabled":true},{"key":"senderDivisionId","value":"12","description":"DivisionId of the shipment sender.","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 20 Nov 2024 02:09:09 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 1,\n \"total\": 1,\n \"from\": null,\n \"to\": null,\n \"items\": [\n {\n \"id\": \"376859\",\n \"version\": 2,\n \"number\": \"SHPL2524572231\",\n \"dateTime\": \"2024-11-19T23:44:55.868000Z\",\n \"scheduledDeliveryDate\": \"2024-11-21T08:20:00.000000Z\",\n \"closingDate\": null,\n \"createdAt\": \"2024-11-19T23:44:56.256000Z\",\n \"updatedAt\": \"2024-11-19T23:45:55.581000Z\",\n \"deletedAt\": null,\n \"userCreate\": \"13b0f247-1a51-11ed-a361-48df37b92096\",\n \"status\": \"ReadyToShip\",\n \"gtid\": \"2000000000000254890\",\n \"paymentStatus\": \"NeedPay\",\n \"currencyCode\": \"PLN\",\n \"parcelsAmount\": 1,\n \"note\": \"\",\n \"payerType\": \"Sender\",\n \"payerContractId\": null,\n \"payerContractNumber\": null,\n \"postomatCellReservation\": \"\",\n \"postomatOrderRef\": \"\",\n \"firstDayStorage\": null,\n \"cargoAutoReturnDate\": null,\n \"marketplacePartner\": \"\",\n \"registerNumber\": \"\",\n \"pickupId\": \"\",\n \"pickupNumber\": \"\",\n \"pickupShipmentStatus\": \"\",\n \"customerNote\": \"\",\n \"creationDateNote\": \"\",\n \"sender\": {\n \"companyId\": null,\n \"companyTin\": \"\",\n \"companyName\": \"Private person\",\n \"phone\": \"48900555111\",\n \"email\": \"chuckS@ff.ff\",\n \"name\": \"Chuck Norriss\",\n \"countryCode\": \"PL\",\n \"settlementId\": \"22326\",\n \"cityId\": null,\n \"address\": \"02-188, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Janka Muzykanta, 60, , , \",\n \"addressParts\": {\n \"city\": \"Warszawa\",\n \"region\": \"Warszawa County\",\n \"street\": \"Janka Muzykanta\",\n \"post_code\": \"02-188\",\n \"building\": \"60\",\n \"flat\": \"\",\n \"block\": \"\",\n \"note\": \"\"\n },\n \"divisionId\": \"948389\",\n \"divisionCategory\": \"PostBranch\",\n \"archive\": false,\n \"serviceType\": \"Division\",\n \"ioss\": \"\",\n \"eoriCode\": \"\",\n \"registrationAddressParts\": {\n \"city\": \"\",\n \"region\": \"\",\n \"street\": \"\",\n \"post_code\": \"\",\n \"building\": \"\",\n \"flat\": \"\",\n \"block\": \"\",\n \"note\": \"\"\n }\n },\n \"recipient\": {\n \"companyId\": null,\n \"companyTin\": \"\",\n \"companyName\": \"Private person\",\n \"phone\": \"48555444333\",\n \"email\": \"ChuckNorrisR@gmail.comm\",\n \"name\": \"Chuck Norris\",\n \"countryCode\": \"PL\",\n \"settlementId\": \"22326\",\n \"cityId\": null,\n \"address\": \"02-274, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Mineralna, 15, , , \",\n \"addressParts\": {\n \"city\": \"Warszawa\",\n \"region\": \"Warszawa County\",\n \"street\": \"Mineralna\",\n \"post_code\": \"02-274\",\n \"building\": \"15\",\n \"flat\": \"\",\n \"block\": \"\",\n \"note\": \"\"\n },\n \"divisionId\": \"1888291\",\n \"divisionCategory\": \"PostBranch\",\n \"archive\": false,\n \"serviceType\": \"Division\",\n \"eoriCode\": \"\",\n \"registrationAddressParts\": {\n \"city\": \"\",\n \"region\": \"\",\n \"street\": \"\",\n \"post_code\": \"\",\n \"building\": \"\",\n \"flat\": \"\",\n \"block\": \"\",\n \"note\": \"\"\n }\n },\n \"parcels\": [\n {\n \"number\": \"SHPL2524572231\",\n \"row_number\": 1,\n \"untied\": false,\n \"cargo_category_id\": \"1\",\n \"cargo_category_group\": \"document\",\n \"parcel_description\": \"Documents\",\n \"insurance_cost\": 0.01,\n \"length\": 350,\n \"width\": 250,\n \"height\": 20,\n \"actual_weight\": 1000,\n \"volumetric_weight\": 438,\n \"length_check\": null,\n \"width_check\": null,\n \"height_check\": null,\n \"actual_weight_check\": null,\n \"volumetric_weight_check\": null\n }\n ],\n \"services\": [\n {\n \"id\": 1092083,\n \"shipment_parcel_row_number\": 1,\n \"service_id\": \"5637144578\",\n \"service_type\": \"MainService\",\n \"service_name\": \"Document delivery\",\n \"service_code\": \"Document\",\n \"parcel_number\": \"1\",\n \"payer_type\": \"Sender\",\n \"amount\": 1,\n \"price\": 12,\n \"discount\": 0,\n \"cost\": 12,\n \"cost_before_check\": null,\n \"payment_status\": \"NeedPay\",\n \"currency_code\": \"PLN\",\n \"additional_parameters\": {\n \"divisionId\": null,\n \"addressParts\": null,\n \"cod\": null,\n \"date\": null,\n \"from\": null,\n \"to\": null,\n \"string\": null,\n \"fullName\": null,\n \"phone\": null\n }\n }\n ],\n \"onlineTracking\": {\n \"tracking_status_code\": 1,\n \"tracking_update_date\": \"2024-11-19T23:44:56.412968Z\",\n \"short_description\": \"Waiting for a parcel from you\",\n \"long_description\": \"Waiting for a parcel from you\",\n \"info\": \"\",\n \"label\": \"orange\"\n },\n \"tracking\": [\n {\n \"number\": \"SHPL2524572231\",\n \"date\": \"2024-11-19T23:44:56.256000Z\",\n \"division\": \"948389\",\n \"settlement\": \"22326\",\n \"event\": \"CreateID\",\n \"event_status\": \"now\",\n \"code\": \"1\",\n \"division_name\": \"branch\",\n \"settlement_name\": \"Warsaw\",\n \"event_name\": \"Waiting for the parcel from the sender\"\n }\n ],\n \"totalWeight\": 1,\n \"totalInsuranceCost\": 0.01,\n \"totalCost\": 12,\n \"invoice\": {\n \"incoterm\": \"DAP\",\n \"currency\": \"EUR\",\n \"exportReason\": \"Selling\",\n \"exportReasonNote\": \"Selling1\",\n \"exportReasonNoteEng\": \"Selling2\",\n \"cost\": 0.01,\n \"items\": [\n {\n \"name\": \"Documents\",\n \"nameEng\": \"Documents\",\n \"material\": \"paper\",\n \"materialEng\": \"paper\",\n \"madeInCountryCode\": \"PL\",\n \"measurementCode\": \"pieces\",\n \"amount\": 1,\n \"cost\": 0.01,\n \"hsCode\": \"49119900\",\n \"hsCodeDeclaration\": \"49119900\",\n \"hsCodeClearance\": \"49119900\",\n \"producerAndModel\": \"\",\n \"actualWeight\": 1\n }\n ]\n }\n }\n ]\n}"}],"_postman_id":"c2edc71f-2b2d-44e6-ac14-f47ed01d0895"},{"name":"Create Documents Shipments","id":"45e92dd8-e573-4d67-b519-90849b1daca2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"status\": \"ReadyToShip\",\r\n \"clientOrder\": \"\",\r\n \"note\": \"\",\r\n \"payerType\": \"Sender\",\r\n \"payerContractNumber\": null,\r\n \"invoice\": {\r\n \"incoterm\": \"DAP\",\r\n \"exportReasonId\": 1,\r\n \"exportReasonNote\": \"\",\r\n \"exportReasonNoteEng\": \"\",\r\n \"currency\": \"EUR\",\r\n \"cost\": 40,\r\n \"items\": [\r\n {\r\n \"name\": \"Diamond testers\",\r\n \"nameEng\": \"Diamond testers\",\r\n \"measurementCode\": \"pieces\",\r\n \"hsCode\": \"7016901000\",\r\n \"amount\": 1,\r\n \"cost\": 40,\r\n \"actualWeight\": 1500,\r\n \"currency\": \"EUR\",\r\n \"producerAndModel\": \"\",\r\n \"material\": \"Tin\",\r\n \"materialEng\": \"Tin\",\r\n \"madeInCountryCode\": null\r\n }\r\n ]\r\n },\r\n \"services\": [],\r\n \"parcels\": [\r\n {\r\n \"cargoCategory\": \"parcel\",\r\n \"number\": null,\r\n \"parcelDescription\": \"test\",\r\n \"insuranceCost\": 40,\r\n \"insuranceCurrencyCode\": \"EUR\",\r\n \"rowNumber\": 1,\r\n \"width\": 210,\r\n \"length\": 290,\r\n \"height\": 100,\r\n \"actualWeight\": 1500\r\n }\r\n ],\r\n \"sender\": {\r\n \"companyTin\": \"\",\r\n \"companyName\": \"\",\r\n \"phone\": \"48900555111\",\r\n \"email\": \"chuckS@ff.ff\",\r\n \"name\": \"Chuck Norris\",\r\n \"countryCode\": \"PL\",\r\n \"settlementId\": 22326,\r\n \"address\": null,\r\n \"divisionId\": 948389,\r\n \"ioss\": null,\r\n \"addressParts\": {}\r\n },\r\n \"recipient\": {\r\n \"companyTin\": \"\",\r\n \"companyName\": \"\",\r\n \"phone\": \"14144888999\",\r\n \"email\": \"test@com.us\",\r\n \"name\": \"Chuck Norris\",\r\n \"countryCode\": \"US\",\r\n \"settlementId\": null,\r\n \"divisionId\": null,\r\n \"addressParts\": {\r\n \"postCode\": \"38111\",\r\n \"regionn\": \"TN\",\r\n \"city\": \"Memphis\",\r\n \"street\": \"Burton Avenue\",\r\n \"building\": \"1374\",\r\n \"note\": \"first floor\"\r\n }\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"https://api-stage.novapost.pl/v.1.0/shipments","description":"This API method is engineered to streamline the process of generating a shipping document for logistics operations through Nova Post. By submitting key data, such as the originating and destination addresses for the shipment, users can effortlessly create a document detailing the transportation of goods. This method includes optional fields for customs authorities, accommodating shipments that cross borders. The API response will provide the unique identifier of the generated document along with other relevant information.
\nMethod: POST
\nURL: https://api-stage.novapost.pl/v.1.0/shipments
{\n \"id\": 376860,\n \"number\": \"SHPL2896131485\",\n \"scheduledDeliveryDate\": \"2024-11-21T08:20:00.000000Z\",\n \"status\": \"ReadyToShip\",\n \"cost\": 12,\n \"parcelsAmount\": 1,\n \"createdAt\": \"2024-11-20T01:09:41.636352Z\",\n \"updatedAt\": \"2024-11-20T01:09:41.636352Z\",\n \"deletedAt\": null,\n \"deliveryPartners\": [],\n \"services\": [\n {\n \"id\": \"1092084\",\n \"shipmentId\": \"376860\",\n \"shipmentParcelRowNumber\": \"1\",\n \"serviceId\": \"5637144578\",\n \"amount\": 1,\n \"contractNumber\": null,\n \"payerType\": \"Sender\",\n \"paymentStatus\": \"NeedPay\",\n \"divisionId\": null,\n \"price\": 12,\n \"discount\": 0,\n \"cost\": 12,\n \"currencyCode\": \"PLN\",\n \"user\": \"13b0f247-1a51-11ed-a361-48df37b92096\",\n \"shipmentLockVersion\": 1,\n \"additionalParameters\": {},\n \"createdAt\": \"2024-11-20T01:09:41.636352Z\",\n \"updatedAt\": \"2024-11-20T01:09:41.636352Z\"\n }\n ]\n}\n\nid: A unique identifier assigned to each shipment, facilitating internal operations such as modifications, system searches, and deletion of shipments. The 'id' serves as a key reference for administrative and logistical processes within the delivery system, allowing precise access and management of shipment records.
\nnumber: The transportation document number provided to clients for tracking purposes and accessing printed forms. It also facilitates shipment searches within the system, offering a customer-friendly way to monitor shipment progress. While 'number' is used externally for tracking and documentation, it can also serve internal needs similar to 'id' for identifying shipments in certain system operations. Pattern: ^[A-Z]{4}\\d{10}$.
\nscheduledDeliveryDate: Estimated delivery date based on routing and service level, subject to change based on logistics and external factors.
\nstatus: Current status of the shipment. Initially set to \"ReadyToShip\" upon creation, indicating it's prepared for dispatch.
\ncost: Total cost calculated for the delivery services provided, based on shipment size, weight, destination, and service options selected.
\nparcelsAmount: The total number of parcels included in the shipment. This count helps in logistics planning and tracking.Constraints: Min 1
\ncreatedAt: Timestamp when the shipment was created.
\nupdatedAt: The last timestamp when the shipment record was updated. Helps in tracking changes and updates made to the shipment details.
\nThis API method allows you to calculate the estimated delivery cost for your cargo based on various factors such as weight, dimensions, destination, and shipping method. By providing the necessary details of your cargo and shipment, you can obtain an estimated cost for delivering the goods. The response will typically include the approximate calculated cost based on the provided information.
\n{\n \"sender\": {\n \"countryCode\": \"PL\",\n \"settlementId\": 22326,\n \"divisionId\": 948389\n },\n \"recipient\": {\n \"countryCode\": \"PL\",\n \"settlementId\": 22326,\n \"divisionId\": 1888291\n },\n \"services\": [\n {\n \"serviceId\": \"5637144578\",\n \"serviceName\": \"Document delivery\",\n \"serviceCode\": \"Document\",\n \"amount\": 1,\n \"price\": 12,\n \"currencyCode\": \"PLN\",\n \"cost\": 12\n }\n ]\n}\n\nsender: Provides the sender's basic geographical information as part of the shipment's origin details in the response. This object outlines the sender’s country and may include additional location identifiers like settlement and division IDs if available.
\nrecipient: Provides the recipient's basic geographical information as part of the shipment's delivery details in the response. This object outlines the recipient’s country and may include additional location identifiers like settlement and division IDs if available.
\nservices: A collection of services associated with the shipment, each entry detailing specific services applied or requested for the shipment. This array encompasses various service details such as type of service, amount, and contractual details, along with any additional parameters that specify further service-related requirements or conditions.
\nThis API method enables you to update an existing transportation document by providing the document ID and the complete set of updated data. By specifying the document ID and including all the necessary information, you can replace the old document with the new data provided in the request. The response will typically indicate the success of the update operation and may include details of StartFragmentEndFragment
\nthe modified document.
\nStartFragment
\n{\n \"id\": 301010,\n \"number\": \"SHPL0239705199\",\n \"scheduledDeliveryDate\": \"2024-09-06T06:00:00.000000Z\",\n \"status\": \"ReadyToShip\",\n \"cost\": 55,\n \"parcelsAmount\": 1,\n \"createdAt\": \"2024-09-03T12:21:06.453809Z\",\n \"updatedAt\": \"2024-09-03T12:50:20.158966Z\",\n \"deletedAt\": null,\n \"deliveryPartners\": []\n}\n\nid: Shipment id. A unique identifier assigned to each shipment, facilitating internal operations such as modifications, system searches, and deletion of shipments. The 'id' serves as a key reference for administrative and logistical processes within the delivery system, allowing precise access and management of shipment records.Constraints: Min 1
\nnumber: Shipment number. The transportation document number provided to clients for tracking purposes and accessing printed forms. It also facilitates shipment searches within the system, offering a customer-friendly way to monitor shipment progress. While 'number' is used externally for tracking and documentation, it can also serve internal needs similar to 'id' for identifying shipments in certain system operations.Pattern: ^[A-Z]{4}\\d{10}$
\nscheduledDeliveryDate: Estimated delivery date based on routing and service level, subject to change based on logistics and external factors.
\nstatus: Current status of the shipment. Initially set to \"ReadyToShip\" upon creation, indicating it's prepared for dispatch.
\ncost: Total cost calculated for the delivery services provided, based on shipment size, weight, destination, and service options selected.
\nparcelsAmount: The total number of parcels included in the shipment. This count helps in logistics planning and tracking.Constraints: Min 1
\ncreatedAt: Timestamp when the shipment was created
\nupdatedAt: The last timestamp when the shipment record was updated. Helps in tracking changes and updates made to the shipment details.
\ndeletedAt: The timestamp when the shipment was canceled or removed from the system. If not canceled, this field is null.
\nThis API method allows you to delete a transportation document by providing its unique document ID. By specifying the document ID in the request, you can remove the corresponding document from the system. The response will typically indicate the success of the deletion operation.
\nExample Response (successful deletion):
\n{\n \"deletedAt\": \"2024-11-20T01:57:52.176276Z\"\n}\n\nTransportation document/Shipment id
\n","type":"text/plain"},"type":"any","value":"376861","key":"id"}]}},"response":[{"id":"29781b7b-837c-4c51-9a93-a861875095d9","name":"Example response Delete document","originalRequest":{"method":"DELETE","header":[{"key":"Authorization","value":""}],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":{"raw":"https://api-stage.novapost.pl/v.1.0/shipments/:id","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","shipments",":id"],"variable":[{"key":"id","value":"376861","description":"Transportation document/Shipment id"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 20 Nov 2024 01:57:52 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"Content-Length","value":"43","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"deletedAt\": \"2024-11-20T01:57:52.176276Z\"\n}"}],"_postman_id":"f6320fd7-b101-4ff9-841b-0878a1f8bba3"},{"name":"Print documents","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","packages":{},"id":"dd234de0-856f-4f6d-8d6f-7e16fa8d5cc1"}}],"id":"f5e5a9db-ba5f-4b63-a70e-e24bb4bbda9c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api-stage.novapost.pl/v.1.0/shipments/print?type=marking&numbers[]=SHPL2524572231","description":"This API method allows you to retrieve a transportation document marking in PDF format by providing the document number. The document marking is a printable document that clients can attach or affix to their cargo when sending it. By specifying the document number in the request, you can generate a PDF file containing the document marking for easy printing.
\nSuccessful Response Example:
\nAllowed: marking ┃ international ┃ invoice
\n","type":"text/plain"},"key":"type","value":"marking"},{"description":{"content":"Shipment`s numbers. Can accept either a single number or an array of numbers. \nExample: SHPL6549254433
\n","type":"text/plain"},"key":"numbers[]","value":"SHPL2524572231"}],"variable":[]}},"response":[],"_postman_id":"f5e5a9db-ba5f-4b63-a70e-e24bb4bbda9c"},{"name":"Tracking documents","event":[{"listen":"test","script":{"exec":[""],"type":"text/javascript","packages":{},"id":"3fb32335-7312-4cf9-ac0f-329af3d343a8"}}],"id":"ac1f88f9-0918-48a9-8057-c121bcec6cdf","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://api-stage.novapost.pl/v.1.0/shipments/tracking/history/?numbers[]=SHPL2524572231","description":"This API method enables you to retrieve the status of a shipment by providing the transportation document number. By specifying the document number in the request, you can obtain information about the current location or status of the shipment, providing clients with real-time updates on the progress of their cargo.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}},"urlObject":{"protocol":"https","path":["v.1.0","shipments","tracking","history",""],"host":["api-stage","novapost","pl"],"query":[{"description":{"content":"Shipment`s numbers. Can accept either a single number or an array of numbers. \nExample: SHPL6549254433
\n","type":"text/plain"},"key":"numbers[]","value":"SHPL2524572231"}],"variable":[]}},"response":[{"id":"f8082861-cfaf-433e-bc45-d5fff704a323","name":"Example response Tracking documents","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://api-stage.novapost.pl/v.1.0/shipments/tracking/history/?numbers[]=SHPL2524572231","protocol":"https","host":["api-stage","novapost","pl"],"path":["v.1.0","shipments","tracking","history",""],"query":[{"key":"numbers[]","value":"SHPL2524572231","description":"Shipment`s numbers. Can accept either a single number or an array of numbers. \nExample: SHPL6549254433"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Wed, 20 Nov 2024 02:03:09 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"Content-Length","value":"248","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"items\": [\n {\n \"id\": \"376859\",\n \"number\": \"SHPL2524572231\",\n \"scheduled_delivery_date\": \"2024-11-21T08:20:00.000000Z\",\n \"history_tracking\": [\n {\n \"code\": \"1\",\n \"code_name\": \"ECN created\",\n \"country_code\": \"PL\",\n \"settlement\": \"Warsaw\",\n \"date\": \"2024-11-19T23:44:56.256000Z\"\n }\n ]\n }\n ]\n}"}],"_postman_id":"ac1f88f9-0918-48a9-8057-c121bcec6cdf"}],"id":"01551650-d752-4ed1-bfad-6518ea53d113","description":"Folder contains following methods with path configured for Stage Environment:
\nhttps://api-stage.novapost.pl/v.1.0
\nFind documents
\nCreate Documents Shipments (with response example)
\nCalculate delivery cost (with response example)
\nUpdate document (with response example)
\nDelete document (with response example)
\nPrint documents
\nTracking documents
\nThis method allows business clients to create a new courier pickup request by specifying essential parameters such as the pickup address, parcel type, and additional details.
\nInitial Status (Draft): The pickup request is created in the Draft status, which allows clients to add all necessary shipments to the request.
Transition to Created: Once all shipments are added, clients must use the \"Update pickup request status\" method to change the status to Created. This indicates that the pickup is finalized and ready for processing by the courier service.
Time Intervals: To include a specific time interval for the pickup, clients should retrieve available time intervals using the corresponding method. This ensures that the requested pickup time aligns with the courier's schedule and availability.
\nThis method is available to business clients in EU countries where Nova Post operates.
\nnote: Type: string, Description: Optional notes or instructions for the courier, Constraints: Max 255 chars.
\nservices: Type: [string], Description: List of additional services that can be included in the pickup request. This functionality is currently under development, Constraints: —.
\nphone: Type: string, Description: The contact phone number of the sender, required to allow the courier to reach out if necessary, Constraints: 8 to 14 chars.
\nemail: Type: string┃null, Description: While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications, Constraints: —.
\nfullName: Type: string, Description: Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup, Constraints: Max 100 chars.
\ncompanyTin: Type: string, Description: The contract number of the requesting company, Constraints: 2 to 20 chars.
\ncompanyName: Type: string, Description: Name of the company requesting the pickup, Constraints: 2 to 255 chars.
\ncountryCode: Type: string, Description: ISO Alpha-2 code for the pickup location, Constraints: Pattern: ^[A-Z]{2}$.
\naddressParts: Type: object, Description: Detailed address information for the pickup location, Constraints: —.
\ncity: Type: string, Description: The name of the city for the pickup location, Constraints: Max 100 chars.
\nregion: Type: string, Description: The administrative area, state, or region for the pickup, Constraints: Max 100 chars.
\nstreet: Type: string, Description: The street name for the pickup location, Constraints: Max 100 chars.
\npostCode: Type: string, Description: The postal code of the pickup location, Constraints: Max 10 chars.
\nbuilding: Type: string, Description: The building number or name at the pickup address, Constraints: Max 100 chars.
\nflat: Type: string, Description: The apartment or office number within the building, Constraints: Max 10 chars.
\nblock: Type: string, Description: The specific block or section within a larger complex, if applicable, Constraints: Max 100 chars.
\nnote: Type: string, Description: Additional instructions for the courier to access the pickup location, Constraints: Max 100 chars.
\npickedTimeFrom: Type: date-time┃null, Description: Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots, Constraints: Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$.
\npickedTimeTo: Type: date-time┃null, Description: End of the pickup time window, selected from available time intervals provided by the method that returns available time slots, Constraints: Pattern: ^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$.
\nid: Type: integer, Description: Unique identifier for the pickup request, Constraints: Minimum 1.
\nnumber: Type: string, Description: Reference number for the pickup request, Constraints: Pattern: '^[A-Z]{4}\\d{10}$'.
\nstatus: Type: string, Description: Current pickup status, Constraints: Possible values include: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.
\nstatusDateTime: Type: string, Format: date-time, Description: Date and time when the status was last updated, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\".
\nsource: Type: string, Description: Origin of the request, Constraints: Max length 50.
\nexecutor: Type: string, Description: Assigned executor for the pickup, Constraints: Max length 50, Nullable.
\ncompanyTin: Type: string, Description: The contract number of the requesting company, Constraints: Min length 2, Max length 20.
\ncompanyName: Type: string, Description: Name of the company, Constraints: Min length 2, Max length 255.
\nfullName: Type: string, Description: Full name of the requester, Constraints: Max length 100.
\nphone: Type: string, Description: Contact phone number, Constraints: Min length 8, Max length 14.
\nemail: Type: string, Description: Contact email address, Constraints: Nullable.
\ncountryCode: Type: string, Description: Country code for the pickup location, Constraints: Pattern: \"^[A-Z]{2}$\".
\ncreatedByUser: Type: string, Description: ID of the user who created the request, Constraints: Max length 50.
\ndeliveryPartner: Type: string, Description: Partner responsible for delivery, Constraints: Nullable.
\nlockVersion: Type: integer, Description: Version number for concurrency control, Constraints: Minimum 1.
\ndivisionId: Type: integer, Description: Division ID associated with the pickup, Constraints: Minimum 1, Nullable.
\nsettlementId: Type: integer, Description: Settlement ID for the pickup location, Constraints: Minimum 1.
\ncityDistrict: Type: string, Description: City district of the pickup location, Constraints: Max length 50, Nullable.
\naddress: Type: object, Description: Formatted address and geolocation, Constraints: Nullable.
\nstring: Type: string, Description: Complete address as a formatted string, Constraints: Max length 255.
\nlatitude: Type: number, Format: float, Description: Latitude of the pickup location, Constraints: Minimum -90, Maximum 90.
\nlongitude: Type: number, Format: float, Description: Longitude of the pickup location, Constraints: Minimum -180, Maximum 180.
\naddressParts: Type: object, Description: Breakdown of address details, Constraints: Nullable.
\npostCode: Type: string, Description: Postal code of the pickup location, Constraints: Max length 10.
\nbuilding: Type: string, Description: Building number of the pickup location, Constraints: Max length 100.
\nstreet: Type: string, Description: Street name for the pickup location, Constraints: Max length 100.
\ncity: Type: string, Description: City name for the pickup location, Constraints: Max length 100.
\nregion: Type: string, Description: Region name for the pickup location, Constraints: Max length 100.
\nflat: Type: string, Description: Flat or apartment number, Constraints: Max length 10.
\nnote: Type: string, Description: Additional notes for the address, Constraints: Max length 100.
\nblock: Type: string, Description: Block or building section, Constraints: Max length 100, Nullable.
\npickedTimeFrom: Type: string, Format: date-time, Description: Start of the pickup time window, Constraints: Nullable.
\npickedTimeTo: Type: string, Format: date-time, Description: End time for the pickup window, Constraints: Nullable.
\nnote: Type: string, Description: Note or instructions for the courier, Constraints: Max length 255, Nullable.
\ncurrencyCode: Type: string, Description: Currency code of the country used for payment transactions, Constraints: Pattern: \"^[A-Z]{3}$\".
\nexternalId: Type: string, Description: Internal data, not for use, Constraints: Nullable.
\nshipments: Type: array, Items: type: object, Description: List of shipments associated with this pickup request.
\nservices: Type: array, Items: type: object, Description: List of additional services that can be included in the pickup request, Constraints: Currently under development.
\nstatuses: Type: array, Description: Array of status objects tracking pickup status changes, Items: type: object.
\nid: Type: integer, Description: Unique status identifier, Constraints: Minimum 1.
\npickupId: Type: integer, Description: Pickup request ID, Constraints: Minimum 1.
\nstatus: Type: string, Description: Current pickup status, Constraints: Possible values include: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.
\ndateTime: Type: string, Format: date-time, Description: Date and time of status update, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\".
\nnote: Type: string, Description: Optional notes related to the status, Constraints: Max length 255, Nullable.
\nuser: Type: string, Description: User ID who changed the status, Constraints: Max length 50.
\ncreatedAt: Type: string, Format: date-time, Description: Date-time of status creation, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\".
\nupdatedAt: Type: string, Format: date-time, Description: Date-time of the last update, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\".
\ndeletedAt: Type: string, Format: date-time, Description: Date-time of delete, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", Nullable.
\ncreatedAt: Type: string, Format: date-time, Description: Date-time of pickup creation, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\".
\nupdatedAt: Type: string, Format: date-time, Description: Date-time of the last update, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\".
\ndeletedAt: Type: string, Format: date-time, Description: Date-time of delete, Constraints: Pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", Nullable.
\nThe response for this request can be represented as a JSON schema.
\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}},"urlObject":{"protocol":"https","path":["v.1.0","pickups"],"host":["api-stage","novapost","pl"],"query":[],"variable":[]}},"response":[{"id":"5ae405ab-c8ac-4450-b2d2-cf3fa5795e0d","name":"Example response Create pickup","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Authorization","value":"{{vault:json-web-token}}","disabled":true}],"body":{"mode":"raw","raw":"{\n \"note\": \"Test pickup 777? Тестовий пікап, не обробляйте!\",\n \"services\": [],\n \"phone\": \"48900555111\",\n \"email\": \"chucknorris@roundhouse.kick\",\n \"fullName\": \"Chuck Norris\",\n \"companyTin\": \"\",\n \"companyName\": \"\",\n \"countryCode\": \"PL\",\n \"addressParts\": {\n \"city\": \"Warszawa\",\n \"region\": \"Warszawa County\",\n \"street\": \"Admiralska\",\n \"postCode\": \"01234\",\n \"building\": \"1\",\n \"flat\": \"1\",\n \"block\": \"\",\n \"note\": \"Test shipment, do not process\"\n },\n \"pickedTimeFrom\": \"2025-01-24T10:52:56.515000Z\",\n \"pickedTimeTo\": \"2025-01-24T12:52:56.515000Z\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://api-stage.novapost.pl/v.1.0/pickups"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"server","value":"nginx","enabled":true},{"key":"date","value":"Fri, 24 Jan 2025 14:13:20 GMT","enabled":true},{"key":"content-type","value":"application/json","enabled":true},{"key":"access-control-allow-origin","value":"*","enabled":true},{"key":"access-control-expose-headers","value":"date, content-disposition","enabled":true},{"key":"cache-control","value":"no-cache, private","enabled":true},{"key":"language","value":"en","enabled":true},{"key":"via","value":"1.1 google","enabled":true},{"key":"Alt-Svc","value":"h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000","enabled":true},{"key":"Transfer-Encoding","value":"chunked","enabled":true}],"cookie":[],"responseTime":null,"body":"{\n \"id\": \"38553\",\n \"number\": \"PUPL0000020729\",\n \"status\": \"Draft\",\n \"statusDateTime\": \"2025-01-24T14:13:20.321018Z\",\n \"source\": \"clientapi\",\n \"executor\": null,\n \"companyTin\": \"\",\n \"companyName\": \"\",\n \"fullName\": \"Chuck Norris\",\n \"phone\": \"48900555111\",\n \"email\": \"chucknorris@roundhouse.kick\",\n \"countryCode\": \"PL\",\n \"createdByUser\": \"5fed17f8-5198-11eb-80fb-b8830365bd04\",\n \"deliveryPartner\": null,\n \"lockVersion\": 1,\n \"divisionId\": null,\n \"settlementId\": 22326,\n \"cityDistrict\": null,\n \"address\": {\n \"string\": \"01234, Polska, Województwo mazowieckie, Warszawa County, Warszawa, Admiralska, 1, , 1, Test shipment, do not process\",\n \"latitude\": 52.26215209999999,\n \"longitude\": 21.1792149\n },\n \"addressParts\": {\n \"postCode\": \"01234\",\n \"building\": \"1\",\n \"street\": \"Admiralska\",\n \"city\": \"Warszawa\",\n \"region\": \"Warszawa County\",\n \"flat\": \"1\",\n \"note\": \"Test shipment, do not process\",\n \"block\": \"\"\n },\n \"pickedTimeFrom\": \"2025-01-24T10:52:56.515000Z\",\n \"pickedTimeTo\": \"2025-01-24T12:52:56.515000Z\",\n \"note\": \"Test pickup 777? Тестовий пікап, не обробляйте!\",\n \"currencyCode\": \"PLN\",\n \"externalId\": null,\n \"shipments\": [],\n \"services\": [],\n \"statuses\": [\n {\n \"id\": 139710,\n \"pickupId\": 38553,\n \"status\": \"Draft\",\n \"dateTime\": \"2025-01-24T14:13:20.321018Z\",\n \"note\": null,\n \"user\": \"5fed17f8-5198-11eb-80fb-b8830365bd04\",\n \"createdAt\": \"2025-01-24T14:13:20.321853Z\",\n \"updatedAt\": \"2025-01-24T14:13:20.321853Z\",\n \"deletedAt\": null\n }\n ],\n \"createdAt\": \"2025-01-24T14:13:20.321853Z\",\n \"updatedAt\": \"2025-01-24T14:13:20.321853Z\",\n \"deletedAt\": null\n}"}],"_postman_id":"a85ba70f-cca0-4ac6-b2d8-8fa547526e7b"},{"name":"Retrieve list of courier pickup","id":"db5e71f7-9277-4003-91cc-6dcae0db4ac3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":false},"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"url":"https://api-stage.novapost.pl/v.1.0/pickups?ids[]=38554","description":"This method allows business clients to retrieve a list of all courier pickup requests they have created. Clients can filter the list using specific parameters such as pickup IDs or pickup numbers. This method is available to business clients in EU countries where Nova Post operates.
\nname: 'numbers[]', description: Search pickups by document number. Can accept either a single search number or an array of numbers for conducting the search., type: string, example: PUCZ0000002671
\nname: 'ids[]', description: A list of pickup request IDs to search. Can accept either a single search number or an array of numbers for conducting the search., type: integer, format: int32, example: 28813
\nname: 'limit', description: Max number of items to return on page., type: integer, format: int32, example: 1, default: 15
\nname: 'page', description: Number of page to return., type: integer, format: int32, example: 1
\ncurrent_page: The current page of results in the paginated response., type: integer, minimum: 1
\nlast_page: The last available page in the paginated response., type: integer, minimum: 1
\nper_page: The number of items per page., type: integer, minimum: 1
\ntotal: Total number of pickup requests matching the filter criteria., type: integer, minimum: 0
\nitems: List of pickup requests., type: array
\nid: Unique identifier for the pickup request., type: string, minimum: 1
\nnumber: Reference number for the pickup request., type: string, pattern: '^[A-Z]{4}\\d{10}$'
\nstatus: Current pickup status, representing the different stages in the pickup process., type: string
\nstatusDateTime: Date-time of the last status update., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\"
\nsource: Source of the request creation (e.g., API, Web)., type: string
\nexecutor: Identifier of the executor (courier or service)., type: string
\ncompanyTin: Tax identification number of the company., type: string
\ncompanyName: Name of the company creating the request., type: string
\nfullName: Full name of the client sending the parcel., type: string, maxLength: 100
\nphone: The contact phone number of the sender., type: string, minLength: 8, maxLength: 14
\nemail: Contact email address, if applicable., type: string, nullable: true
\ncountryCode: ISO Alpha-2 code for the pickup location., type: string, pattern: \"^[A-Z]{2}$\"
\nexternalId: External identifier of the pickup request provided by the client., type: string
\ncreatedByUser: User ID of the person who created the request., type: string
\ndivisionId: Division ID responsible for handling the request., type: integer
\nsettlementId: Settlement ID for the pickup location., type: integer
\ncityDistrict: District of the city for the pickup., type: string
\ndeliveryPartner: Delivery partner handling the request., type: string
\nlockVersion: Version control number for preventing conflicts during updates., type: integer
\naddress: Full address details., type: object
\naddress: Full formatted address., type: string
\nlatitude: Latitude coordinate of the pickup location., type: string
\nlongitude: Longitude coordinate of the pickup location., type: string
\naddressParts: Breakdown of address details., type: object
\npostCode: Postal code of the pickup location., type: string, maxLength: 10
\nbuilding: Building number of the pickup location., type: string, maxLength: 100
\nstreet: Street name for the pickup location., type: string, maxLength: 100
\ncity: City name for the pickup location., type: string, maxLength: 100
\nregion: Region name for the pickup location., type: string, maxLength: 100
\nflat: Flat or apartment number., type: string, maxLength: 10
\nnote: Additional notes for the address., type: string, maxLength: 100
\nblock: Block or building section., type: string, maxLength: 100, nullable: true
\npickedTimeFrom: Start of the pickup time window, specified in request., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", nullable: true
\npickedTimeTo: End time for the pickup window, specified in request., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", nullable: true
\ncurrencyCode: Currency code of the country used for payment transactions., type: string, pattern: \"^[A-Z]{3}$\"
\nshipments: List of shipments associated with this pickup request., type: array
\nservices: List of additional services requested., type: array
\nstatuses: Array of status objects tracking pickup status changes., type: array
\nid: Unique status identifier., type: integer, minimum: 1
\npickupId: Pickup request ID., type: integer, minimum: 1
\nstatus: Current pickup status, representing the different stages in the pickup process., type: string
\ndateTime: Date and time of status update., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\"
\nnote: Optional notes related to the status., type: string, maxLength: 255, nullable: true
\nuser: User ID who changed the status., type: string, maxLength: 50
\ncreatedAt: Date-time of status creation., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\"
\nupdatedAt: Date-time of the last update., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\"
\ndeletedAt: Date-time of delete, if applicable., type: string, format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", nullable: true
\ncreatedAt: Date-time when the pickup request was created., type: string, format: date-time
\nupdatedAt: Date-time when the pickup request was last updated., type: string, format: date-time
\ndeletedAt: Date-time when the pickup request was deleted, if applicable., type: string, format: date-time, nullable: true
\nThe method is used to update the details of an already created pickup request. It allows clients to modify information such as the pickup address, contact details, time window and other to ensure accurate and timely parcel collection. This method is available to business clients in EU countries where Nova Post operates.
\nnote: Optional notes or instructions for the courier. (maxLength: 255)
\nservices: List of additional services that can be included in the pickup request. This functionality is currently under development. (nullable)
\nphone: The contact phone number of the sender, required to allow the courier to reach out if necessary. (minLength: 8, maxLength: 14)
\nemail: While not mandatory, providing an email is recommended as a backup contact method in case the phone number is incorrect or for additional notifications regarding the pickup. (nullable)
\nfullName: Full name of the client sending the parcel, essential for identifying the sender and ensuring accurate handling of the pickup. (maxLength: 100)
\ncompanyTin: The contract number of the requesting company. (minLength: 2, maxLength: 20)
\ncompanyName: Name of the company requesting the pickup. (minLength: 2, maxLength: 255)
\nlockVersion: Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change. (minimum: 1)
\ncountryCode: ISO Alpha-2 code for the pickup location. (pattern: \"^[A-Z]{2}$\")
\naddressParts: Detailed address information for the pickup location.
\ncity: The name of the city for the pickup location. (maxLength: 100)
\nregion: The administrative area, state, or region for the pickup. (maxLength: 100)
\nstreet: The street name for the pickup location. (maxLength: 100)
\npostCode: The postal code of the pickup location. (maxLength: 10)
\nbuilding: The building number or name at the pickup address. (maxLength: 100)
\nflat: The apartment or office number within the building. (maxLength: 10)
\nblock: The specific block or section within a larger complex, if applicable. (maxLength: 100)
\nnote: Additional instructions for the courier to access the pickup location. (maxLength: 100)
\npickedTimeFrom: Start of the pickup time window, selected from available time intervals provided by the method that returns available time slots. (format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", nullable)
\npickedTimeTo: End of the pickup time window, selected from available time intervals provided by the method that returns available time slots. (format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\", nullable)
\nThe response for this request includes a JSON schema with:
\nid: Unique identifier for the updated pickup request. (minimum: 1)
\nnumber: Reference number for the pickup request. (pattern: '^[A-Z]{4}\\d{10}$')
\nstatus: Current pickup status, representing the different stages in the pickup process. Possible values include: Draft, Created, AppointedCourier, InProgress, Done, ClientCanceled, NotCompleted, Deleted, ReceivedByCourier.
\nlockVersion: Updated version number for concurrency control.
\nnote: Updated notes for the courier. (maxLength: 255)
\npickedTimeFrom: Updated start of the pickup time window. (format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\")
\npickedTimeTo: Updated end of the pickup time window. (format: date-time, pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\")
\naddressParts: Updated address information for the pickup location.
\ncity: The name of the city for the pickup location. (maxLength: 100)
\nregion: The administrative area, state, or region for the pickup. (maxLength: 100)
\nstreet: The street name for the pickup location. (maxLength: 100)
\npostCode: The postal code of the pickup location. (maxLength: 10)
\nbuilding: The building number or name at the pickup address. (maxLength: 100)
\nflat: The apartment or office number within the building. (maxLength: 10)
\nblock: The specific block or section within a larger complex, if applicable. (maxLength: 100)
\nnote: Additional instructions for the courier to access the pickup location. (maxLength: 100)
\nstatuses: Array of updated status objects tracking pickup status changes. (items: object)
\nThis method allows business clients to fully delete an existing courier pickup request. When a pickup request is deleted, it is marked as removed in the system, and the deletion date-time is recorded. This method is available to business clients in EU countries where Nova Post operates.
\nin: path
\nname: id
\nrequired: true
\nschema: type: integer, minimum: 1
\ndescription: Unique identifier of the pickup request to be deleted.
\nThis method is used to add already created shipments to an existing courier pickup request. According to the established business process, already created shipments must be added to the courier pickup request after it has been created. This method is available to business clients in EU countries where Nova Post operates.
\nRequest Body
\nResponse
The response will include an array of objects, each representing a shipment created for the pickup. Each object contains the following properties:
id: { type: integer, description: \"Unique identifier for the pickup shipment record\", minimum: 1 }
\npickupId: { type: integer, description: \"Unique identifier of the associated pickup request\", minimum: 1 }
\nshipmentId: { type: integer, description: \"Unique identifier of the added shipment\", minimum: 1 }
\nstatus: { type: string, description: \"Indicates the current status of the shipment as part of the pickup request. Possible values: Accepted, NotReady, NotPacked, ClientCanceled, Deleted, Added\" }
note: { type: string, description: \"Additional notes related to the shipment, if applicable\", nullable: true }
\ndeliveryPartners: { type: array, description: \"List of delivery partners associated with the shipment, if applicable\", items: { type: object } }
\ncreatedAt: { type: string, format: date-time, description: \"Date-time when the shipment was added\", pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\" }
\nupdatedAt: { type: string, format: date-time, description: \"Date-time when the shipment record was last updated\", pattern: \"^20[0-9]{2}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}.[0-9]{6}Z$\" }
\ndeletedAt: { type: string, format: date-time, description: \"Date-time when the shipment record was deleted, if applicable\", nullable: true }
\nThis method allows updating the status of an existing courier pickup request. It is specifically designed for transitioning a pickup request from Draft to Created.
While the request is in Draft status, it remains in a preparatory phase where all necessary shipments can be added. Once the status is updated to Created, the shipment management system recognizes the pickup as finalized and ready for processing by the courier service.
id: { type: integer, description: \"The unique identifier of the pickup request being updated\", minimum: 1 }
\nstatus: { type: string, description: \"This field is used to update the status of a pickup request to indicate that the pickup request is finalized and ready for processing by the shipment management system\", enum: [\"Created\"] }
\nlockVersion: { type: integer, description: \"Version number for concurrency control to avoid conflicting updates. When using this method and making updates, the value of this parameter must be incremented by 1 for each subsequent change\", minimum: 1 }
\nnote: { type: string, description: \"A required note or comment providing additional information about the reason for the status update. This field must be filled when changing the status to ensure proper tracking and context\", maxLength: 255 }
\nrequired: [ \"id\", \"status\", \"lockVersion\" ]
\nUpon a successful update, the response will include a JSON object with a success key set to true:
This method retrieves available time intervals for pickups. The algorithm operates based on geographical zones serviced by couriers. These zones are conditional areas on a map defined by logistical features of courier operations. Depending on the pickup location, the system identifies the specific courier responsible for that zone and returns the detailed time intervals available for pickup.
\nMandatory Parameters:
\ncountryCode: Specifies the country code according to ISO 3166-1 Alpha-2 standard.
type: Defines the type of pickup. Allowed values are PickupDayToDay (same-day pickup) or PickupNextDay (next-day pickup).
If only these two parameters are provided, the method will return general courier working hours for the specified country without detailed intervals for a specific location or zone.
\nRecommended Parameters for Accurate Results:
\naddressParts: Provide the full pickup address, including building, street, city, region, and postal code. This ensures precise time intervals are returned for the specified address.
latitude and longitude: Use geographical coordinates if a full address is not available to determine the zone.
divisionId: Specify the ID of the nearest division if the exact address is unknown. However, note that proximity to a division does not guarantee that the courier servicing the address operates from the same division.
Additional Parameters:
\nweight: Time intervals may depend on the shipment's weight. This parameter is helpful for large or weight-sensitive shipments.Important Notes:
\nIf only countryCode and type are provided, the system will return general working hours of couriers without detailed time intervals for a specific address.
For the most accurate time intervals, providing a full address or coordinates is strongly recommended.
\nTime Interval Selection Logic:
\nIf a PickupDayToDay configuration exists:
It takes priority over PickupNextDay.
\nToday is available if:
\nNot a holiday (holiday == false);
A working schedule exists (from != null);
Current time < orderTo.
Up to 7 calendar days (including today) may be returned if:
\nNot holidays;
\nfrom is set;
orderTo is only checked for today.
If no PickupDayToDay, but PickupNextDay is configured:
Today is not available.
\nUp to 7 calendar days (excluding today) may be returned if:
\nNot holidays;
\nfrom is set.
orderTo applies only to tomorrow. If current time > orderTo, tomorrow is excluded.
If no time interval configuration exists (fallback mode):
\nToday is not available.
\nUp to 7 calendar days (excluding today, weekends, holidays) may be returned.
\nA fixed orderTo = 17:00 applies only to tomorrow.
Note:
If from is set but timeIntervals is empty, the courier will arrive sometime during the day without a fixed slot.
This logic applies to all types of configurations.
Validation behavior:
\nIf the selected day is no longer valid, the system automatically assigns the next available valid day.
\nIf the time interval is invalid or empty, the courier will arrive during the full working period.
\nRecommendation:
Providing full address details or coordinates is strongly recommended to ensure accurate time interval results.
type: { type: string, description: \"Type of time interval. Allowed values are PickupDayToDay or PickupNextDay\", enum: [\"PickupDayToDay\", \"PickupNextDay\"] }
countryCode: { type: string, description: \"Country code according to the ISO 3166-1 Alpha-2 standard\", pattern: \"^[A-Z]{2}$\" }
\ndivisionId: { type: integer, description: \"Division ID for specific branch identification\", minimum: 1, nullable: true }
\nlatitude: { type: number, description: \"Latitude for geolocation-based search\", minimum: -90, maximum: 90, nullable: true }
\nlongitude: { type: number, description: \"Longitude for geolocation-based search\", minimum: -180, maximum: 180, nullable: true }
\nmaxWeightPlaceRecipient: { type: integer, description: \"Weight of the shipment in kilograms. Optional for non-weight-sensitive intervals\", minimum: 0, nullable: true }
\naddressParts: { type: object, description: \"Full address details for location-based interval search. If not provided, latitude and longitude will be used\", nullable: true, properties: { building: { type: string, description: \"Building number or identifier\", maxLength: 100 }, street: { type: string, description: \"Street name\", maxLength: 100 }, city: { type: string, description: \"City name\", maxLength: 100 }, region: { type: string, description: \"Region or administrative area\", maxLength: 100 }, postCode: { type: string, description: \"Postal code\", maxLength: 10 }, flat: { type: string, description: \"Flat or apartment number, if applicable\", maxLength: 10, nullable: true }, note: { type: string, description: \"Additional notes for location identification\", maxLength: 100, nullable: true } } }
\nid: integer, Unique identifier for the time interval, minimum: 1
\ncountryCode: string, Country code according to the ISO 3166-1 Alpha-2 standard, pattern: \"^[A-Z]{2}$\"
\ndivisionId: integer, Division ID related to the time interval, minimum: 1, nullable: true
\ntype: string, The type of the time interval, enum: - PickupDayToDay, - PickupNextDay
\ndeliveryPartner: string, Partner responsible for the pickup, nullable: true
\nignoreNonWorkingDays: boolean, Whether to include non-working days in the search
\nmonday: object, Time intervals available on Monday, properties:
\nfrom: string, Start time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntimeIntervals: array, items:
\nfrom: string, Start time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntuesday: object, Time intervals available on Tuesday, properties:
\nfrom: string, Start time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntimeIntervals: array, items:
\nfrom: string, Start time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nwednesday: object, Time intervals available on Wednesday, properties:
\nfrom: string, Start time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntimeIntervals: array, items:
\nfrom: string, Start time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nthursday: object, Time intervals available on Thursday, properties:
\nfrom: string, Start time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntimeIntervals: array, items:
\nfrom: string, Start time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nfriday: object, Time intervals available on Friday, properties:
\nfrom: string, Start time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntimeIntervals: array, items:
\nfrom: string, Start time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nsaturday: object, Time intervals available on Saturday, properties:
\nsunday: object, Time intervals available on Sunday, properties:
\nfrom: string, Start time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\ntimeIntervals: array, items:
\nfrom: string, Start time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nto: string, End time of the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\norderTo: string, Time until which an order can be placed for the sub-interval, pattern: \"^(([0,1][0-9]|(2[0-3]))|([0-9])):[0-5][0-9]$\", nullable: true
\nnonWorkingDays: array, List of non-working days in the week, items: string, enum: - Monday, - Tuesday, - Wednesday, - Thursday, - Friday, - Saturday, - Sunday
\ncreatedAt: string, Date and time when the entry was created, format: \"yyyy-MM-dd'T'HH:mm:ss.SSSZ\"
\nupdatedAt: string, Date and time when the entry was last updated, format: \"yyyy-MM-dd'T'HH:mm:ss.SSSZ\"
\ndeletedAt: string, Date and time when the entry was deleted, format: \"yyyy-MM-dd'T'HH:mm:ss.SSSZ\", nullable: true
\nisDeleted: boolean, Indicates whether the entry has been deleted, default: false
\nThe Courier pickup feature allows sending parcels directly from an address. Through the API, clients can create requests for courier pickup, manage visit time intervals, cancel, and edit requests.
\nThis article outlines the key aspects of working with courier pickup through the API.
\nFolder contains following methods with path configured for Stage Environment:
\nhttps://api-stage.novapost.pl/v.1.0
\nCreate a courier call request
\nAdd parcels to a courier call request
\nChange the status of a request
\nRetrieve available time intervals for a courier visit
\nRetrieve a list of parcels added to a courier call request
\nRemove parcels from a request
\nDelete a courier call request
\nTrack the status of current courier call requests
\nCreate subscription
Method: POST
Path: /v.1.0/tracking-push/subscribers
Auth: Authorization: {jwt}
Overview: Create a webhook subscription to receive tracking events.
Query parameters:
type: required; type: string. The type of subscription to be created. This is a mandatory field and can take values such as: - individual: For personal accounts. - numbers: For tracking specific shipment numbers. - legal: For business accounts, requiring additional company details. - creator: To tracking all shipments created by the client, regardless of whether they are specified as the sender. Allowed: individual, numbers, legal, creator.
\nurl: required; type: string (uri). The callback URL where webhook notifications will be sent. This is a mandatory field and must be a valid URL. The URL should be capable of receiving POST requests with JSON payloads.
\nisActive: required; type: boolean. Indicates whether the subscription should be active immediately upon creation. If set to true, the webhook will start sending notifications as soon as the subscription is confirmed. Defaults to false if not provided.
phone: optional; type: string. The phone number associated with the subscription. This parameter is required when the subscription type is individual. The phone number must be in international format, for example, 380637445555.
secretToken: optional; type: string. Webhook Authorization Token: Maximum Length 600 Characters
\neventTypes: optional; type: array. A list of event types that the subscription will listen to. This parameter allows you to specify which events should trigger webhook notifications. If no value is provided, the subscription will be created for all event types by default.
\nsendWarnings: optional; type: boolean. Determines if email warnings should be sent in case of issues with the specified webhook URL. If enabled, the system will send notifications about delivery problems or other errors. Defaults to false.
warningEmail: optional; type: string (email). The email address where warnings about endpoint issues will be sent. It is required if sendWarnings is set to true. The email address should be valid and active to ensure delivery of warnings.
companyTins: optional; type: array. A list of company tax identification numbers relevant to the subscription type legal. This parameter is required for legal subscriptions and is essential to verify the company's identity. Each TIN should be a valid UUID.
Notes:
The type defines required attributes: individual→phone, numbers→use /subscribers/{id}/numbers, legal→companyTins[].
Empty eventTypes[] = all events.
{\n \"url\": \"https://example.com/webhooks/np\",\n \"type\": \"numbers\",\n \"isActive\": true,\n \"eventTypes\": [],\n \"sendWarnings\": true,\n \"warningEmail\": \"alerts@example.com\",\n \"secretToken\": \"replace-with-your-token\"\n }\n\nRetrieve subscriptions\nMethod: GET\nPath: /v.1.0/tracking-push/subscribers\nAuth: Authorization: {jwt}\nOverview: Return all subscriptions configured for the authenticated client.\nSuccess: 200.
Update subscription
Method: PUT
Path: /v.1.0/tracking-push/subscribers/{id}
Auth: Authorization: {jwt}
Path parameter:
Delete subscription\nMethod: DELETE\nPath: /v.1.0/tracking-push/subscribers/{id}\nAuth: Authorization: {jwt}\nPath parameter:
Add numbers to subscription
Method: POST
Path: /v.1.0/tracking-push/subscribers/{id}/numbers
Auth: Authorization: {jwt}
Path parameter:
id: required; type: string. The unique identifier of the subscription to which shipment numbers will be added. This is a required path parameter.
Body:
{\n \"numbers\": [\"20600000179995\", \"20600000179992\"]\n }\n\nSuccess: 200.\n\nTest webhook\nMethod: POST\nPath: /v.1.0/tracking-push/subscribers/test-webhook\nAuth: Authorization: {jwt}\nOverview: Trigger a test delivery to the configured callback URL(s). Requires at least one active subscription.\nSuccess: 200.
Subscribe to tracking events and receive HTTP POST callbacks on your endpoint.
Base path: /v.1.0/tracking-push/subscribers. Auth header: Authorization: .
Types:
numbers - events for a specific list of shipments
individual - events for shipments created by a specific person (identified by phone)
legal - events for shipments of specified companies (by TIN/EDRPOU)
Key fields:
url - HTTPS callback endpoint
secretToken - optional signing token (sent in X-NP-Key)
eventTypes[] - filter of events (empty = all)
isActive - subscription status
sendWarnings / warningEmail - email alerts when delivery fails
This endpoint allows users to register a new shipment in the system. It processes the provided shipment details and returns information about the newly created shipment record.
\nLimitations for working with registers:
\nThis method is available for shipments from Ukraine to the World.
\nCreating registers is available only for shipments originating from Ukraine.
\nA shipment can be added to a register only if the Sender’s data (city, counterparty, address) are identical for all shipments being added.
\nA shipment can be added only to one register — the same document cannot be added to multiple registers simultaneously.
\nA shipment cannot be added to a register if a printed form has already been generated for this document and the shipment date (printing date) is earlier than yesterday relative to the register creation date.
\nA shipment can be added to a register only until an express waybill has been created based on it (or until the shipment has been scanned at a Nova Poshta branch/unit).
\nA shipment marked for deletion cannot be added to a register.
\nAfter the register’s printed form has been generated, adding shipments to it is blocked.
\nMethod: POST
URL: https://api-stage.novapost.pl/v.1.0/registry/
description (string): Register name.
\nshipments (array of strings): An array containing unique shipment identifiers.
\n{\n \"description\": \"Test\",\n \"shipments\": [\n \"3a56b790-a362-11f0-87c4-005056bd9e02\",\n \"47fc8621-a362-11f0-87c4-005056bd9e02\"\n ]\n}\n\nThe response body must contain the following parameters:
\nid (string): Unique registry identifier.
\nnumber (string): Registry number.
\nversionTracking (integer): Registry version.
\ncreatedAt (date-time): Registry creation date.
\nupdatedAt (string|null): Registry last update date.
\ndeletedAt (string|null): Registry deletion date.
\nposted (boolean): Flag: 0 - registry not printed, 1 - printed.
\nprinted (boolean): Flag: 0 - registry not printed, 1 - printed.
\ndescription (string): Registry name.
\nsenderCompanyId (string): Unique identifier of the sender’s legal entity in the system.
\nsenderCompanyTin (string): Sender legal entity identifier.
\nsenderPhone (string): Sender contact phone number.
\nsenderCountryCode (string): Sender's country code according to ISO 3166-1 Alpha-2.
\nsenderSettlementId (string): Unique settlement identifier.
\nsenderSettlementExternalId (string): Additional unique settlement identifier (Ukraine only).
\nsenderSettlementName (string): Settlement name.
\nsenderDivisionId (string): Unique warehouse identifier.
\nsenderDivisionExternalId (string): Additional unique warehouse identifier (Ukraine only).
\nsenderDivisionName (string): Warehouse name.
\nsenderAddress (string): Home address or warehouse description.
\nsenderAddressParts (object): Sender’s address — contains variables describing the sender’s pickup address or another location besides warehouses.
\ncity (string): City name from which the shipment is dispatched.
\nregion (string): Administrative region (state or province) of the city.
\nstreet (string): Street name of the sender’s location.
\nstreetId (string): Unique street identifier.
\npostCode (string): Postal code.
\nbuilding (string): Building number.
\nflat (string): Apartment number.
\nblock (string): Block.
\nlatitude (number|null): Geographic latitude.
\nlongitude (number|null): Geographic longitude.
\nnote (string): Additional information about the sender’s address.
\naddressId (string|null): Unique address identifier.
\nshipments (array of object): List of shipments included in the register ⮕ [ Item ].
\nshipmentId (string): Unique shipment identifier.
\nshipmentNumber (string): Shipment number.
\n{\n \"id\": \"55d8598f-a362-11f0-87c4-005056bd9e02\",\n \"number\": \"106-00000749\",\n \"versionTracking\": 1,\n \"createdAt\": \"2025-10-07 12:45:19.085311\",\n \"updatedAt\": null,\n \"deletedAt\": null,\n \"posted\": false,\n \"printed\": false,\n \"description\": \"Test\",\n \"senderCompanyId\": \"208a60fa-45fc-48ef-98e5-53f0819ebf4f\",\n \"senderCompanyTin\": \"\",\n \"senderPhone\": \"380954891992\",\n \"senderCountryCode\": \"UA\",\n \"senderSettlementId\": \"118064\",\n \"senderSettlementExternalId\": \"e718a680-4b33-11e4-ab6d-005056801329\",\n \"senderSettlementName\": \"Kyiv\",\n \"senderDivisionId\": \"12255\",\n \"senderDivisionExternalId\": \"abe2e27a-79c2-11e2-b1c0-d4ae527baec3\",\n \"senderDivisionName\": \"\",\n \"senderAddress\": \"Київ, Відділення №72 (до 30 кг): вул. Бульварно-Кудрявська, 21\",\n \"senderAddressParts\": {\n \"city\": \"\",\n \"region\": \"\",\n \"street\": \"\",\n \"streetId\": \"\",\n \"postCode\": \"\",\n \"building\": \"\",\n \"flat\": \"\",\n \"block\": \"\",\n \"latitude\": null,\n \"longitude\": null,\n \"note\": \"\",\n \"addressId\": null\n },\n \"shipments\": [\n {\n \"shipmentId\": \"47fc8621-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51187918711526\"\n },\n {\n \"shipmentId\": \"3a56b790-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51262070458910\"\n }\n ]\n}\n\nThis API method allows retrieving information about registries created by you.
\nMethod: GET
\nURL: https://api-stage.novapost.pl/v.1.0/registry/
Path Parameter:
\nids[] (array of string): Unique registry identifiers for which information should be retrieved. This parameter is required if the numbers parameter is not specified.
numbers[] (array of string): Unique registry number for which information should be retrieved. This parameter is required if the ids parameter is not specified.EndFragment
settlementIds[] (array of string): Unique settlement identifier.
\ncreatedAtFrom (date): Start date of the registry filtering period. Used to retrieve records created from this date onwards (inclusive). The createdAtFrom field must be a date before createdAtTo
createdAtTo (date): End date of the registry filtering period. Used to retrieve records created before this date (exclusive).
\npageEnd (integer): Max number of items to return on page.
\nlimit (integer): Number of page to return.
\nThe response body must contain the following parameters:
\ncurrent_page (integer): Current page number in the response.
\nlast_page (integer): Total number of pages available for the request.
\nper_page (integer): Number of items returned on a single page.
\ntotal (integer): Total number of items matching the request criteria.
\nitems (integer): Array of objects containing data of the items on the current page. Each item includes:
\nid (string): Unique registry identifier.
\nnumber (string): Registry number.
\nversionTracking (integer): Registry version.
\ncreatedAt (date-time): Registry creation date.
\nupdatedAt (string|null): Registry last update date.
\ndeletedAt (string|null): Registry deletion date.
\nposted (boolean): Flag: 0 - registry not printed, 1 - printed.
\nprinted (boolean): Flag: 0 - registry not printed, 1 - printed.
\ndescription (string): Registry name.
\nsenderCompanyId (string): Unique identifier of the sender’s legal entity in the system.
\nsenderCompanyTin (string): Sender legal entity identifier.
\nsenderPhone (string): Sender contact phone number.
\nsenderCountryCode (string): Sender's country code according to ISO 3166-1 Alpha-2.
\nsenderSettlementId (string): Unique settlement identifier.
\nsenderSettlementExternalId (string): Additional unique settlement identifier (Ukraine only).
\nsenderSettlementName (string): Settlement name.
\nsenderDivisionId (string): Unique warehouse identifier.
\nsenderDivisionExternalId (string): Additional unique warehouse identifier (Ukraine only).
\nsenderDivisionName (string): Warehouse name.
\nsenderAddress (string): Home address or warehouse description.
\nsenderAddressParts (object): Sender’s address — contains variables describing the sender’s pickup address or another location besides warehouses.
\ncity (string): City name from which the shipment is dispatched.
\nregion (string): Administrative region (state or province) of the city.
\nstreet (string): Street name of the sender’s location.
\nstreetId (string): Unique street identifier.
\npostCode (string): Postal code.
\nbuilding (string): Building number.
\nflat (string): Apartment number.
\nblock (string): Block.
\nlatitude (number|null): Geographic latitude.
\nlongitude (number|null): Geographic longitude.
\nnote (string): Additional information about the sender’s address.
\naddressId (string|null): Unique address identifier.
\nshipments (array of object): List of shipments included in the register ⮕ [ Item ].
\nshipmentId (string): Unique shipment identifier.
\nshipmentNumber (string): Shipment number.
\n{\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 15,\n \"total\": 1,\n \"items\": [\n {\n \"id\": \"55d8598f-a362-11f0-87c4-005056bd9e02\",\n \"number\": \"106-00000749\",\n \"versionTracking\": 2,\n \"createdAt\": \"2025-10-07T12:45:19.000000Z\",\n \"updatedAt\": \"2025-10-07T09:45:51.048000Z\",\n \"deletedAt\": null,\n \"posted\": false,\n \"printed\": false,\n \"description\": \"Test\",\n \"senderCompanyId\": \"208a60fa-45fc-48ef-98e5-53f0819ebf4f\",\n \"senderCompanyTin\": \"\",\n \"senderPhone\": \"380954891992\",\n \"senderCountryCode\": \"UA\",\n \"senderSettlementId\": \"118064\",\n \"senderSettlementExternalId\": \"e718a680-4b33-11e4-ab6d-005056801329\",\n \"senderSettlementName\": \"Kyiv\",\n \"senderDivisionId\": \"12255\",\n \"senderDivisionExternalId\": \"abe2e27a-79c2-11e2-b1c0-d4ae527baec3\",\n \"senderDivisionName\": \"Post branch\",\n \"senderAddress\": \"\",\n \"senderAddressParts\": {\n \"city\": null,\n \"region\": null,\n \"street\": null,\n \"streetId\": null,\n \"postCode\": null,\n \"building\": null,\n \"flat\": null,\n \"block\": null,\n \"latitude\": null,\n \"longitude\": null,\n \"note\": null,\n \"addressId\": \"\"\n },\n \"shipments\": [\n {\n \"shipmentId\": \"47fc8621-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51187918711526\"\n },\n {\n \"shipmentId\": \"3a56b790-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51262070458910\"\n }\n ]\n }\n ]\n}\n\nThis method is used to add already created shipments to an existing registry identified by {{Id}}.
\nRestrictions
\nThis method is available for shipments from Ukraine to the World.
\nA shipment can be added to a registry only if the Sender’s data (city, counterparty, address) are identical to the shipments already included in the registry.
\nA shipment can be added only to one register - the same document cannot be added to multiple registers simultaneously.
\nA shipment cannot be added to a register if a printed form has already been generated for this document and the shipment date (printing date) is earlier than yesterday relative to the register creation date.
\nA shipment can be added to a register only until an express waybill has been created based on it (or until the shipment has been scanned at a Nova Poshta branch/unit).
\nA shipment marked for deletion cannot be added to a register.
\nAfter the register’s printed form has been generated, adding shipments to it is blocked.
\nMethod: POST
URL: https://api-stage.novapost.pl/v.1.0/registry/{{Id}}/shipments
Path Parameter:
\n{\n \"shipments\": [\n \"4e8a6cc9-a36b-11f0-87c4-005056bd9e02\"\n ]\n}\n\nThe response body must contain the following parameters:
\nid (string): Unique registry identifier.
\nnumber (string): Registry number.
\nversionTracking (integer): Registry version.
\ncreatedAt (date-time): Registry creation date.
\nupdatedAt (string|null): Registry last update date.
\ndeletedAt (string|null): Registry deletion date.
\nposted (boolean): Flag: 0 - registry not printed, 1 - printed.
\nprinted (boolean): Flag: 0 - registry not printed, 1 - printed.
\ndescription (string): Registry name.
\nsenderCompanyId (string): Unique identifier of the sender’s legal entity in the system.
\nsenderCompanyTin (string): Sender legal entity identifier.
\nsenderPhone (string): Sender contact phone number.
\nsenderCountryCode (string): Sender's country code according to ISO 3166-1 Alpha-2.
\nsenderSettlementId (string): Unique settlement identifier.
\nsenderSettlementExternalId (string): Additional unique settlement identifier (Ukraine only).
\nsenderSettlementName (string): Settlement name.
\nsenderDivisionId (string): Unique warehouse identifier.
\nsenderDivisionExternalId (string): Additional unique warehouse identifier (Ukraine only).
\nsenderDivisionName (string): Warehouse name.
\nsenderAddress (string): Home address or warehouse description.
\nsenderAddressParts (object): Sender’s address — contains variables describing the sender’s pickup address or another location besides warehouses.
\ncity (string): City name from which the shipment is dispatched.
\nregion (string): Administrative region (state or province) of the city.
\nstreet (string): Street name of the sender’s location.
\nstreetId (string): Unique street identifier.
\npostCode (string): Postal code.
\nbuilding (string): Building number.
\nflat (string): Apartment number.
\nblock (string): Block.
\nlatitude (number|null): Geographic latitude.
\nlongitude (number|null): Geographic longitude.
\nnote (string): Additional information about the sender’s address.
\naddressId (string|null): Unique address identifier.
\nshipments (array of object): List of shipments included in the register ⮕ [ Item ].
\nshipmentId (string): Unique shipment identifier.
\nshipmentNumber (string): Shipment number.
\n{\n \"id\": \"55d8598f-a362-11f0-87c4-005056bd9e02\",\n \"number\": \"106-00000749\",\n \"versionTracking\": 2,\n \"createdAt\": \"2025-10-07T12:45:19.000000Z\",\n \"updatedAt\": \"2025-10-07T09:45:51.048000Z\",\n \"deletedAt\": null,\n \"posted\": false,\n \"printed\": false,\n \"description\": \"Test\",\n \"senderCompanyId\": \"208a60fa-45fc-48ef-98e5-53f0819ebf4f\",\n \"senderCompanyTin\": \"\",\n \"senderPhone\": \"380954891992\",\n \"senderCountryCode\": \"UA\",\n \"senderSettlementId\": \"118064\",\n \"senderSettlementExternalId\": \"e718a680-4b33-11e4-ab6d-005056801329\",\n \"senderSettlementName\": \"Kyiv\",\n \"senderDivisionId\": \"12255\",\n \"senderDivisionExternalId\": \"abe2e27a-79c2-11e2-b1c0-d4ae527baec3\",\n \"senderDivisionName\": \"Post branch\",\n \"senderAddress\": \"\",\n \"senderAddressParts\": {\n \"city\": null,\n \"region\": null,\n \"street\": null,\n \"streetId\": null,\n \"postCode\": null,\n \"building\": null,\n \"flat\": null,\n \"block\": null,\n \"latitude\": null,\n \"longitude\": null,\n \"note\": null,\n \"addressId\": \"\"\n },\n \"shipments\": [\n {\n \"shipmentId\": \"47fc8621-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51187918711526\"\n },\n {\n \"shipmentId\": \"3a56b790-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51262070458910\"\n },\n {\n \"shipmentId\": \"4e8a6cc9-a36b-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51032417016620\"\n }\n ]\n}\n\nThis method allows you to remove specific shipments from an existing registry identified by {{Id}}.
\nMethod: DELETE
URL: https://api-stage.novapost.pl/v.1.0/registry/{{Id}}/shipments
Path Parameter:
\n{\n \"shipments\": [\n \"47fc8621-a362-11f0-87c4-005056bd9e02\"\n ]\n}\n\nThe response body must contain the following parameters:
\nid (string): Unique registry identifier.
\nnumber (string): Registry number.
\nversionTracking (integer): Registry version.
\ncreatedAt (date-time): Registry creation date.
\nupdatedAt (string|null): Registry last update date.
\ndeletedAt (string|null): Registry deletion date.
\nposted (boolean): Flag: 0 - registry not printed, 1 - printed.
\nprinted (boolean): Flag: 0 - registry not printed, 1 - printed.
\ndescription (string): Registry name.
\nsenderCompanyId (string): Unique identifier of the sender’s legal entity in the system.
\nsenderCompanyTin (string): Sender legal entity identifier.
\nsenderPhone (string): Sender contact phone number.
\nsenderCountryCode (string): Sender's country code according to ISO 3166-1 Alpha-2.
\nsenderSettlementId (string): Unique settlement identifier.
\nsenderSettlementExternalId (string): Additional unique settlement identifier (Ukraine only).
\nsenderSettlementName (string): Settlement name.
\nsenderDivisionId (string): Unique warehouse identifier.
\nsenderDivisionExternalId (string): Additional unique warehouse identifier (Ukraine only).
\nsenderDivisionName (string): Warehouse name.
\nsenderAddress (string): Home address or warehouse description.
\nsenderAddressParts (object): Sender’s address — contains variables describing the sender’s pickup address or another location besides warehouses.
\ncity (string): City name from which the shipment is dispatched.
\nregion (string): Administrative region (state or province) of the city.
\nstreet (string): Street name of the sender’s location.
\nstreetId (string): Unique street identifier.
\npostCode (string): Postal code.
\nbuilding (string): Building number.
\nflat (string): Apartment number.
\nblock (string): Block.
\nlatitude (number|null): Geographic latitude.
\nlongitude (number|null): Geographic longitude.
\nnote (string): Additional information about the sender’s address.
\naddressId (string|null): Unique address identifier.
\nshipments (array of object): List of shipments included in the register ⮕ [ Item ].
\nshipmentId (string): Unique shipment identifier.
\nshipmentNumber (string): Shipment number.
\n{\n \"id\": \"55d8598f-a362-11f0-87c4-005056bd9e02\",\n \"number\": \"106-00000749\",\n \"versionTracking\": 3,\n \"createdAt\": \"2025-10-07T12:45:19.000000Z\",\n \"updatedAt\": \"2025-10-07T10:56:43.313000Z\",\n \"deletedAt\": null,\n \"posted\": false,\n \"printed\": false,\n \"description\": \"Test\",\n \"senderCompanyId\": \"208a60fa-45fc-48ef-98e5-53f0819ebf4f\",\n \"senderCompanyTin\": \"\",\n \"senderPhone\": \"380954891992\",\n \"senderCountryCode\": \"UA\",\n \"senderSettlementId\": \"118064\",\n \"senderSettlementExternalId\": \"e718a680-4b33-11e4-ab6d-005056801329\",\n \"senderSettlementName\": \"Kyiv\",\n \"senderDivisionId\": \"12255\",\n \"senderDivisionExternalId\": \"abe2e27a-79c2-11e2-b1c0-d4ae527baec3\",\n \"senderDivisionName\": \"Post branch\",\n \"senderAddress\": \"\",\n \"senderAddressParts\": {\n \"city\": null,\n \"region\": null,\n \"street\": null,\n \"streetId\": null,\n \"postCode\": null,\n \"building\": null,\n \"flat\": null,\n \"block\": null,\n \"latitude\": null,\n \"longitude\": null,\n \"note\": null,\n \"addressId\": \"\"\n },\n \"shipments\": [\n {\n \"shipmentId\": \"4e8a6cc9-a36b-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51032417016620\"\n },\n {\n \"shipmentId\": \"3a56b790-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51262070458910\"\n }\n ]\n}\n\nThis method is used to rename an existing register identified by {{Id}}.
\nMethod: PUT
\nURL: https://api-stage.novapost.pl/v.1.0/registry/{{Id}}/rename
Path Parameter:
\n{\n \"description\": \"Test2\"\n}\n\nThe response body must contain the following parameters:
\nid (string): Unique registry identifier.
\nnumber (string): Registry number.
\nversionTracking (integer): Registry version.
\ncreatedAt (date-time): Registry creation date.
\nupdatedAt (string|null): Registry last update date.
\ndeletedAt (string|null): Registry deletion date.
\nposted (boolean): Flag: 0 - registry not printed, 1 - printed.
\nprinted (boolean): Flag: 0 - registry not printed, 1 - printed.
\ndescription (string): Registry name.
\nsenderCompanyId (string): Unique identifier of the sender’s legal entity in the system.
\nsenderCompanyTin (string): Sender legal entity identifier.
\nsenderPhone (string): Sender contact phone number.
\nsenderCountryCode (string): Sender's country code according to ISO 3166-1 Alpha-2.
\nsenderSettlementId (string): Unique settlement identifier.
\nsenderSettlementExternalId (string): Additional unique settlement identifier (Ukraine only).
\nsenderSettlementName (string): Settlement name.
\nsenderDivisionId (string): Unique warehouse identifier.
\nsenderDivisionExternalId (string): Additional unique warehouse identifier (Ukraine only).
\nsenderDivisionName (string): Warehouse name.
\nsenderAddress (string): Home address or warehouse description.
\nsenderAddressParts (object): Sender’s address — contains variables describing the sender’s pickup address or another location besides warehouses.
\ncity (string): City name from which the shipment is dispatched.
\nregion (string): Administrative region (state or province) of the city.
\nstreet (string): Street name of the sender’s location.
\nstreetId (string): Unique street identifier.
\npostCode (string): Postal code.
\nbuilding (string): Building number.
\nflat (string): Apartment number.
\nblock (string): Block.
\nlatitude (number|null): Geographic latitude.
\nlongitude (number|null): Geographic longitude.
\nnote (string): Additional information about the sender’s address.
\naddressId (string|null): Unique address identifier.
\nshipments (array of object): List of shipments included in the register ⮕ [ Item ].
\nshipmentId (string): Unique shipment identifier.
\nshipmentNumber (string): Shipment number.
\n{\n \"id\": \"55d8598f-a362-11f0-87c4-005056bd9e02\",\n \"number\": \"106-00000749\",\n \"versionTracking\": 5,\n \"createdAt\": \"2025-10-07T12:45:19.000000Z\",\n \"updatedAt\": \"2025-10-07T12:17:15.681000Z\",\n \"deletedAt\": null,\n \"posted\": false,\n \"printed\": false,\n \"description\": \"Test2\",\n \"senderCompanyId\": \"e06f386d-6da9-11de-99d6-002219c743f6\",\n \"senderCompanyTin\": \"33550801\",\n \"senderPhone\": \"380501234567\",\n \"senderCountryCode\": \"UA\",\n \"senderSettlementId\": \"118064\",\n \"senderSettlementExternalId\": \"e718a680-4b33-11e4-ab6d-005056801329\",\n \"senderSettlementName\": \"Kyiv\",\n \"senderDivisionId\": \"12255\",\n \"senderDivisionExternalId\": \"abe2e27a-79c2-11e2-b1c0-d4ae527baec3\",\n \"senderDivisionName\": \"Post branch\",\n \"senderAddress\": \"\",\n \"senderAddressParts\": {\n \"city\": null,\n \"region\": null,\n \"street\": null,\n \"streetId\": null,\n \"postCode\": null,\n \"building\": null,\n \"flat\": null,\n \"block\": null,\n \"latitude\": null,\n \"longitude\": null,\n \"note\": null,\n \"addressId\": \"\"\n },\n \"shipments\": [\n {\n \"shipmentId\": \"4e8a6cc9-a36b-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51032417016620\"\n },\n {\n \"shipmentId\": \"3a56b790-a362-11f0-87c4-005056bd9e02\",\n \"shipmentNumber\": \"51262070458910\"\n }\n ]\n}\n\nThis method allows you to permanently delete an existing register identified by {{Id}}.
\nMethod: DELETE
URL:https://api-stage.novapost.pl/v.1.0/registry/{{Id}}
Path Parameter:
\nThe response body must contain the following parameters:
\nsuccess (boolean): Indicates whether the deletion was successful. A value of true confirms that the entry has been successfully removed.{\n \"success\": true\n}\n\nThe Registry feature allows grouping shipments into separate lists (registries) for easier control and processing. Through the API you can create new registries, add or remove shipments, rename, and fully delete them.
\nFolder contains following methods with path configured for Stage Environment:
https://api-stage.novapost.pl/
Registry methods in API:
\nRetrieve a list of registries — view all existing registries with filtering options (GET /registry).
Create a registry — register a new shipment registry with a chosen name/description (POST /registry).
Add shipments to a registry — attach one or more shipments to an existing registry (POST /registry/{id}/shipments).
Remove shipments from a registry — delete specific shipments from a registry (DELETE /registry/{id}/shipments).
Rename a registry — update the name of an existing registry (PUT /registry/{id}/rename).
Delete a registry — permanently remove a registry and all its content (DELETE /registry/{id}).
This endpoint accepts an array of goods with their attributes (SKU, name, price, shelf life, etc.) and returns the created records with assigned objectId identifiers.
Method: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/goods/multiple
goods (array): Array of product objects.
\nsku (string): Product identifier in the system.
\ngoodsUnitName (string): Product name.
\ngoodsUnitFullName (string): Full name of the product unit.
\nprice (Float): Price per unit of the product.
\ninventExpireDays (Integer): Shelf life in days.
\n{\n \"goods\": [\n {\n \"sku\": \"9948610846581684151024\",\n \"goodsUnitName\": \"string\",\n \"goodsUnitFullName\": \"string\",\n \"price\": 1000,\n \"inventExpireDays\": 1\n },\n {\n \"sku\": \"9948610846581684151045\",\n \"goodsUnitName\": \"string\",\n \"goodsUnitFullName\": \"string\",\n \"price\": 200,\n \"inventExpireDays\": null\n }\n ]\n}\n\ngoods (array): Array of product objects.
\nobjectId (string): Unique identifier of the product.
\nsku (string): Product identifier in the system.
\ngoodsUnitName (string): Product name.
\ngoodsUnitFullName (string): Full name of the product unit.
\nprice (Float): Price per unit of the product.
\ninventExpireDays (integer): Shelf life in days.
\n{\n \"goods\": [\n {\n \"objectId\": \"69dfb650-92f9-4d27-a03c-a39e0a099374\",\n \"sku\": \"9948610846581684151024\",\n \"goodsUnitName\": \"string\",\n \"goodsUnitFullName\": \"string\",\n \"price\": 1000,\n \"inventExpireDays\": 1\n },\n {\n \"objectId\": \"b1fc6f3d-edaa-49e5-aa39-88890c367387\",\n \"sku\": \"9948610846581684151045\",\n \"goodsUnitName\": \"string\",\n \"goodsUnitFullName\": \"string\",\n \"price\": 200,\n \"inventExpireDays\": null\n }\n ]\n}\n\n201 OK: Indicates that the goods have been successfully created and assigned objectId identifiers.
422 Unprocessable Entity: Indicates that the request body was syntactically correct, but failed validation due to invalid or missing field values.
\n400 Bad Request: Indicates that the request contains an invalid format or incorrect syntax and cannot be processed by the server.
\nThis endpoint allows modifying details of an existing goods item. Only the fields that need to be changed are sent in the request (partial update), for example updating the name or price of a good. On success, the API returns the updated resource fields.
\nMethod: PATCH
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/goods/{objectId}
Only the fields that need to be changed should be included in the request. All fields below are optional, but at least one of them must be provided in order to perform an update.
\ngoodsUnitName (string): Product name.
\ngoodsUnitFullName (string): Full product name.
\nprice (Float, optional): Price per unit of the product.
\ninventExpireDays (Integer, optional): Shelf life in days.
\n{\n \"goodsUnitName\": \"string\",\n \"goodsUnitFullName\": \"string\",\n \"price\": 900,\n \"inventExpireDays\": 1\n}\n\nThe response returns the updated resource fields (only the fields that are present in the request).
\ngoodsUnitName (string): Product name.
\ngoodsUnitFullName (string): Full product name.
\nprice (Float): Price per unit of the product.
\ninventExpireDays (Integer): Shelf life in days.
\n{\n \"goodsUnitName\": \"string\",\n \"goodsUnitFullName\": \"string\",\n \"price\": 900,\n \"inventExpireDays\": 1\n}\n\n201 OK: Request successful. The server has responded as required.
\n422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\n404 Resource Not Found: The requested resource does not exist.
\nThis method is used to create one or more barcodes associated with a specific good.
\nMethod: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/goods/{objectId}/barcodes/multiple
The barcode data is passed in the barcodes array. Each element in this array has the following structure:
barcodes (array): Array of barcode objects.
\nbarCode (string): Barcode value.
\nmeasureUnitName (string): Unit of measurement.
\nincludes (integer): Number of units in the package.
\nweight (float): Weight of the barcode package (kg).
\nlength (float): Package length in centimeters.
\nheight (float): Package height in centimeters.
\nwidth (float): Package width in centimeters.
\n{\n \"barcodes\": [\n {\n \"barCode\": \"string\",\n \"measureUnitName\": \"шт\",\n \"includes\": 1,\n \"weight\": 0.01,\n \"length\": 0.01,\n \"height\": 0.01,\n \"width\": 0.01\n }\n ]\n}\n\nbarcodes (array): Array of barcode objects.
\nobjectBarcodeId (string): Unique identifier of the barcode.
\nbarCode (string): Barcode value.
\nmeasureUnitName (string): Unit of measurement (e.g., pcs, box, pallet).
\nincludes (integer): Number of units in the packaging.
\nweight (float): Weight of the barcode package (kg).
\nlength (float): Length of the package (in centimeters).
\nheight (float): Height of the package (in centimeters).
\nwidth (float): Width of the package (in centimeters).
\n{\n \"barcodes\": [\n {\n \"objectBarcodeId\": \"3279cadb-daeb-4c62-a2fa-8fdb105c85a4\",\n \"barCode\": \"string\",\n \"measureUnitName\": \"шт\",\n \"includes\": 1,\n \"weight\": 0.01,\n \"length\": 0.01,\n \"height\": 0.01,\n \"width\": 0.01\n }\n ]\n}\n\n201 OK: Barcode(s) successfully created. The response returns a barcodes array with all created barcodes, each containing a unique objectBarcodeId and the specified parameters.
422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\nThis method is used to update the parameters of an existing barcode in the system by its unique identifier.
\nMethod: PATCH
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/barcodes/{objectBarcodeId}
Only the fields that need to be updated should be included in the request body.
Note: All fields are optional, but at least one field must be provided to perform the update.
measureUnitName (string): Unit of measurement.
\nincludes (integer): Number of units in the package.
\nweight (float): Weight of the barcode package (kg).
\nwidth (float): Package width in centimeters.
\nheight (float): Package height in centimeters.
\nlength (float): Package length in centimeters.
\n{\n \"measureUnitName\": \"шт\",\n \"includes\": 1,\n \"weight\": 2.02,\n \"length\": 5.05,\n \"height\": 4.45,\n \"width\": 30\n}\n\nReturns the updated barcode object with the same fields as in the request:
\nmeasureUnitName (string): Unit of measurement.
\nincludes (integer): Number of units in the package.
\nweight (float): Weight of the barcode package (kg).
\nlength (float): Package length in centimeters.
\nheight (float): Package height in centimeters.
\nwidth (float): Package width in centimeters.
\n{\n \"measureUnitName\": \"шт\",\n \"includes\": 1,\n \"weight\": 2.02,\n \"length\": 5.05,\n \"height\": 4.45,\n \"width\": 30\n}\n\n201 OK: Barcode(s) successfully created. The barcode was successfully updated. Returns the updated barcode object.
\n422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\n404 Resource Not Found: The requested resource does not exist.
\nThis endpoint allows creating a new inbound plan to receive goods at the specified warehouse. A plan may contain one or more goods positions.
\nMethod: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/inbound-plans
externalNumber (string): Document number in client's system.
\nguid (string): Unique document ID in client's system.
\ndestWarehouse (string): Destination warehouse code.
\ndeliveryType (integer): Type of delivery.
Values:
1 – Supplier
3 – Return
7 – Nova Post
additionalInfo (string): Additional information or comment.
\ndetails (array): List of product items included in the plan. Must contain at least one object.
\nobjectId (string): Product ID.
\nquantity (integer): Number of product units.
\n{\n \"externalNumber\": \"PL-116252\",\n \"guid\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"destWarehouse\": \"TEST\",\n \"deliveryType\": 3,\n \"additionalInfo\": \"Поставка згідно замовлення #154\",\n \"details\": [\n {\n \"objectId\": \"776cfd22-1a20-4def-82dd-b14d2e6fba1f\",\n \"quantity\": 10\n },\n {\n \"objectId\": \"08adb9c8-4819-4480-87aa-54538563269e\",\n \"quantity\": 25\n }\n ]\n}\n\ndocumentId (string): Unique identifier of the inbound plan.
\nstatus (string): Current status of the plan (e.g. \"1\" = New).
externalNumber (string): External number of the inbound plan.
\nguid (string): GUID reference for the plan.
\ndestWarehouse (string): Code or name of the destination warehouse.
\ndeliveryType (integer): Delivery type.
Values:
1 – Supplier
3 – Return
7 – Nova Post
additionalInfo (string): Additional comment or description.
\ndetails (array): Array of product item details included in the inbound plan. Must contain at least one object.
\nobjectId (string): Unique identifier of the product in WMS.
\nquantity (integer): Quantity of product units planned for receipt.
\n{\n \"documentId\": \"e52937bd-bdbc-499c-bbf8-2cbfeab51ee5\",\n \"status\": \"1\",\n \"externalNumber\": \"PL-437763\",\n \"guid\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"destWarehouse\": \"Boyarka\",\n \"deliveryType\": 3,\n \"additionalInfo\": \"Поставка згідно замовлення #154\",\n \"details\": [\n {\n \"objectId\": \"776cfd22-1a20-4def-82dd-b14d2e6fba1f\",\n \"quantity\": 10\n },\n {\n \"objectId\": \"08adb9c8-4819-4480-87aa-54538563269e\",\n \"quantity\": 25\n }\n ]\n}\n\n201 OK: Request successful. The server has responded as required. The response returns the created inbound plan with all provided parameters, as well as its unique identifier documentId and status \"1\" (New).
422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\nThis endpoint allows adding one or more goods items to an already created inbound plan that is in status \"1\" (New). It expands the list of goods within the existing plan without creating a new document.
Method: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/inbound-plans/{documentId}/details
The data for new product items is passed in the details array.
details (array): Array of product items to add.
\nobjectId (string): Product identifier in WMS.
\nquantity (integer): Quantity of product units.
\n{\n \"details\": [\n {\n \"objectId\": \"7599d0e2-813b-4889-aca4-c9056abd0d27\",\n \"quantity\": 5\n },\n {\n \"objectId\": \"cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe\",\n \"quantity\": 10\n }\n ]\n}\n\nThe response returns the updated list of goods (details) for the inbound plan:
details (array): Array of product items in the inbound plan.
\nobjectId (string): Product identifier in WMS.
\nquantity (integer): Quantity of product units.
\n{\n \"details\": [\n {\n \"objectId\": \"7599d0e2-813b-4889-aca4-c9056abd0d27\",\n \"quantity\": 5\n },\n {\n \"objectId\": \"cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe\",\n \"quantity\": 10\n }\n ]\n}\n\n201 OK: The inbound plan was successfully updated.
\n422 Unprocessable Entity: The request body contains invalid data.
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\nThis endpoint is used to update the parameters of an existing inbound delivery plan by its unique identifier. The plan must be in status “1” (New).
\nMethod: PATCH
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/inbound-plans/{documentId}
Only the fields that need to be changed should be included in the request. Below are the updatable fields:
\ndestWarehouse (string): Destination warehouse.
\ndeliveryType (integer): Type of delivery.
Accepted values:
1 – Supplier delivery
3 – Nova Post return
7 – Nova Post delivery
additionalInfo (string): Additional information or comments.
\ndetails (array): Array of items included in the plan.
\nobjectId (string): Product identifier in external system.
\nquantity (integer): Number of product units.
\nNote: All fields are optional, but at least one of them must be provided in order to perform an update.
\n{\n \"destWarehouse\": \"TEST\",\n \"deliveryType\": 3,\n \"additionalInfo\": \"Change quantity and warehouse\",\n \"details\": [\n {\n \"objectId\": \"7599d0e2-813b-4889-aca4-c9056abd0d27\",\n \"quantity\": 7\n },\n {\n \"objectId\": \"cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe\",\n \"quantity\": 15\n }\n ]\n}\n\nstatus (string): Current status of the inbound plan (\"1\" = New).
destWarehouse (string): Destination warehouse code.
\ndeliveryType (integer): Type of delivery.
Accepted values:
1 – Supplier delivery
3 – Nova Post return
7 – Nova Post delivery
additionalInfo (string): Additional notes or comments.
\ndetails (array): List of product items in the plan.
\nobjectId (string): Unique ID of the product in the WMS system.
\nquantity (integer): Quantity of the product to be received.
\n{\n \"status\": \"1\",\n \"destWarehouse\": \"TEST\",\n \"deliveryType\": 3,\n \"additionalInfo\": \"Change quantity and warehouse\",\n \"details\": [\n {\n \"objectId\": \"7599d0e2-813b-4889-aca4-c9056abd0d27\",\n \"quantity\": 7\n },\n {\n \"objectId\": \"cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe\",\n \"quantity\": 15\n }\n ]\n}\n\n201 OK: The inbound plan was successfully updated. The response returns the updated inbound plan object.
\n422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\n404 Resource Not Found: The requested resource does not exist.
\nThis endpoint allows deleting one or more goods from an existing inbound plan that is in status \"1\" (New).
Method: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/inbound-plans/{documentId}/details/multiple-delete
Product items to be removed are passed in the details array.
details (array): Array of products to be removed.
\n{\n \"details\": [\n {\n \"objectId\": \"7599d0e2-813b-4889-aca4-c9056abd0d27\"\n },\n {\n \"objectId\": \"cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe\"\n }\n ]\n}\n\nReturns the details array with the products specified for deletion:
details (array): Array of products to be removed.
\n{\n \"details\": [\n {\n \"objectId\": \"7599d0e2-813b-4889-aca4-c9056abd0d27\"\n },\n {\n \"objectId\": \"cdba97f7-0ca0-4e25-a41e-abb32eb7a6fe\"\n }\n ]\n}\n\n201 OK: The inbound plan was successfully updated. The response returns the updated details array of the inbound plan.
422 Unprocessable Entity: The request body contains invalid data.
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\nThis endpoint cancels an existing inbound plan in status \"1\" (New). Once canceled, the plan transitions to status \"10\" (Cancelled) and is excluded from further processing.
Method: PATCH
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/inbound-plans/{documentId}/cancel
Pass an empty JSON object.
\n{}\n\ndocumentId (string): Unique identifier of the inbound plan.
\nstatus (integer): Current status of the plan (10 = Canceled).
{\n \"documentId\": \"e52937bd-bdbc-499c-bbf8-2cbfeab51ee5\",\n \"status\": 10\n}\n\n200 OK: The inbound plan was successfully canceled. The response returns the documentId and status \"10\" of the canceled inbound plan.
422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\n404 Resource Not Found: The requested resource does not exist.
\nThis endpoint is used to retrieve the statuses of one or more inbound plans, with support for filtering via query parameters.
\nMethod: GET
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/inbound-plans/status
No request body. All filters are passed as query parameters.
\npage (integer): Page number (each page returns up to 25 records).
\ndocumentIds[] (string): List of inbound plan IDs.
\nexternalNumbers[] (string[]): List of inbound plan external numbers.
\nwarehouseIds[] (string[]): List of warehouse codes.
\nstartDate (string, ISO 8601): Start date of search (e.g. 2025-05-05T00:00:00Z).
endDate (string, ISO 8601): End date of search (e.g. 2025-05-10T00:00:00Z).
Note: If no filter parameters are provided, the response returns the most recent inbound plans.
\nThe response includes a documents array with inbound plans matching the filters, as well as pagination fields.
Top-level fields:
\ndocuments (array): List of inbound plans.
\ndocumentId (string): Unique identifier of the inbound plan.
\nexternalNumber (string): External number of the inbound plan.
\nstatus (integer): Current plan status:
\n1 – New
2 – In Progress
3 – Completed
10 – Cancelled
destWarehouse (string): Warehouse code.
\nitems[] (array): Item details of the inbound plan.
\nobjectId (string): Product identifier.
\nsku (string): Product SKU.
\nmeasureUnitName (string / null): Unit of measurement.
\nexpectedQuantity (integer): Expected quantity.
\nreceivedQuantity (integer / null): Actually received quantity.
\ncondition (integer / null): Condition flag:
\n0 – Normal
1 – Defective
expiryDate (string, ISO 8601): Expiry date (e.g. 2025-11-12T00:00:00Z).
page: Current page number.
\npages (integer): Total number of pages.
\n{\n \"documents\": [\n {\n \"documentId\": \"28c16a4e-ad76-4c21-83bf-a7d8de8a4879\",\n \"externalNumber\": \"PL-249400\",\n \"status\": 1,\n \"destWarehouse\": \"MAIN\",\n \"items\": [\n {\n \"objectId\": \"2f1d92e7-0e92-46eb-bd9c-888ec3a9789c\",\n \"expectedQuantity\": 25,\n \"receivedQuantity\": null,\n \"expiryDate\": null,\n \"measureUnitName\": null,\n \"condition\": null,\n \"sku\": \"9948610846581684151031\"\n },\n {\n \"objectId\": \"b2c0fea8-a43b-4e8d-b9f7-14f31ba8eb08\",\n \"expectedQuantity\": 10,\n \"receivedQuantity\": null,\n \"expiryDate\": null,\n \"measureUnitName\": null,\n \"condition\": null,\n \"sku\": \"9948610846581684151000\"\n }\n ]\n },\n {\n \"documentId\": \"745a5e03-93b5-4332-9f5f-64ba0329102d\",\n \"externalNumber\": \"PL-169084\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"7e22342d-ffa4-436c-8fa4-c187d78be206\",\n \"externalNumber\": \"PL-973182\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"ed2a7dda-1992-4e05-b550-3d25b0b5257b\",\n \"externalNumber\": \"PL-200508\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"10b322d5-161e-49ee-b09d-ad15e10edd6c\",\n \"externalNumber\": \"PL-194407\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"2e217d06-4841-4ef1-bd7f-f27944dddbb4\",\n \"externalNumber\": \"PL-438453\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"cb8ece3e-991f-45a8-9f57-225f085dee3f\",\n \"externalNumber\": \"PL-168771\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"e9dd1735-c02d-4ef5-a3c5-85a6aea4c1eb\",\n \"externalNumber\": \"PL-866633\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"e4aabcaf-a8dd-4a10-b0f6-5ae3cf7e9eab\",\n \"externalNumber\": \"PL-457390\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"59185508-6135-4686-8296-89d2e3676021\",\n \"externalNumber\": \"PL-403234\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"d66f5891-1743-47d8-a559-28b1ddbe36fa\",\n \"externalNumber\": \"PL-739526\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"c9ef1354-f970-45ee-b6a1-70f87d36fa9d\",\n \"externalNumber\": \"PL-980836\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"8a29b285-23a4-429b-a181-bbd6b21ca328\",\n \"externalNumber\": \"PL-530483\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"7cab1ebd-6328-4df0-b3f8-ebbe2024e2c8\",\n \"externalNumber\": \"PL-603226\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"ce0e5672-c92a-45d7-87cb-40fb3cdf9023\",\n \"externalNumber\": \"PL-400721\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"6ffbbe8f-fee9-441c-a47f-98a5b86f1868\",\n \"externalNumber\": \"PL-430022\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"8fa2b4a1-cd98-421e-8fb0-4b203dbafe13\",\n \"externalNumber\": \"PL-899297\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"ebf52fbe-7756-40a5-ba4e-431cc58df24a\",\n \"externalNumber\": \"PL-607850\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"181fc7a6-c0a9-4993-b322-aba27c75561e\",\n \"externalNumber\": \"PL-725478\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"02ef9f8a-b27f-451c-9fad-415f53da05de\",\n \"externalNumber\": \"PL-670630\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"b19d9276-6dba-48ea-aeaa-a1eb1d8489c0\",\n \"externalNumber\": \"PL-960458\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"2627eb80-54d1-4b61-b5dc-f448caff0047\",\n \"externalNumber\": \"PL-987072\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"3888f15f-1ef4-4c92-b533-f87c0501d717\",\n \"externalNumber\": \"PL-472715\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"77f90173-5f32-4285-9c8c-df9644fc59ad\",\n \"externalNumber\": \"PL-567298\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n },\n {\n \"documentId\": \"e77f8cfb-92b7-420e-a5c1-b3b29627069c\",\n \"externalNumber\": \"PL-699041\",\n \"status\": 10,\n \"destWarehouse\": \"2\",\n \"items\": []\n }\n ],\n \"page\": 1,\n \"pages\": 9\n}\n\ndocuments array with inbound plans matching the filters.This endpoint is used to create a new customer order for shipping goods from the warehouse. Two delivery scenarios are supported:
\nShipment via Nova Post — the international express waybill number must be specified, which the client generates beforehand.
\nCustomer pickup — the order is created without specifying an international express waybill.
\nIf the request is properly formed and all requirements are met, the order is created with one of the following statuses:
\n\"1\" (New) — when all products are available in stock
\"13\" (Incomplete) — when some products are partially unavailable
Method: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/orders
externalNumber (string): Customer's internal order number.
\ndestWarehouse (string): Warehouse code.
\ndeliveryType (integer): Type of delivery.
Values:
2 – Nova Post
5 – Customer pickup
waybilNumber (string, conditional): Waybill number.
\nadditionalInfo (string): Additional information or comment.
\ndetails (array): List of product items included in the order.
\nobjectId (string): Product ID.
\nquantity (integer): Number of product units.
\nprice (float): Unit price.
\nsum (float): Total item amount.
\n{\n \"externalNumber\": \"ORDER-26062037-16\",\n \"destWarehouse\": \"Boyarka\",\n \"deliveryType\": 5,\n \"additionalInfo\": \"Замовлення зі складу в Боярці\",\n \"details\": [\n {\n \"objectId\": \"1b34e39f-5805-4510-94ca-1d88ea14739a\",\n \"quantity\": 2,\n \"price\": 10.5,\n \"sum\": 30.5\n }\n ]\n}\n\ndocumentId (string): Unique identifier of the customer order.
\nstatus (string): Status of the order.
\nexternalNumber (string): Customer's order number.
\ndestWarehouse (string): Warehouse code.
\nadditionalInfo (string): Additional notes or comments.
\ndeliveryType (integer): Delivery type (2 = Nova Post, 5 = Pickup).
waybilNumber (string): Waybill number; required if deliveryType is 2.
details (array): Array of product items included in the order.
\nobjectId (string): Unique identifier of the product in WMS.
\nquantity (integer): Quantity of the goods.
\nprice (float): Price per goods (precision up to 2 decimal places).
\nsum (float): Total amount for the item line.
\n{\n \"documentId\": \"4f22ed76-8f4f-422f-bf24-f13d165e6bf2\",\n \"status\": \"13\",\n \"externalNumber\": \"ORDER-26062037-16\",\n \"destWarehouse\": \"MAIN\",\n \"additionalInfo\": \"Замовлення зі складу в Боярці\",\n \"deliveryType\": 5,\n \"waybilNumber\": null,\n \"details\": [\n {\n \"objectId\": \"1b34e39f-5805-4510-94ca-1d88ea14739a\",\n \"quantity\": 2,\n \"price\": 10.5,\n \"sum\": 30.5\n }\n ]\n}\n\n201 OK: Request successful. Returns the full order object with documentId and initial status.
422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\nThis endpoint is used to add new goods to an existing client order that is currently in status \"13\" (Incomplete).
If the added goods are available in sufficient quantity, the order status is automatically changed to \"1\" (New).
This allows editing an existing order and resuming its processing without creating a new document.
Method: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/orders/{documentId}/details
Only the goods that need to be added are passed in the request body.
\ndetails (array): Array of items to be added to the order.
\nobjectId (string): Unique product identifier in WMS.
\nquantity (integer): Quantity of product.
\nprice (float): Unit price.
\nsum (float): Total value of the line item.
\n{\n \"details\": [\n {\n \"objectId\": \"ab0b584d-c269-41b3-a8d2-b718b96edf3b\",\n \"quantity\": 5,\n \"price\": 10,\n \"sum\": 50\n }\n ]\n}\n\ndocumentId (string): Unique identifier of the customer order.
\nstatus (integer): Current status of the order (13 = Incomplete).
{\n \"documentId\": \"e2d29580-457f-4562-88bf-b5e28aea9f88\",\n \"status\": 13\n}\n\n201 OK: Order details updated.
\n422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\n404 Resource Not Found: The requested resource does not exist.
\nThis method is used to retrieve information about the statuses of one or more client orders, with optional filtering parameters.
\nMethod: GET
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/orders/status
No request body. All filters are passed as query parameters.
\npage (integer): Page number (each page includes up to 25 objects).
\ndocumentIds (string[]): List of order identifiers.
\nexternalNumbers (string[]): List of client order numbers.
\nwarehouseIds (string[]): List of warehouse codes.
\nstartDate (string): Start date (ISO 8601 format, e.g., 2025-05-05T00:00:00Z).
endDate (string): End date (ISO 8601 format, e.g., 2025-05-05T00:00:00Z).
Note: If no filters are provided, the response will return the most recent client orders.
\ndocuments (array): Array containing client orders that match the filtering criteria. Each element in documents includes:
documentId (string): Unique identifier of the order.
\nexternalNumber (string): Order number in the client's system.
\nstatus (integer): Current order status, where 1 — New, 2 — In progress, 3 — Completed, 10 — Cancelled, 13 — Incomplete.
statusTime (string): Timestamp of the latest status update (format: YYYY-MM-DDThh:mm:ssZ).
waybilNumber (string): IEW (International Express Waybill) number.
\ndestWarehouse (string): Warehouse code.
\npage (integer): Current page number.
\npages (integer): Total number of pages.
\n{\n \"documents\": [\n {\n \"documentId\": \"ab73a718-24fe-11f0-af17-42010ade0e84\",\n \"externalNumber\": \"CO-01-01\",\n \"status\": 1,\n \"statusTime\": \"2025-08-01T09:49:38+00:00\",\n \"waybilNumber\": \"\",\n \"destWarehouse\": \"MAIN\"\n }\n ],\n \"page\": 1,\n \"pages\": 1\n}\n\ndocuments containing client orders that match the filtering criteria.This endpoint is used to cancel a previously created client order that is currently in status \"13\" (Incomplete). Once canceled, the order changes to status \"10\" (Canceled) and is excluded from further processing.
Method: PATCH
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/orders/{documentId}/cancel
An empty object {} must be sent.
{}\n\nReturns the canceled client order identifier and its new status:
\ndocumentId (string): Unique identifier of the client order.
\nstatus (integer): New status of the client order (10 – Canceled).
{\n \"documentId\": \"7fe65529-5cd1-4333-93a8-c072aae70edc\",\n \"status\": 10\n}\n\n201 OK: The client order was successfully canceled. Returns the documentId and new status (\"10\") of the canceled order.
404 Not Found: The requested resource does not exist.
\n422 Unprocessable Entity: The request body contains invalid data.
\n400 Syntax Error: The request has incorrect format or syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\nThis endpoint is used to retrieve detailed information about a specific client order by its documentId.
Method: GET
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/orders/{documentId}/details
No request body. All filters are passed as query parameters.
\npage (integer, optional): Page number (each page returns up to 25 records).
\ndocumentIds[] (string[], optional): List of inbound plan IDs.
\nexternalNumbers[] (string[], optional): List of inbound plan external numbers.
\nwarehouseIds[] (string[], optional): List of warehouse codes.
\nstartDate (string, ISO 8601, optional): Start date of search (e.g. 2025-05-05T00:00:00Z).
endDate (string, ISO 8601, optional): End date of search (e.g. 2025-05-10T00:00:00Z).
Note: If no filter parameters are provided, the response returns the most recent inbound plans.
\ndocumentId (string): Unique identifier of the order.
\nexternalNumber (string): External (client-side) order number.
\nitems (array of objects): List of ordered items.
\nobjectId (string): Unique identifier of the product.
\nsku (string): Product SKU.
\nmeasureUnitName (string): Unit of measurement (e.g., pcs, box).
\nplannedQuantity (integer): Planned quantity.
\nactualQuantity (integer): Actually shipped quantity.
\ncondition (integer): Product condition, where 0 = Good, 1 = Defective.
series (array): List of serial numbers.
\n{\n \"documentId\": \"22be2de9-47ae-4438-9cec-d55a0d4bd387\",\n \"externalNumber\": \"27062025-07\",\n \"items\": [\n {\n \"objectId\": \"08c6c4c9-3258-11f0-befc-42010ade0e9e\",\n \"sku\": \"Regression4_1\",\n \"measureUnitName\": \"шт.\",\n \"plannedQuantity\": 1,\n \"actualQuantity\": \"1\",\n \"condition\": 0,\n \"series\": []\n }\n ]\n}\n\n201 OK: Data successfully retrieved. The response returns the full breakdown of the order matching the query.
\n404 Not Found: The requested resource does not exist.
\nThis endpoint is used to update the parameters of an existing client order that is currently in status \"13\" (Incomplete).
The request allows modifying general order parameters, the list of items, and—if delivery is via Nova Post—setting or updating the Waybill Number.
Method: PATCH
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/orders/{documentId}
Only the fields that need to be updated should be included in the request body.
\nNote: All fields are optional, but at least one field must be provided to perform the update.
\ndestWarehouse (string): Code of the warehouse for dispatch.
\ndeliveryType (integer): Delivery type: 2 – Nova Post, 5 – Pickup.
waybilNumber (string): Waybill number (required if deliveryType = 2).
additionalInfo (string): Additional info or comment.
\ndetails (array): Array of items included in the order.
\nobjectId (string): Goods ID. UUID.
\nquantity (integer): Quantity of goods.
\nprice (float): Goods price.
\nsum (float): Total amount per goods.
\n{\n \"destWarehouse\": \"Boyarka\",\n \"deliveryType\": 5,\n \"additionalInfo\": \"Update Info\",\n \"details\": [\n {\n \"objectId\": \"04adcd98-edd5-4428-9106-e6f43544d683\",\n \"quantity\": 48,\n \"price\": 15.5,\n \"sum\": 34.5\n }\n ]\n}\n\nReturns the updated client order object with its current parameters:
\nstatus (string): Status of the order (\"13\" = Incomplete).
destWarehouse (string): Code of the warehouse for dispatch.
\nadditionalInfo (string): Additional notes or comments.
\ndeliveryType (integer): Type of delivery (2 = Nova Post, 5 = Pickup).
waybilNumber (string): Waybill number; required if deliveryType is 2.
details (array): List of product items in the order.
\nobjectId (string, UUID): Goods ID.
\nquantity (integer): Quantity of goods.
\nprice (float): Price per unit (precision up to 2 decimal places).
\nsum (float): Total amount per goods.
\n{\n \"status\": \"13\",\n \"destWarehouse\": \"MAIN\",\n \"additionalInfo\": \"Update Info\",\n \"deliveryType\": 5,\n \"waybilNumber\": null,\n \"details\": [\n {\n \"objectId\": \"1b34e39f-5805-4510-94ca-1d88ea14739a\",\n \"quantity\": 2,\n \"price\": 10.5,\n \"sum\": 30.5\n },\n {\n \"objectId\": \"04adcd98-edd5-4428-9106-e6f43544d683\",\n \"quantity\": 48,\n \"price\": 15.5,\n \"sum\": 34.5\n }\n ]\n}\n\n201 OK: The client order was successfully updated. The response contains the updated order object.
\n404 Not Found: The requested resource does not exist.
\n422 Unprocessable Entity: The request body contains invalid data.
\n400 Syntax Error: The request has incorrect format or syntax.
\n403 Authorization Error: Access to the resource is forbidden.
\nThis method is used to delete one or more product items from a client order that is currently in status \"13\" (Incomplete).
If an item with insufficient stock is removed from such an order, its status is automatically changed to \"1\" (New).
This request allows updating the order and sending it for processing without creating a new document.
Method: POST
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/pl/orders/{documentId}/details/multiple-delete
Only the items that need to be deleted should be included in the request body.
\ndetails (array): Array of items to be deleted from the order.
\n{\n \"details\": [\n {\n \"objectId\": \"1b34e39f-5805-4510-94ca-1d88ea14739a\"\n }\n ]\n}\n\ndocumentId (string): Unique identifier of the client order.
\nstatus (integer): Current status of the client order (e.g. 13 – Incomplete).
{\n \"documentId\": \"7921dccd-9004-472e-a410-c9573a5edadd\",\n \"status\": 13\n}\n\n201 OK: The client order was successfully updated. Returns the updated order detail object.
\n422 Unprocessable Entity: The data in the request body is invalid (validation errors).
\n400 Bad Request: The request has an incorrect format or invalid syntax.
\nThis method is used to retrieve information on current stock remains of goods in the fulfillment warehouse(s). It allows the client to see how many units of each goods are available or reserved.
\nMethod: GET
URL: https://api-stage.novapost.pl/v.1.0/fulfillment/{countrycode}/stock-remains
Request body is not used. All filters are provided as query parameters.
\npage (integer): Page number (each page returns up to 25 records).
\nobjectIds[] (string[]): List of goods IDs to filter by (specific products by UUID).
\nobjectArts[] (string[]): List of product article numbers (SKUs) to filter by.
\nobjectTitle[] (string[]): List of product names to filter by.
\nwarehouseIds[] (string[]): Warehouse codes to filter (if empty, all warehouses).
\nremainDate (string): Date up to which to consider all receipts (inventory as of this date). Format: YYYY-MM-DD or full ISO timestamp. If provided, stock will be calculated as of that date/time.
condition (string): Filter by condition of stock:
0 – good (saleable) stock, 1 – damaged (unsaleable) stock. If omitted, all conditions are included.
Note: If no filters are provided, the response returns all stock remains for the client’s goods across all warehouses. Invalid filters are ignored (no error for unknown SKUs, etc., the result will just exclude those).
\ngoodsStock (array): Array of stock entries per goods and warehouse.
\nobjectId (string): Unique identifier of the product.
\nsku (string): Product SKU.
\nmeasureUnitName (string): Unit of measurement (e.g., pcs).
\nquantity (integer): Total quantity in stock.
\nreservedQuantity (integer): Quantity reserved in active orders.
\navailableQuantity (integer): Quantity available (excluding reserved).
\ndestWarehouse (string): Warehouse code.
\nexpiryDate (string): Expiry date in ISO 8601 format (e.g., 2025-05-05T00:00:00Z).
page (integer): Current page number of the paginated response.
\npages (integer): Total number of pages in the response.
\n{\n \"goodsStock\": [\n {\n \"objectId\": \"04adcd98-edd5-4428-9106-e6f43544d683\",\n \"sku\": \"RestRegression-02\",\n \"measureUnitName\": \"шт\",\n \"quantity\": 150,\n \"availableQuantity\": 149,\n \"reservedQuantity\": 1,\n \"destWarehouse\": \"War-FF\",\n \"expiryDate\": \"2025-12-31\"\n },\n {\n \"objectId\": \"04adcd98-edd5-4428-9106-e6f43544d683\",\n \"sku\": \"RestRegression-02\",\n \"measureUnitName\": \"шт\",\n \"quantity\": 150,\n \"availableQuantity\": 149,\n \"reservedQuantity\": 1,\n \"destWarehouse\": \"000063146\",\n \"expiryDate\": \"2025-12-31\"\n }\n ],\n \"page\": 1,\n \"pages\": 1\n}\n\nThis section provides an introduction to the Fulfillment REST API documentation, including its purpose. The Fulfillment API enables external clients to interact with Nova Post's fulfillment warehouse management system, allowing them to create inbound delivery plans and outbound shipment orders for goods.
\nBase URL …/v.1.0/fulfillment/{countrycode} (e.g. https://api.novapost.com/v.1.0/fulfillment/pl/)
The system includes key resources that represent the main entities and processes of the fulfillment system. These include:
\ngoods — products (each good has a unique SKU, unit of measure, price, etc.).
\nbarcodes — product barcodes
\nplan-inbounds — inbound delivery plans
\norders — customer orders
\nstocks — warehouse stock levels
\nThese resources cover core business processes: inventory management, supply handling, order processing, and stock tracking.
\nEach of the listed resources supports its own set of CRUD operations, enabling full automation of fulfillment processes for the client.
\n","_postman_id":"9cb7ef5c-ebdf-4c94-9c73-ed0b49bf06af","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}}}],"id":"131458dd-ef86-41db-a09e-4b8e4df5eb90","description":"Folder contains Customer API methods for NovaPost Test environment:
\nhttps://api-stage.novapost.pl/v.1.0
\nMain Sections:
\nAuthorization
\nDictionaries
\nServices
\nShipments
\nPickups
\nWebhooks
\nRegisters
\nPlease proceed with request in Authorization folder to generate a temporary JWT-token first, in order to run allfurther requests in collection for Stage environment.
\n","_postman_id":"131458dd-ef86-41db-a09e-4b8e4df5eb90","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","id":"e4250ffc-f0d7-46cb-927d-7145dbf99886","name":"NovaPost Client API","type":"collection"}}}],"auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"Authorization"},{"key":"value","value":""}]}},"event":[{"listen":"prerequest","script":{"id":"c4262279-8ad0-4f83-a915-64ca16d5088f","type":"text/javascript","packages":{},"exec":[""]}},{"listen":"test","script":{"id":"58dfd0d4-6cf4-478f-a45f-2e0e25f3ca15","type":"text/javascript","packages":{},"exec":[""]}}],"variable":[{"key":"apiKey","value":""},{"key":"jwt","value":""}]}