Создание Интернет-документа

Самым важным сервисом API "Нова пошта" по праву считается создание интернет-документа.

В данной документации мы рассмотрим вариант создания интернет-документа через получение идентификатор (REF) контрагентов и адресов.


Интернет-документ состоит из набора параметров и справочников, а именно:

1. Данные по отправителю
2. Данные по получателю
3. Данные по отделению доставки или отправления
4. Данные по адресу доставки или отправления
5. Дополнительные справочники
6. Дополнительная параметры

В данной документации мы пошагово рассказываем, как получить данные для каждого, обязательного параметра, необходимого для создания интернет-документа.

6 шагов для создания интернет-документа через API

Справочник Контрагентов - getCounterparties

Данный справочник необходим для получения списка доступных контрагентов отправителей. В ответе на сформированный запрос, АПИ отдаст список доступных контрагентов и их параметры. В данном ответе нам необходимо получить идентификатор (REF) контагента для дальнейшего получения списка доступных контактных лиц Контрагента.

Стоит учитывать, что клиенты не могут самостоятельно создавать Контрагентов отправителей.
"Description": "Приватна особа",
"Ref": "82f28fae-3951-11e6-a54a-005056801333",
"Phones": "380971155109",


Все что необходимо сделать, это подставить нужный идентификатор (REF) Контрагента отправителя + телефон в форму запроса на создание интернет-документа + номер телефона, пример:

"Sender": "82f28fae-3951-11e6-a54a-005056801333",
"SendersPhone": "380971155109",

Справочник контактных лиц Контрагента - getCounterpartyContactPerson

Данный справочник необходим для получения списка доступных контактных лиц Контрагента. В ответе на сформированный запрос, АПИ отдаст список доступных контактных лиц Контрагента и их параметры. В данном ответе нам необходимо получить идентификатор (REF) контактного лица Контрагента отправителя для возможности формирования запроса на создание интернет-документа

"Description": "Іванов Іван Іванович",
"Ref": "9b9d5f71-6e3c-11e4-ab6d-005056801329",


Все что необходимо сделать, это подставить нужный идентификатор (REF) контактного лица Контрагента отправителя в форму запроса на создание интернет-документа, пример:

"ContactSender": "9b9d5f71-6e3c-11e4-ab6d-005056801329",

Справочник Контрагентов - getCounterparties

Данный справочник необходим для получения списка доступных контрагентов получателей. В ответе на сформированный запрос, АПИ отдаст список доступных контрагентов и их параметры. В данном ответе нам необходимо получить идентификатор (REF) контрагента для дальнейшего получения списка доступных контактных лиц Контрагента

"Description": "Приватна особа",
"Ref": "82f28fae-3951-11e6-a54a-005056801333",
"Phones": "380971155109",


Все что необходимо сделать, это подставить нужный идентификатор (REF) Контрагента получателя + телефон в форму запроса на создание интернет-документа, пример:

"Recipient": "82f28fae-3951-11e6-a54a-005056801333",
"RecipientsPhone": "380971155109",

Справочник контактных лиц Контрагента - getCounterpartyContactPerson

Данный справочник необходим для получения списка доступных контактных лиц Контрагента. В ответе на сформированный запрос, АПИ отдаст список доступных контактных лиц Контрагента и их параметры. В данном ответе нам необходимо получить идентификатор (REF) контактного лица Контрагента получателя для возможности формирования запроса на создание интернет-документа

"Description": "Іванов Іван Іванович",
"Ref": "9b9d5f71-6e3c-11e4-ab6d-005056801329",


Все что необходимо сделать, это подставить нужный идентификатор (REF) контактного лица Контрагента получателя в форму запроса на создание интернет-документа, пример:

"ContactRecipient": "9b9d5f71-6e3c-11e4-ab6d-005056801329",

Создание контрагентов

Метод создания Контрагента (приватна особа)- Save

Данный метод позволят создать контрагента получателя. В ответе на сформированный запрос, АПИ отдаст описание и идентификатор (REF) созданного контрагента.

"Ref": "e57f8afb-55f1-11e5-ad08-005056801333",


Все что необходимо сделать, это подставить нужный идентификатор (REF) контрагента получателя в форму запроса на создание интернет-документа, пример:

"Sender": "e57f8afb-55f1-11e5-ad08-005056801333",

Метод создания Контрагента с типом юридическое лицо или организация - Save

Данный метод позволят создать контрагента получателя. В ответе на сформированный запрос, АПИ отдаст описание и идентификатор (REF) созданного контрагента.

"Ref": "e57f8afb-55f1-11e5-ad08-005056801333",


Все что необходимо сделать, это подставить нужный идентификатор (REF) контрагента получателя в форму запроса на создание интернет-документа, пример:

"Sender": "e57f8afb-55f1-11e5-ad08-005056801333",

Метод создания Контрагента с типом третьего лица - Save

Данный метод позволят создать контрагента получателя. В ответе на сформированный запрос, АПИ отдаст описание и идентификатор (REF) созданного контрагента.

