Working With Nova Poshta API

Working with Nova Poshta API
TABLE OF CONTENTS
Working with Nova Poshta API ……………………………………………………………………………………......................................2
The Cities Directory …....……………………………………………………………………………….……………………………......3
The Warehouses Directory ……………………………………………………………………………….………………………….…..6
The Settlements Directory ……………………………………………………………………………………………………………...10
The Directory of streets in the Settlements …………………………………………………………………………………........14
Online search in Directories ………………………………………………………………………………………………………………..…17
Online search in the Settlements Directory ……………………………………………………………………………………………..17
Online search of streets in the Settlements Directory ……………………………………………………………………………….…19
API methods for receiving data about a Sender ……………………………………………………………………………………………..22
Getting a Ref identifier of a Sender ……………………………………………………………………………......................................22
Getting a Ref identifier of the Sender’s contact person ………………………………………………………………………………...24
Creation of the Sender’s address (if shipment is made from the address) …………………………………………………………..…25
Getting the Sender’s Addresses Directory ……………………………………………………………………………………………....27
Formation of the request to create an invoice ……………………………………………………………………………………………....29
Create an invoice for a Nova Poshta parcel terminal ………………………………………………………………………………………..40
Editing of the created invoice ………………………………………………………………………………………………………………..42
Partial invoice editing …………………………………………………………………………………………………………………....45
Working with registries ……………………………………………………………………………………………………………………….46
Limitations when working with registries ……………………………………………………………………………………………….51
Getting a printed form of the registry …………………………………………………………………………………………………..52
Getting printed forms of express invoices and labels ………………………………………………………………………………………..53
Getting printed form of express invoice ………………………………………………………………………………………………...53
Getting printed forms of labels ………………………………………………………………………………………………………….54
Tracking ………………………………………………………………………………………………………………………………………..55
Current tracking statuses ………………………………………………………………………………………………………………..56

API (application programming interface) is a toolkit for work automation with Nova Poshta. API functionality
allows to quickly integrate logistics processes into any business and is a single entry point for all clients and
services.
API key - to start your work with the Nova Poshta API functionality, you need to generate an API key and use it
when creating a request. The key can be generated in the Personal Cabinet menu.
Request format - the data exchange with API is carried out via the HTTPS protocol using the POST or GET methods
of transmitting data to the entry point, depending on the type of XML or JSON request.
Entry points:
JSON - https://api.novaposhta.ua/v2.0/json/
XML - https://api.novaposhta.ua/v2.0/xml/
2
Working with directories
The Cities Directory, the Nova Poshta Warehouses Directory, the Settlements Directory are the main directories that
are used in the Nova Poshta. The Streets Directory can also be used.
The Cities Directory

