Создание Интернет-документа
Самым важным сервисом 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