"Ref": "e57f8afb-55f1-11e5-ad08-005056801333",


Все что необходимо сделать, это подставить нужный идентификатор (REF) контрагента получателя в форму запроса на создание интернет-документа, пример:

"Sender": "e57f8afb-55f1-11e5-ad08-005056801333",

Справочник отделений - getWarehouses

Данный справочник необходим для получения списка всех отделений по Украине. Справочник скачивается на Украинском или русском языках.

В ответе на сформированный запрос, АПИ отдаст список отделений по Всей Украине. Для создания Интернет докумнта нам необходим идентификатор (REF) выбранного отделения:


"Ref": "39931b80-e1c2-11e3-8c4a-0050568002cf",

Все что необходимо сделать, это подставить нужный идентификатор (REF) отделения в форму запроса создания интернет-документа, для отпраителя:

"SenderAddress": "39931b80-e1c2-11e3-8c4a-0050568002cf",

Или для получателя:

"RecipientAddress": "39931b80-e1c2-11e3-8c4a-0050568002cf",

Данный параметр может использоваться в следующих запросах:

Для создания адреса доставки получателя или отправителя необходимо воспользоваться тремя справочниками:

1. Справочник городов компании - getCities

Для получения нужного города доставки, необходимо загрузить нужный идентификатор (REF) из справочника городов

"Description": "Агрономічне",
"Ref": "ebc0eda9-93ec-11e3-b441-0050568002cf",


Все что необходимо сделать, это подставить нужный идентификатор (REF) города получателя или отправителя в форму запроса на поиск нужной улицы в методе -getStreet, пример:

"CityRef": "ebc0eda9-93ec-11e3-b441-0050568002cf"

2. Справочник улиц компании - getStreet

Для выбора адреса в ранее выбранном городе, необходимо загрузить улицы из справочника улиц, пример:


"Description": "Академічна",
"Ref": "b5e79222-2d34-11e4-acce-0050568002cf",

Все что необходимо сделать, это подставить нужный идентификатор (REF) выбранной улицы получателя или отправителя в форму запроса на создание адреса доставки, пример:

"StreetRef": "b5e79222-2d34-11e4-acce-0050568002cf",

И ранее выбранный идентификатор (REF) нужного города:

"CityRef": "ebc0eda9-93ec-11e3-b441-0050568002cf"


3. Метод создания адреса для Отправителя или Получателя - Save

Данный метод позволяет создать адрес доставки для получателя или отправителя. В ответе на сформированный запрос, API отдаст описание и идентификатор (REF) созданного адреса, пример:


"Ref": "e57f8afb-55f1-11e5-ad08-005056801333",
"Description": "Жовтнева (Новобіличі) вул. 7 кв. 2"

Все что необходимо сделать, это подставить нужный идентификатор (REF) адреса созданного в п.2, в форму запроса на создание адреса, пример:

"StreetRef": "d4450bdb-0a58-11de-b6f5-001d92f78697",

Данный параметр может использоваться в следующих запросах:


По итогу создания АДРЕСА, все что необходимо сделать, это подставить нужный идентификатор (REF) адреса отправителя в форму запроса на создание интернет-документа, пример:

"SenderAddress": "e57f8afb-55f1-11e5-ad08-005056801333",

Или адреса получателя

"RecipientAddress": "e57f8afb-55f1-11e5-ad08-005056801333",

Справочник Видов груза - getCargoTypes

Данный справочник необходим для получения списка типов груза. Справочник скачивается на Украинском языке.

В ответе на сформированный запрос, АПИ отдаст список доступных видов груза, в формате ответа Описание и идентификатор (REF):

"Description":"Вантаж"
"Ref":"Cargo"


Все что необходимо сделать, это подставить нужный идентификатор (REF) груза в форму запроса на создание интернет документа, пример:

"CargoType": "Cargo",

Данный параметр может использоваться в следующих запросах:


Справочник Виды плательщиков - getTypesOfPayers

Данный справочник необходим для получения списка видов плательщиков услуги доставки. Справочник доступен на Украинском и Русском языках.

В ответе на сформированный запрос, АПИ отдаст список доступных видов плательщиков, в формате ответа Описание и идентификатор (REF): Вид плательщика "Третье лицо" возможно заказать только после заключения договора с компанией "Новая Почта".

"Description": "Третя особа",
"Ref": "ThirdPerson"


Все что необходимо сделать, это подставить нужный идентификатор (REF) груза в форму запроса на создание интернет-документа, пример:

PayerType":"Sender",

Данный параметр может использоваться в следующих запросах:


Справочник Описания груза - getCargoDescriptionList

Данный справочник необходим для получения описания груза на Украинском языке. Справочник доступен на Украинском и Русском языках.

В ответе на сформированный запрос, АПИ отдаст список доступных видов плательщиков, в формате ответа Описание и идентификатор (REF):