The "getCities" method works in the "Address" model; this method loads the directory of the Ukrainian cities with
Nova Posta post offices.
If we add to this request the parameter “FindByString” (search by strings) and write the name of the needed
settlement (e. g. Brovary) in its properties, we will get a request, which will help identify this settlement in the Cities
Directory.
"methodProperties": {
"FindByString": "Бровари"
3
A request example with a Response structure
minimal set of parameters
{ { A city name in Ukrainian

"modelName": "Address", "Description": "Київ",
"calledMethod": "getCities", "DescriptionRu": "Киев", A city name in Russian
"methodProperties": { }, "Ref": "8d5a980d-391c-11dd-90d9-001a92567626",
"apiKey": "" "Delivery1": "1",
} "Delivery2": "1",
"Delivery3": "1", A Ref identifier of the city
"Delivery4": "1",
"Delivery5": "1",
"Delivery6": "1",
"Delivery7": "0",
"Area": "71508131-9b87-11de-822f-000c2965ae0e",
"SettlementType": "563ced10-f210-11e3-8c4a-0050568002cf",
"IsBranch": "1",
"PreventEntryNewStreetsUser": null,
4
"Conglomerates": [
"d4771ed0-4fb7-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac",
"f86b75e9-42f4-11e4-91b8-2f592fe1dcac"
],
"CityID": "4",
"SettlementTypeDescription": "місто",
"SettlementTypeDescriptionRu": "город",
"SpecialCashCheck": 1
},
5
Use the Ref identifier of a city from the Company Cities Directory, downloaded by "getCities" request. The Ref identifier
of the city will be indicated in the sender’s data block in the CitySender parameter of the API request for creating an
express invoice (hereinafter the invoice).
The Warehouses Directory

The "getWarehouses" method works in the "Address" model; this method loads the actual Nova Poshta Warehouses
Directory.
Example:
It is possible to filter warehouses by the following features:
1) TypeOfWarehouseRef - the Ref identifier of the warehouse type; "TypeOfWarehouseRef":"9a68df70-0267-42a8-bb5c-
37f427e36ee4",
2) CityName - the city name according to the Cities Directory; ""CityName":"Київ"
"CityRef": "20982d74-9b6c-11e2-a57a-d4ae527baec3",
3) CityRef - the Ref identifier of the city according to the Cities Directory. }
It is also possible to get data on warehouses in a particular settlement by the Ref identifier of the settlement received
through the getSettlements method.
Example:
"SettlementRef": "e71629ab-4b33-11e4-ab6d-005056801329" // the Ref identifier of settlement from the
Settlements Directory 6
A request example for getting the Response structure for request with descriptions of parameter values
Nova Poshta Warehouses Directory
A warehouse
1 description in
{ Ukrainian
{
"modelName": "Address", "SiteKey": "105", A warehouse
"calledMethod": 2 description in Russian
"getWarehouses", 1 "Description": "Відділення №1: вул. Пирогівський шлях, 135",
"methodProperties": { }, 2 "DescriptionRu": "Отделение №1: ул. Пироговский путь, 135", A short address in
"ShortAddress": "Київ, Пирогівський шлях, 135", 3
"apiKey": "" 3 Ukrainian
} "ShortAddressRu": "Киев, Пироговский путь, 135",
4 "Phone": "380800500609", 4
A short address in
Russian
"TypeOfWarehouse": "9a68df70-0267-42a8-bb5c-37f427e36ee4",
5 "Ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf", 5
A Ref identifier of the
"Number": "1", warehouse type
6
7 "CityRef": "8d5a980d-391c-11dd-90d9-001a92567626", A Ref identifier of the
6 warehouse
8
7 A warehouse number
An identifier of the
8 city according to the
Cities Directory
(getCities)
7
A settlement type
9
A city name1in Ukrainian 9 "CityDescription": "Київ", according to the
according to1the Cities
10
"CityDescriptionRu": "Киев", 15 Settlements
Directory (getCities) "SettlementRef": "e718a680-4b33-11e4-ab6d-005056801329", Directory
11 (getSettlements)
A city name in Russian "SettlementDescription": "Київ",
12 "SettlementAreaDescription": "Київська",
10 according to the Cities An availability of the
Directory (getCities) 13 "SettlementRegionsDescription": "", PostFinance cash
16
14 "SettlementTypeDescription": "місто", desk (1=yes/0=no)
A Ref identifier of the
15 "Longitude": "30.542884000000000",
11 settlement according to the "Latitude": "50.354786000000000", An availability of
Settlements Directory POS-terminal at the
(getSettlements) "PostFinance": "1", 17
warehouse
"BicycleParking": "1", (1=yes/0=no)
A settlement name according 16 "PaymentAccess": "1",
12 to the Settlements Directory "POSTerminal": "1", A possibility of
(getSettlements) "InternationalShipping": "0", processing an
18
17
"SelfServiceWorkplacesCount": "0", international
An area name for a
settlement according to the
"TotalMaxWeightAllowed": 0, shipping
18
13 Settlements Directory "PlaceMaxWeightAllowed": "1100",
The maximum
(getSettlements) 19 package weight (if it
19
“0” – there is no
A region name for a 20
restrictions)
14 settlement according to the
Settlements Directory The maximum
(getSettlements) 20
weight for one 8
package place
21 "Reception": {
"Monday": "08:00-22:00",
"Tuesday": "08:00-22:00", The package reception
"Wednesday": "08:00-22:00", 21
"Thursday": "08:00-22:00", schedule
"Friday": "08:00-22:00",
"Saturday": "08:00-19:00", To the day delivery
"Sunday": "09:00-18:00" 22
}, schedule
"Delivery": {
22
"Monday": "08:00-18:00", Warehouse working
"Tuesday": "08:00-18:00", 23
"Wednesday": "08:00-18:00", schedule
"Thursday": "08:00-18:00",
"Friday": "08:00-18:00",
"Saturday": "08:00-18:00",
"Sunday": "09:00-16:00"
},
"Schedule": {
23 "Monday": "08:00-19:00",
"Tuesday": "08:00-22:00",
"Wednesday": "08:00-22:00",
"Thursday": "08:00-22:00",
"Friday": "08:00-22:00",
"Saturday": "08:00-19:00",
"Sunday": "09:00-18:00"
},
"DistrictCode": "в1",
"WarehouseStatus": "Working",
"CategoryOfWarehouse": "Branch",
"Direct": ""
},…
9
Out of the Warehouses Directory, downloaded on the getWarehouses request, you need to use the Ref identifier of a
warehouse (Ref field in the response) which can be specified in the API request to create an invoice:
- in the sender’s data block in the SenderAddress parameter (if a shipment is made from the Nova Poshta
warehouse);
- in the recipient’s data block in the RecipientWarehouseRef parameter (if a delivery is made to the Nova
Poshta warehouse, and the warehouse is indicated as a ref identifier).
A warehouse number (the Number field in the response) could be used in the recipient’s data block in the
RecipientAddressName parameter (if a delivery is made to the Nova Poshta warehouse, and the warehouse is indicated
as a string (warehouse number), not as ref identifier.
The Settlements Directory

The «getSettlements» method allows downloading the Settlements Directory of Ukraine where Nova Poshta delivers
the load to both warehouses and addresses. The method returns no more than 150 entries per page.
To download the full directory page by page, use the parameter "Page": "1" as a loop; the loop's ending condition
would be a void in the data block. 10
Also, the method allows searching by string, provided the FindByString parameter is specified for it. Important! Search
is possible only in Ukrainian.
Example:
"FindByString": "Бровари"
}
Keep a copy of the directories on the client side and keep it up to date. It is recommended to update directory weekly.
The parameter in the response "Warehouse": "1 or 0" indicates the presence of Nova Poshta warehouses in the
settlement.
11
Request example Response snippet for a request with parameter values description
A Ref identifier of a
1 settlement
{ { A ref identifier of a
"modelName": 1 "Ref": "e71f7424-4b33-11e4-ab6d-005056801329", 2 settlement type
"AddressGeneral", 2 "SettlementType": "563ced10-f210-11e3-8c4a-0050568002cf", A settlement name in
"calledMethod": "Latitude": "48.330028000000000", 3 Ukrainian
"getSettlements", "Longitude": "30.232109000000000",
"methodProperties": { 3 "Description": "Благовіщенське", 4
A settlement name in
"Page": 1 4 "DescriptionRu": "Благовещенское", Russian
}, 5 "SettlementTypeDescription": "місто", A settlement type in
"apiKey": "" "SettlementTypeDescriptionRu": "город", 5
6 Ukrainian
} "Region": "e4b0d307-4b33-11e4-ab6d-005056801329",
7
"RegionsDescription": "Благовіщенський р-н", A settlement type in
8 "RegionsDescriptionRu": "Благовещенский р-н", 6 Russian
9
7 A ref identifier of a
region
8 A region name in
Ukrainian
12
9 A region name in
Russian
1 10 "Area": "dcaadbf9-4b33-11e4-ab6d-005056801329",
1 11
"AreaDescription": "Кіровоградська область",
"AreaDescriptionRu": "Кировоградская область", 10 A ref identifier of an
12 area
"Index1": "26400",
13 An area name in
"Index2": "26400", 11 Ukrainian
14 "IndexCOATSU1": "3525510100",
"Delivery1": "1", An area name in
12
"Delivery2": "1", Russian
"Delivery3": "1", 13 A postcode from
"Delivery4": "1",
"Delivery5": "1", 14 A postcode to
"Delivery6": "0",
An availability of the
"Delivery7": "0", Nova Poshta
"SpecialCashCheck": 1, 15 warehouses in this
"Warehouse": "1" settlement
},
15
13
Out of the Settlements Directory, downloaded on the getSettlements request, you need to use the ref identifier of a
settlement which can be specified in the RecipientCityRef parameter of the recipient’s datablock in the API request to
create an invoice.
If the data about the Recipient's settlement is transmitted not as a ref-identifier, but as strings, then in the API request
to create an invoice there will be used the values taken from such parameters as the Description, RegionsDescription,
AreaDescription, SettlementTypeDescription. In the request for creating an Internet Document these will be,
respectively, "RecipientCityName", "RecipientAreaRegions", "RecipientArea", "SettlementType" parameters.
The Directory of streets in the Settlements
The «getSettlements» method allows downloading the Directory of streets in a settlement. In the SettlementRef
parameter need to pass a ref-identifier of a settlement according to Settlements Directory (getSettlements).
To download the full directory page by page, use the parameter "Page": "1" as a loop; the loop's ending condition
will be a void in the data block.
14
Request example Response snippet for a request with parameter values description
{ {
"apiKey": "", "Description": "1-го Травня", A street name in
"DescriptionRu": "1-го Мая", 1 Ukrainian

"modelName": "Address",
"Ref": "c502d906-4bbe-11e4-ab6d-005056801329",
"calledMethod": 1 "StreetsType": "вул.", A street name in
"getSettlementStreets", 2 "StreetsTypeRef": "0f1d7fbb-4bba-11e4-ab6d-005056801329" 2 Russian
3 A Ref identifier of a
"SettlementRef": "e716f975- },
3 street
4b33-11e4-ab6d-005056801329"
}
}
15
Out of the Streets Directory, downloaded on the getSettlementStreets request, you need to use the ref identifier of a
street (Ref field in the response above) which can be specified in the RecipientStreetRef parameter of the recipient’s
data block in the API request to create an invoice (if a delivery is made to the address, and the street is indicated as a
ref identifier, not as a string).
16
Online search in Directories
Online search in the Settlements Directory
The “searchSettlements” method works in the “Address” model; this method is necessary for the online search of
settlements. To execute a search, the CityName parameter accepts the settlement name in Ukrainian or the
settlement postcode.
Request example Response snippet for request 1
A settlement
description
A number of Nova
{ { 2 Poshta warehouses in
this settlement
"apiKey": "ВАШ КЛЮЧ", "Present": "м. Київ, Київська обл.",
"modelName": "Address", 1 "Warehouses": 705, A settlement name in
"calledMethod": "MainDescription": "Київ", 3 Ukrainian according
2
"searchSettlements", "Area": "Київська", to the Settlements
3 "Region": "", Directory
"CityName": "київ" 4 A settlement area in
} 5 4 Ukrainian according
} to the Settlements
Directory
A settlement region in
5 Ukrainian according
to the Settlements
Directory 17
6 "SettlementTypeCode": "м.",
7
"Ref": "e718a680-4b33-11e4-ab6d-005056801329",
"DeliveryCity": "8d5a980d-391c-11dd-90d9-001a92567626",
8 "StreetsAvailability": true,
"ParentRegionTypes": "область",
"ParentRegionCode": "обл.",
"RegionTypes": "",
"RegionTypesCode": "" 6 An abbreviated name
of a settlement type
},
A settlement ref
7 identifier according to
the Settlements
Directory
A city ref identifier

8 from the getCities
Directory, from which
delivery to this
settlement is carried
out
18
Out of the response to request on searchSettlements method, you need to use the ref identifier of a settlement
(the Ref field in the response) which can be specified in the RecipientCityRef parameter of the recipient’s data block
in the API request to create an invoice.
If the data about the Recipient's settlement is transmitted not as a ref-identifier, but as strings, then the request for
creating an invoice via API will use the values taken from such parameters as the MainDescription, Area, and
Region. In the request for creating an Internet Document there will be, respectively, "RecipientCityName",
"RecipientArea", "RecipientAreaRegions" parameters.
Online search of streets in the Settlements Directory
The “searchSettlementStreets” method works in the “Address” model; this method is necessary for the online
search of streets . The search is performed in Ukrainian by the street name (or first letters of the name).
19
Request example Response snippet for request A Ref identifier of a

settlement
according to the
Settlements
3 Directory
{ {
"apiKey": "7d297a6b5cb76d92e8a90378032b3c1c", "SettlementRef": "e718a680-4b33-11e4-ab6d-005056801329", A ref identifier of
"modelName": "Address", "SettlementStreetRef": "a922cfc4-6848-11e6-8304-00505688561d",4 a street
3"SettlementStreetDescription": "Шолуденко",
"calledMethod": "searchSettlementStreets", 4"Present": "вул. Шолуденко",
"methodProperties": { A street name in
"StreetName": "шолуденк", 5 "StreetsType": "0f1d7fbb-4bba-11e4-ab6d-005056801329", Ukrainian
5
6 "StreetsTypeDescription": "вул.",
1 "SettlementRef": "e718a680-4b33-11e4-ab6d- "Location": [
005056801329", 7 50.452941991388997, A street
2"Limit": 50 8 30.478049917147001 description in
6
} 9 ], Ukrainian
} "SettlementStreetDescriptionRu": "Шолуденко"
} A ref identifier of
7
the street type
11 A street name for a searching 1
A street name for searching 0 8 An abbreviated
A ref identifier of a settlement name of a street
2A Ref identifier of settlement
according to the Settlements 9 type
according to the Settlement
Directory
Directory 1 Coordinates
0 20
A street name in
Out of the response to the searchSettlementStreets request, you need to use the Ref identifier of a street (the
SettlementStreetRef field in the response above) which can be specified in the RecipientStreetRef parameter of the
recipient’s data block in the API request to create an invoice (if both a delivery to the address and the street are
passed as a ref identifier, not as a string).
21
API methods for receiving data about a Sender