"Ref": "8f46973e-33e4-11e3-b441-0050568002cf",
"Description": "DVD/HD- медіаплеєр"


Все что необходимо сделать, это подставить нужный идентификатор (REF) описания в форму запроса на создание интернет-документа, пример:

"Description":"абажур",

Данный параметр может использоваться в следующих запросах:


Справочник Технологии доставки - getServiceTypes

Данный справочник необходим для список типов технологий доставки: «склад-склад», «двери-двери», «склад-двери», «двери-склад» на Украинском или Русском языках.

В ответе на сформированный запрос, АПИ отдаст список доступных технологии доставки, в формате ответа Описание и идентификатор (REF):

"Description":"Двері-Двері",
"Ref":"DoorsDoors"


Все что необходимо сделать, это подставить нужный идентификатор (REF) технологии доставки в форму запроса на создание интернет-документа, пример:

"ServiceType":"WarehouseWarehouse",

Данный параметр может использоваться в следующих запросах:


Справочник Формы оплаты - getPaymentForms

Данный справочник необходим для получения списка форм оплаты. Справочник доступен на Украинском и Русском языках.

В ответе на сформированный запрос, АПИ отдаст список доступных форм оплаты, в формате ответа Описание и идентификатор (REF):

Description":"Наличный расчет",
"Ref":"Cash"


Все что необходимо сделать, это подставить нужный идентификатор (REF) груза в форму запроса на создание интернет-документа, пример:

"PaymentMethod":"Cash",

Данный параметр может использоваться в следующих запросах:

Параметр Фактический вес - weight

Параметр необходим для указания фактического веса. Параметр обязателен для заполнения.

Все что необходимо сделать, это прописать нужный вес груза в форму запроса на создание интернет-документа, пример:

"weight": "28",


Данный параметр может использоваться в следующих запросах:


Параметр Количество мест - SeatsAmount

Параметр необходим для указания фактического количества мест отправления. Параметр обязателен для заполнения.

Все что необходимо сделать, это указать необходимое количество мест в форму запроса на создание интернет-документа, пример:

"SeatsAmount":"1",


Данный параметр может использоваться в следующих запросах:


Параметр Объявленная стоимость - Cost

Параметр необходим для указания объявленной стоимости. Параметр обязателен для заполнения.

Все что необходимо сделать, это прописать стоимость отправления груза в форму запроса на создание интернет-документа, пример:

"Cost":"500",


Данный параметр может использоваться в следующих запросах:


Параметр Дата отправления - DateTime. Не обязательный

Параметр не обязателен, но может быть необходим для указания фактической даты отправления в формате дд.мм.гггг, если дата доставки отправления будет происходить позже.

Все что необходимо сделать, это прописать нужную дату в форму запроса на создание интернет-документа, или оставить параметр пустым, пример:

"DateTime":"23.09.2017",


Данный параметр может использоваться в следующих запросах:

Параметр Общий объем - VolumeGeneral. Не обязательный

Параметр не обязателен, но может быть необходим для указания общего обьема, м.куб (min - 0.0004), для более точного просчета стоимости.

Все что необходимо сделать, это прописать нужный объем груза в форму запроса на создание интернет-документа, пример:

"VolumeGeneral": "0.1",


Данный параметр может использоваться в следующих запросах:


Печать Интернет-документов

API Нова пошта предоставляет несколько вариантов печати, HTML или PDF из браузера:

Печать по Ref - HTML или PDF

https://my.novaposhta.ua/orders/printDocument/orders[]/ab91865b-2937-11e4-ab6d-005056801329/type/html или pdf/apiKey/[ВАШ КЛЮЧ]

Вместо идентификатора (REF) можно передавать номер Интернет докумнета, или несколько номеров.

https://my.novaposhta.ua/orders/printDocument/orders/20600000002260,20600000002309/type/html или pdf/apiKey/[ВАШ КЛЮЧ]

Печать Маркировок

Маркировка размещается на каждом месте отправления, если Клиент осуществляет прием-передачу отправлений по реестру.

Маркировка размещается на каждом месте отправлений, начиная со второго, если клиент осуществляет прием-передачу без реестра (на первом месте отправления размещается печатная форма экспресс-накладных)


Печать по Ref - HTML или PDF

https://my.novaposhta.ua/orders/printMarkings/orders[]/ab91865b-2937-11e4-ab6d-005056801329/type/html или pdf/apiKey/[ВАШ КЛЮЧ]

Вместо идентификатора (REF) можно передавать номер Интернет докумнета, или несколько номеров

https://my.novaposhta.ua/orders/printMarkings/orders/20600000002260,20600000002309/type/html или pdf/apiKey/[ВАШ КЛЮЧ]

Печать штрих-кодов на принтере Zebra

https://my.novaposhta.ua/orders/printMarkings/orders/ab91865b-2937-11e4-ab6d-005056801329,ab91865b-2937-11e4-ab6d-005056801329/type/html/apiKey/[ВАШ КЛЮЧ]/zebra/zebra