In the API request to create an invoice, the data about a Sender can be specified as a Ref identifier. As a rule, the
Sender’s data block in the API request to create an invoice is not often changed.
Getting a Ref identifier of a Sender
To the personal account (Personal Cabinet), a Sender is automatically pulled from our information system.
To get a Ref identifier of a Sender (Senders), you need to use the “getCounterparties” method (works in the
“Counterparty” model) with the “Sender” counterparty type.
22
Request example Response request
{ {
"apiKey": "[ВАШ КЛЮЧ]", "Description": "СОнечКО ТОВ",
"modelName": "Counterparty", "Ref": "39ab7d9d-61d1-11e9-9937-005000801c6b", A short name of a
"calledMethod": "getCounterparties", 1"City": "00000000-0000-0000-0000-000000000000", 1 sender
"methodProperties": { 2 "Counterparty": null,
"CounterpartyProperty": "Sender" "FirstName": "", A Ref identifier of a
} "LastName": "", 2 sender
} "MiddleName": "",
"CounterpartyFullName": A full name of a
"ТОВАРИСТВО З ОБМЕЖЕНОЮ ВIДПОВIДАЛЬНIСТЮ \" СОнечКО\"", 3 sender
"OwnershipFormRef": "7f0f351d-2519-11df-be9a-000c291af1b3",
3 "OwnershipFormDescription": "ТОВ",
"EDRPOU": "36049009",
"CounterpartyType": "Organization",
"CityDescription": ""
}…
23
Use a Ref identifier of a Sender from the response on the request above in the “Sender” parameter in the API
request to create an invoice.
Getting a Ref identifier of the Sender’s contact person

The Sender’s contact persons are either automatically pulled into a personal account from our information system,
or (for corporate clients) can be created in the Personal Cabinet or through an API method.
To get the list of the Sender’s contact persons, you need to use the “getCounterpartyContactPerson” method
(works in the “Counterparty” model).
Request example Response snippet
{ …{ A full name of a contact

"apiKey": "ВАШ АПИ-КЛЮЧ", "Description": "Пономаренко Юлія Юріївна", person
"modelName": "Counterparty", "Phones": "380500000000",
"calledMethod": "getCounterpartyContactPersons", "Email": "", A Ref identifier of a contact
"methodProperties": { "Ref": "d9dcbe00-cc88-11e8-8b24-005056881c6b",
person
"Ref": "39ab7d9d-61d1-11e9-9937-005000801c6b ", "LastName": "Пономаренко",
"Page": "1" "FirstName": "Юлія",
} "MiddleName": "Юріївна"
} }
],
A Ref identifier of a Sender 24
In the API request to create an invoice, the data about a Sender can be specified as a Ref identifier. As a rule, a Sender’s
data block in the API request to create an invoice is not often changed.
You need to use a Ref identifier (the Ref field in response above) of a contact person in ContactSender parameter in the
API request to create an invoice.
Creation of the Sender’s address (if shipment is made from the address)
You can create the Sender's address in your Personal Account (then get the Ref identifier of the address through the API
method) or via the API using the request to create the address.
To create the Sender’s address (if shipment is made from the address), you need to use the request below:
{
"modelName": "Address",
"calledMethod": "save", 1 A Ref identifier of a counterparty-sender
"methodProperties": { 2 A Ref identifier of a street* (see the note below)
"CounterpartyRef": "5ace4a2e-13ee-11e5-add9-005056887b8d", 3 A building number
1"StreetRef": "d4450bdb-0a58-11de-b6f5-001d92f78697", 4
2 A comment to the address (if necessary)
"BuildingNumber": "7",
3"Flat": "2",
*(Note) Request for getting a Ref identifier of a street
"Note": "Комментарий"
4}, (Attention: In the request below through the getStreet
method, a search of a street is performed by Ref identifier
"apiKey": "ВАШ КЛЮЧ"
of a city according to getCities directory). 25
}
You need to use the received Ref identifier of a street in the request to
create the Sender’s address.
{
"modelName": "Address", Response snippet on the request to create a Sender’s address
"calledMethod": "getStreet",
"methodProperties": { …{
"Ref": "e57f8afb-55f1-11e5-ad08-005056801333",
1 "CityRef": "8d5a980d-391c-11dd-90d9- "Description": "Львівська вул. 7 кв. 2 Комментарий"
001a92567626", }…
2 "FindByString": "львівськ"
}, A Ref identifier of a created Sender’s address
"apiKey": ""
}
1A Ref identifier of a Sender’s The received Ref identifier of a Sender’s address, you need to use in API
City according to the
request to create an invoice in the SenderAddress parameter (if
getCities directory
shipment is made from an address, not from the Nova Poshta
2A search of a street by name warehouse).
26
Getting the Sender’s Addresses Directory
If several addresses of a shipment have been created for a Sender, you can receive data on all these addresses through
the API request using with the getCounterpartyAddresses method:
{ Response snippet
"apiKey": "",
"modelName": "Counterparty", …{
"calledMethod": "getCounterpartyAddresses", "Ref": "21463f65-a394-11e7-becf-005056881c6b",
"methodProperties": { 3 "Description": "Героїв Праці вул. 9",
"Ref": "123bf97c-3bba-11e7-80c8-005056887b8d", 4 "CityRef": "db5c88e0-391c-11dd-90d9-001a92567626",
5"CityDescription": "Харків",
1"CounterpartyProperty": "Sender", 6 "StreetRef": "a72a31de-416b-11dd-9198-001d60451983",
2"Page": 1 7 "StreetDescription": "Героїв Праці",
}
} 8 "BuildingRef": "b139ae5b-bf9e-11de-9a0e-000c2965ae0e",
"BuildingDescription": "9",
A Ref identifier of a sender 9 "Note": "",
1 1
0 "AddressName": "" 6 A city name in Ukrainian according to the getCities directory
1 },…
2 A sender is a type of a counterparty 1 A Ref identifier of a street (according to the getStreet directory (in
7 conjunction with the Cities Directory, downloaded by getCities
3 A Ref identifier of an address
method))
4 An address description
8 A street name in Ukrainian 9 A Ref of a building number
5 A Ref identifier of a city according to the 1 1 27
getCities directory 0 A building number 1 A note (comment) to the address
You need to use the received Ref identifier of a Sender’s address in the API request to create an invoice in the
SenderAddress parameter (if shipment is made from address, not from the Nova Poshta warehouse).
28
Formation of the request to create an invoice
To create an invoice via API, it is necessary to generate a request using the “save” method, which works in the
“InternetDocument” model. An API request will consist of a sender’s data block, a receiver’s data block, and
additional parameters characterizing the shipment.
The sender’s data block includes the following parameters:
"CitySender " a value is a ref-identifier of the sender's city
"Sender" a value is a ref-identifier of the sender
"SenderAddress" a sender’s address; a value is a ref of the sender's address (if a shipment is made from an
address) or a ref-identifier of the Nova Poshta warehouse (received from the directory via
getWarehouses method).
"ContactSender" a ref-identifier of a sender’s contact person
"SendersPhone": "380501234567" a telephone number of a sender’s contact person
29
The recipient’s data block (if a recipient is a private person) includes the following parameters:
"RecipientCityRef": "", a ref-identifier of a recipient’s city according to the getSettlements directory. A ref-identifier allows
you to uniquely identify the recipient’s city, without the need to transmit a city data as strings in
separate fields for the name, area, and region
"RecipientWarehouseRef": a ref identifier of a recipient’s warehouse according to the getWarehouses directory. A ref identifier
"", of warehouse allows you to uniquely to identify the warehouse. If a shipment is made to the
warehouse and the warehouse is specified as a ref identifier, there is no need to transmit data about a
recipient’s city
"RecipientCityName": "Київ", a recipient’s city name in Ukrainian as a string according to the getSettlements directory
"RecipientArea": "", an area name for a recipient’s city in Ukrainian as a string according to the getSettlements directory
"RecipientAreaRegions": "", a region name for a recipient’s city in Ukrainian as a string according to the getSettlements directory
"SettlementType": "", a settlement type in Ukrainian as a string according to the getSettlements directory
Pay Name, area, region parameters must be specified in Ukrainian in strict accordance with the
values taken from the directory, downloaded by the getSettlements request. A settlement type
attention is required if there are two or more settlements with the same name, but of different types 30
in
one area or region (e.g. “village” and “urban village”).
"RecipientAddressName": "", a value of this parameter is a street name in Ukrainian as a string (if a shipment is made to the
address) or a warehouse number (e.g. “1”) (if a shipment is made to the warehouse)
"RecipientHouse": "", the recipient’s building number, if a shipment is made to the address
"RecipientFlat": "", the recipient’s apartment number, if a shipment is made to the address
"RecipientType": "PrivatePerson", a recipient type; in this example, it is a private person
"RecipientName": "Петро Іванович the recipient’s name

Петренко",
"RecipientContactName": "Петро the name of the recipient’s contact person (for a private person, the RecipientName and
Іванович Петренко", RecipientContactName parameters are the same)
"RecipientsPhone": "380997979789" the recipient’s telephone number
31
Additional parameters
"NewAddress": "1", this parameter is required; with a value of "1" it specifies that in the request to create an
invoice the data about the recipient’s city is used according to the getSettlements directory,
and the recipient’s data is transmitted as strings
"DateTime":"" shipment creation date. If this parameter is not filled, the current date will be used
automatically
"PayerType": "Sender", the value of this parameter indicates the payer for the delivery service by Nova Poshta
(“Sender” - the payer is the sender, «Recipient» - the payer is the recipient)
"PaymentMethod": "Cash", the value of this parameter indicates, whether cash (Cash) or cashless payment (NonCash) will
be used to pay for the delivery services provided by Nova Poshta. It is necessary to note that
cashless payments are available to counterparties in accordance with the relevant terms of the
contract concluded with Nova Poshta
"ServiceType": a value of this parameter indicates a type of delivery. The parameter may have the following
"WarehouseWarehouse", values. WarehouseWarehouse: a delivery from and to a Nova Poshta warehouse;
WarehouseDoors: a delivery from a warehouse to an address; DoorsWarehouse: a delivery
from an address to a warehouse; DoorsDoors: a delivery from an address to an address
32
"CargoType": "Parcel", a cargo type, possible values: Parcel – up to 30 kg, Cargo – over 30 kg, Pallet – pallet, Documents –
documents (weight can be 0,1, 0,5 or 1 kg)
"VolumeGeneral": "", cargo volume, in cubic meters (m³)
"Weight": "5", weight in kg
"InfoRegClientBarcodes": "", a value of this parameter is the internal order number of the customer; this is an optional parameter
"SeatsAmount": "1", a number of places on the invoice
"Description": "Техніка", a cargo description
"AdditionalInformation": "", additional information about the shipment; this is an optional parameter
"Cost": "100", a declared value of a cargo
"AfterpaymentOnGoodsCost": payment control (COD), this financial service is provided according to the agreement with
"100" PostFinance. A value of this parameter is the amount of money that will be received from a Recipient
and transferred to the account of a Sender
33
Pay Descriptions of other parameters that can be used in the API request to create an invoice,
attention for example, to order additional services or to create a shipment for the recipient – legal
person (organization), will be provided separately, if necessary.
A few examples of API requests to create invoices, see below.

Please note that request examples contain arbitrary data. When testing requests, you need to substitute them with
the relevant values from the directories.
The following examples use the delivery type from the Nova Poshta warehouse. Entry point for requests in json
format - https://api.novaposhta.ua/v2.0/json/
1 The example of the API request to create an invoice to a warehouse (the warehouse is specified as a ref
identifier)
{
"apiKey": "fa10a61f0eb111ae306c6801923c111d",
"modelName": "InternetDocument",
"calledMethod": "save",
34
"CitySender": "db5c88f0-391c-11dd-90d9-001a92567626",
"Sender": "8d411ce5-cae2-11e8-8b24-005056881c6b",
"SenderAddress": "0d545f59-e1c2-11e3-8c4a-0050568002cf",
"ContactSender": "d9dcbe11-cc88-11e8-8b24-005056881c6b",
"SendersPhone": "380501234567",
"RecipientWarehouseRef": " 5a39e553-e1c2-11e3-8c4a-0050568002cf",
"RecipientType": "PrivatePerson",
"RecipientName": "Петро Іванович Петров",
"RecipientContactName": "Петро Іванович Петров",
"RecipientsPhone": "380991234567",
"NewAddress": "1",
"DateTime": "12.03.2020",
"PayerType": "Sender",
"PaymentMethod": "Cash",
"CargoType": "Parcel",
"VolumeGeneral": "0,02",
"Weight": "5",
"ServiceType": "WarehouseWarehouse",
"InfoRegClientBarcodes": "",
"SeatsAmount": "1",
"Description": "Техніка",
"AdditionalInformation": "",
"Cost": "100",
"AfterpaymentOnGoodsCost": "100"
}
35
}
The example of the API request to create an invoice to an address (the Recipient’s city is specified as a ref
2
identifier)
{
"ContactSender": "d9dcbe11-cc88-11e8-8b24-005056881c6b",
"SendersPhone": "380501234567",
"RecipientCityRef": "cf8498bf-4f80-11e4-ab6d-005056801329",
"RecipientAddressName": "Шевченка",
"RecipientHouse": "9",
"RecipientFlat": "1",
"RecipientContactName": "Петро Іванович Петров ",
"NewAddress": "1",
"DateTime": "12.03.2020",
"PaymentMethod": "Cash", 36
"Weight": "5",
"ServiceType": "WarehouseDoors",
"SeatsAmount": "1",
"Cost": "100",
}
}
The example of the API request to create an invoice to an address (the Recipient’s city is specified as string
3 values of parameters)
{
"ContactSender": "d9dcbe11-cc88-11e8-8b24-005056881c6b", 37
"SendersPhone": "380501234567",
"RecipientCityName": "Кононівка",
"RecipientArea": "Черкаська",
"RecipientAreaRegions": "Драбівський",
"SettlementType": "село",
"RecipientAddressName": "Нова",
"RecipientHouse": "1",
"RecipientFlat": "",
"RecipientContactName": "Петро Іванович Петров",
"NewAddress": "1",
"DateTime": "12.03.2020",
"PaymentMethod": "Cash",
"Weight": "5",
"ServiceType": "WarehouseDoors",
"SeatsAmount": "1",
"Cost": "100",
} 38
}
! The examples of other requests, and also the request examples in the xml format, can be additionally provided, if
necessary.
Response example on the request to create an invoice
If the request to create an invoice is successful, the response returns the following data:
{
"success": true,
"data": [ a ref identifier of the
1
{ created document
"Ref": "5a9fc8e1-643e-11ea-8513-b88303659df5", (invoice)
1
2 "CostOnSite": 55, 2
3 "EstimatedDeliveryDate": "13.03.2020", a price of delivery services
4 "IntDocNumber": "20450213886086",
3
"TypeDocument": "InternetDocument" estimated delivery date
}
], 4
a number of created
"errors": [], document (invoice)
"warnings": [],
"info": [],
"messageCodes": [],
"errorCodes": [],
"warningCodes": [],
"infoCodes": [] 39
Create an invoice for a Nova Poshta parcel terminal

To create an invoice for a Nova Poshta parcel terminal, in the API request on the “save” method (the “InternetDocument”
model) it is required to add the OptionsSeat data block with a description of the parameters (dimensions) of the parcel. All
other parameters of the API request to create an invoice are unchanged; the request is formed similarly to the ones for sending
to any Nova Poshta warehouse.
A parcel terminal could only be the recipient’s warehouse. The delivery type in the
Limitations ServiceType parameter must be specified as WarehouseWarehouse (from a warehouse
to a warehouse (parcel terminal)) or DoorsWarehouse (from an address to a
warehouse (parcel terminal)).
You can send to the parcel terminal the following types of cargo - Parcel (CargoType =
Parcel, weight of no more than 30 kg) and Documents (CargoType = Documents,
possible weight values (in the Weight parameter) - 0,1 or 0,5 or 1 kg).
When creating a shipment to the parcel terminal, you can specify only one place per
shipment (the SeatsAmount parameter with a value of “1”).
The maximum value of an estimated cost (the Cost parameter) is 6000 UAH.
Maximum permissible cargo dimensions: width 40 cm, length 58 cm, height 36 cm.
40
Example of the parcel dimensions data block

"OptionsSeat": [
eight": "5", 1
1
1 volumetricVolume": "", 1 weight in kg
2
2 "volumetricWidth": "10",
1 2 volume in cubic meters (m3) (this is an optional
3 parameter )
"volumetricHeight": "10",
2
4 3 width in cm, the maximum value is 40
"volumetricLength": "10"
5} 4 height in cm, the maximum value is 36
] 5
length in cm, the maximum value is 58
}
}
! The full examples of API requests to create shipments to a parcel terminal will be provided separately, if necessary.
41
Editing of the created invoice

You can edit a created invoice (an Internet Document) using the “update” method (it works in the “InternetDocument”
model).
Editing an Internet Document is possible only

Important
before printing it;
until it is transmitted to the Nova Poshta representatives for the actual shipment.
In the API request to edit, you must specify the Ref identifier of a created invoice (an Internet Document) and all the
same parameters that were used in the request by the “save” method. In doing so, the values of some parameters
can be changed, if necessary. As a result of the successful completion of the request, the changes made will be
written in the document. The response to the request contains the same Ref identifier of the document and
warnings about the changed parameters.
After a printout of an edited invoice or label, it is recommended to check that all shipment data is displayed correctly
in printed form.
42
Example of the API request for editing an invoice (an Internet Response example
Document)
{ {
"apiKey": "fa11a61f0eb111ae306c6801923c111d", "success": true,
"modelName": "InternetDocument", "data": [
{ a document’s Ref identifier
"calledMethod": "update", a Ref
(remains unchanged)
"Ref": "0a399341-68f4-11ea-8513-b88303659df5",
"methodProperties": { identifier of a
"Ref": "0a399341-68f4-11ea-8513-b88303659df5", "CostOnSite": 45,
created "EstimatedDeliveryDate": "19.03.2020",
document "IntDocNumber": "20450215534976",
"Sender": "8d111ce5-cae2-11e8-8b24-005056881c6b", "TypeDocument": "InternetDocument"
"SenderAddress": "0d545f59-e1c2-11e3-8c4a-0050568002cf", } a document number
"ContactSender": "d9dcbe00-cc88-11e8-8b24-005056111c6b", ], (remains unchanged)
"SendersPhone": "380501234567", "errors": [],
"RecipientCityName": "Київ", "warnings": [
"RecipientArea": "", "VolumeWeight is changed",
"RecipientAreaRegions": "", "VolumeGeneral is changed",
"SettlementType": "", "Weight is changed"
"RecipientAddressName": "3003", ],
"RecipientType": "PrivatePerson", "info": [],
"RecipientName": "Петро Іванович Іванов", "messageCodes": [],
"RecipientContactName": "Петро Іванович Іванов", "errorCodes": [],
43
"RecipientName": "Петро Іванович Іванов", "warningCodes": [
"RecipientContactName": "Петро Іванович Іванов", "30000200888",
"RecipientsPhone": "380997979789", "30000200889",
"NewAddress": "1", "30000200881"
"DateTime":"18.03.2020", ],
"PayerType": "Sender", "infoCodes": []
"PaymentMethod": "Cash", }
"VolumeGeneral": "",
"Weight": "0.5",
"ServiceType": "WarehouseWarehouse",
"SeatsAmount": "1",
"Description": "описание товара",
"Cost": "1000",
"AfterpaymentOnGoodsCost": "",
"OptionsSeat": [
{
"weight": "0,5",
"volumetricVolume": "",
"volumetricWidth":"15",
"volumetricHeight":"10",
"volumetricLength":"10"
}
]
}
}
! API request example above is using the arbitrary data.

Other requests examples, as well as examples of requests in 44
the xml format, will be provided separately, if necessary.
Partial invoice editing

Example request for partial editing
{
"apiKey": " fa11a61f0eb111ae306c6801923c111d",
"calledMethod": "updatePartial",
"Ref": "0a399341-68f4-11ea-8513-b88303659df5", a Ref identifier of the document to be edited
"Weight": "32" a parameter that needs to be changed
}
}
! The response to the request contains the same Ref identifier of the document (remains unchanged) and
information about the changed parameters.
45
Working with registries
To transfer the created shipments to the Nova Poshta representatives, it is necessary to create an invoice registry and print it in two
copies, for each shipment (for each invoice number) to print the labels.
You can create a registry of shipments in your Personal Cabinet or via an API request. In response to a request for a registry formation,
the registry number and numbers of shipments with the status of "added" or "not added" to the registry are returned.
Example of the API request to add documents to a new registry Example of the response to a request of adding documents to the registry
{ {
"apiKey" : "fa11a61f1eb144ae306c6801923c124d", "success": true, 1 a Ref identifier of the
"modelName" : "ScanSheet", "data": [ 1 created registry
"calledMethod" : "insertDocuments", a Ref identifier or 1 "Ref": "9e5c5270-6f58-11ea-8513-b88303650df5",
{

"methodProperties" : { a document 1 "Number": "105-11616927", 2 a number of the created
"DocumentRefs" : [ number "Date": "2020-03-26 13:54:59",
registry
"7f3bf6ff-6f58-11ea-8513-b88303650df5" 2 "Description": "",
3
] "Errors": [], 3 a date and time of
} "Success": [ creating registry
} {
"Ref":"7f3bf6ff-6f58-11ea-8513-b88303659df5", a ref identifier of the
4 document added to the
"Number": "20450217866047"
4} registry
],
5 a document number
5 added to the registry

46
"Warnings": [],
"Data": {
"Errors": [],
"Success": [],
"Warnings": []
}
}
],
"errors": [],
"warnings": [],
"info": [],
"messageCodes": [],
"errorCodes": [],
"warningCodes": [],
"infoCodes": []
}
Also, a document can be added to an existing registry; an example request:
{
"apiKey" : " fa11a61f1eb144ae306c6801923c124d",
"modelName" : "ScanSheet",
"calledMethod" : "insertDocuments",
"methodProperties" : {
"Ref" : "6d4e3fde-db61-11e8-8b24-005056881c6b",
"DocumentRefs" : [ a Ref identifier or a registry number
"5ed9e40f-db61-11e8-8b24-005056881c6b"
] a Ref identifier or a document number for adding to the registry
}
}
47
Example of the API request for receiving information on Example of the API request for receiving a list of registries
one registry
{
{ "modelName": "ScanSheet",
"modelName": "ScanSheet", "calledMethod": "getScanSheetList",
"calledMethod": "getScanSheet", "apiKey": " fa11a61f1eb144ae306c6801923c124d"
"methodProperties": { a Ref identifier or a }
"Ref": "105-04954010" registry number
},
"apiKey": " fa11a61f1eb144ae306c6801923c124d " The response returns information about all registries
} created in this account.
The response returns information on all invoices included

in the registry.
48
Example of the API request for deleting (disbanding) As a result of the successful completion of the request, the
the registry of shipments response returns information about the deleted registry:
If the registry was created but for some reason will not {
be used, it can be deleted. After the registry is deleted, "success": true,
the registry number is deleted from the Nova Poshta "data": {
information system, and the included invoices are "ScanSheetRefs": {
excluded from the registry but not deleted (the registry "Errors": [], a Ref identifier of the
is being disbanded). To delete the registry, you need to "Success": [ registry
create the appropriate request. {
"Ref": "1fa06b9f-6f59-11ea-8513-b88303659df5",
{
"Number": "105-11617067"
"modelName": "ScanSheet",
}
"calledMethod": "deleteScanSheet", a registry number
]
a Ref identifier or a registry }
"ScanSheetRefs": [ number },…
"105-04536404"
]
},
"apiKey": "fa11a61f1eb144ae306c6801923c124d"
}
49
Example of the API request to delete invoices from the registry

If invoices were added to the registry by mistake, they can be
deleted from there. In the request, you need to pass the ref
identifier or the document number to be deleted from the
registry. As a result of the successful completion of the request,
the document is deleted only from the registry, but is saved in
your account.
{
"modelName": "ScanSheet",
"calledMethod": "removeDocuments",
"DocumentRefs": [ a Ref identifier or a registry
"20450217866247" number
]
},
"apiKey": "fa11a61f1eb144ae306c6801923c124d"
}
50
Limitations when working with registries

Working with registries, you needs to address the following existing limitations:
Limitations You can add an Internet Document (invoice) to the registry if the Sender's data (city,
counterparty, and address) is identical for all shipments added to the registry.
An Internet Document (hereinafter the “ID”) can be added to the only one registry.
That is, the same document cannot be added to several registries at the same time.
An ID printed more than a day ago cannot be added to the registry (the print date is
earlier than yesterday compared to the date the registry was formed).
An ID can be added to the registry only before creating the invoice based on the ID
(i.e., before scanning this shipment in the Nova Poshta warehouse).
An invoice (Internet Document) marked for deletion cannot be added to the registry.
After receiving the printed registry, the addition of documents to it is blocked.
The recommended maximum number of invoices in one registry is 200.
51
Getting a printed form of the registry

You can get a printed form of the registry using a GET request by the number or Ref identifier of the registry. In the
requests below, you need to substitute the Ref identifier or registry number and your API key.
Request example to print the registry by registry Ref identifier

https://my.novaposhta.ua/scanSheet/printScanSheet/refs[]/7ed08016-89e6-11e5-a70c-005056801333/type/pdf/apiKey/YOUR API
KEY
Request example to print the registry by registry number

https://my.novaposhta.ua/scanSheet/printScanSheet/refs[]/105-00000595/type/pdf/apiKey/YOUR API KEY
52
Getting printed forms of express invoices and labels

Getting printed form of express invoice
You can get a file for printing by invoice number or Ref identifier.
1. Printing from a browser
To print by a Ref identifier of invoice; get request
https://my.novaposhta.ua/orders/printDocument/orders[]/ab91865b-2937-11e4-ab6d-005056801329/orders[]/
ab91865b-2937-11e4-ab6d-005056801329/type/pdf/apiKey/[YOUR KEY]
Instead of Ref, you can transfer the invoice number:

To print by an invoice number; get request
https://my.novaposhta.ua/orders/printDocument/orders[]/20600000002260/type/pdf/apiKey/[YOUR KEY]
2. Printing multiple invoices with a single request

https://my.novaposhta.ua/orders/printDocument/orders/20600000002310,20600000002309/type/pdf/apiKey/
[YOUR KEY]
53
Getting printed forms of labels
You can get the file for printing labels by the number or ref-identifier of the invoice.
A shipping label is placed on each place of shipment, if the client carries out receiving and sending of shipments by
registry.
Printing labels on a Zebra Printer

https://my.novaposhta.ua/orders/printMarking100x100/orders[]/ab91865b-2937-11e4-ab6d-005056801329/type/
pdf/apiKey/YOUR KEY/zebra
Instead of Ref, you can transfer the invoice number in the request
Printing multiple invoices by Ref on a Zebra Printer

https://my.novaposhta.ua/orders/printMarking100x100/orders/e3ffb9a6-a7d8-11e9-9937-005056881c6b,e3ffb9a6-
a7d8-11e9-9937-005056881c6b/type/pdf/zebra/zebra/apiKey/YOUR KEY
Instead of Ref, you can transfer the invoice number in the request.
54
Tracking
The “getStatusDocuments” method works in the “TrackingDocument” model and allows you to get extended
information about the shipment and its status at a given time. The method allows you to view up to 100 items
concurrently.
Example of API request for shipments tracking
{
"apiKey": "YOUR KEY",
"modelName": "TrackingDocument",
"calledMethod": "getStatusDocuments",
"Documents": [
{
"DocumentNumber": "an invoice number",
"Phone":"the sender’s or receiver’s telephone number, optional"
},
{
"DocumentNumber": "an invoice number",
"Phone": "the sender’s or receiver’s telephone number, optional"
}
]
}
}
55
Current tracking statuses
Code Status
1 Nova Poshta is waiting for receipt from a sender
2 Deleted
3 Number not found
4 Shipment in the Sender’s city
41 Shipment in the Sender’s city (the status for local standard and local express services - delivery is within the city)
5 Shipment goes to the Recipient's city
6 Shipment is in the Recipient’s city, an indicative delivery to the warehouse - XXX dd-mm. Expect an additional
message about arrival.
7, 8 Arrived at the warehouse.
9 Shipment is received
10 Shipment is received %DateReceived%. Within 24 hours, you will receive an SMS message about money transfer
and will be able to receive it at the cash desk of the New Poshta warehouse.
11 Shipment is received %DateReceived%. The money transfer is given to the Recipient.
56
14 Shipment is transmitted to Recipient for checkup

101 On the way to the Recipient
102, 103, Recipient's refusal
108
104 Address changed
105 Storage is stopped
106 Express invoice of return delivery is received and created
Pay The additional information and examples of API requests can be sent on Client’s
request. Also, information about working with Nova Poshta APІ is provided on the
attention
Developer Portal https://devcenter.novaposhta.ua/
57

Working With Nova Poshta API - Final

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Working With Nova Poshta API - Final

Uploaded by

Copyright:

Available Formats

Working with Nova Poshta API

The Cities Directory

{ { A city name in Ukrainian

The Warehouses Directory

The Settlements Directory

The Directory of streets in the Settlements

"DescriptionRu": "1-го Мая", 1 Ukrainian

A city ref identifier

Online search of streets in the Settlements Directory

Request example Response snippet for request A Ref identifier of a

API methods for receiving data about a Sender

Getting a Ref identifier of a Sender

Request example Response request

Getting a Ref identifier of the Sender’s contact person

{ …{ A full name of a contact

The sender’s data block includes the following parameters:

"CitySender " a value is a ref-identifier of the sender's city

"Sender" a value is a ref-identifier of the sender

"ContactSender" a ref-identifier of a sender’s contact person

"SendersPhone": "380501234567" a telephone number of a sender’s contact person

"RecipientType": "PrivatePerson", a recipient type; in this example, it is a private person

"RecipientName": "Петро Іванович the recipient’s name

"RecipientsPhone": "380997979789" the recipient’s telephone number

"VolumeGeneral": "", cargo volume, in cubic meters (m³)

"Weight": "5", weight in kg

"SeatsAmount": "1", a number of places on the invoice

"Description": "Техніка", a cargo description

"Cost": "100", a declared value of a cargo

A few examples of API requests to create invoices, see below.

Create an invoice for a Nova Poshta parcel terminal

Example of the parcel dimensions data block

Editing of the created invoice

Editing an Internet Document is possible only

! API request example above is using the arbitrary data.

Partial invoice editing

Also, a document can be added to an existing registry; an example request:

The response returns information on all invoices included

Example of the API request to delete invoices from the registry

Limitations when working with registries

Getting a printed form of the registry

Request example to print the registry by registry Ref identifier

Request example to print the registry by registry number

Getting printed forms of express invoices and labels

Instead of Ref, you can transfer the invoice number:

2. Printing multiple invoices with a single request

Printing labels on a Zebra Printer

Printing multiple invoices by Ref on a Zebra Printer

Example of API request for shipments tracking

14 Shipment is transmitted to Recipient for checkup

You might also like