Портал для разработчиков API "Новая Почта"

API Адреса

Работа с адресами

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

Метод «getWarehouses», работает в модели «Address», этот метод загружает справочник отделений «Новая Почта» в рамках населенных пунктов Украины.

Есть возможность отфильтровать нужные отделения по следующим признакам:
1) TypeOfWarehouseRef 2) PostFinance 3) BicycleParking 4) POSTerminal 5) CityName 6) CityRef
Пример:
"methodProperties": { "BicycleParking": "1", "TypeOfWarehouseRef":"9a68df70-0267-42a8-bb5c-37f427e36ee4", "PostFinance": "1", "CityName":"Київ" "CityRef": "20982d74-9b6c-11e2-a57a-d4ae527baec3", }

Есть возможность получить нужное отделение используя параметры:
1) CityName 2) FindByString
Пример:
"methodProperties": { "CityName":"Київ", "FindByString": "Відділення №8" }

или используя идентификатор отделения Ref
Пример:


"methodProperties": {

"Ref": "47402ec5-e1c2-11e3-8c4a-0050568002cf" //РЕФ отделения из справочника отделений

}

Предусмотрена возможность быстрого получения отделений в конкретном городе/нас. пункте или поселке, при помощи метода getSettlements
Пример:
"methodProperties": { "SettlementRef": "e71629ab-4b33-11e4-ab6d-005056801329" //РЕФ города из справочника населенных пунктов Украины }

Если заменить «getWarehouses» на «getWarehouseTypes», можно получить справочник типов отделений «Новая Почта».
Копию справочника необходимо сохранять и поддерживать в актуальном состоянии путем обновления раз в сутки.

URL для входа https://api.novaposhta.ua/v2.0/{format}/ [json or xml]/
Формат, обязательно, должен указываться нижним регистром (маленькими буквами), например https://api.novaposhta.ua/v2.0/json/

Доступность: Требует использования API-ключа.

Try it

URL-адрес запроса

https://api.novaposhta.ua/v2.0/{format}/ [json or xml]

Параметры запроса

format

string

Форматы JSON, XML

Заголовки запросов

Content-Type (дополнительный)

string

Тип формата текста, отправляемого в API.

Текст запроса

Параметр	Тип данных	Описание
apiKey*	string[36]	Ваш ключ API 2.0
modelName*	string	Имя модели
calledMethod*	string	Имя вызываемого метода
methodProperties		Свойства метода
CityName	string[36]	Дополнительный фильтр по имени города
CityRef	string[36]	Дополнительный фильтр по идентификатору города
Page	int[10]	Страница, максимум 500 записей на странице. Работает в связке с параметром Limit
Limit	int[10]	Количество записей на странице. Работает в связке с параметром Page
Language	String[2]	Вывод описания на Украинском или русском языках - ru. По умолчанию всегда выводиться на Украинском языке.

* Обозначение обязательного параметра.

application/json
text/xml

{
    "modelName": "AddressGeneral",
    "calledMethod": "getWarehouses",
    "methodProperties": {
         "Language": "ru"
    },
    "apiKey": "[ВАШ КЛЮЧ]"
}

<?xml version="1.0" encoding="UTF-8" ?>
<root>
	<modelName>AddressGeneral</modelName>
	<calledMethod>getWarehouses</calledMethod>
	<methodProperties>
                <Language>ru</Language>
	</methodProperties>
<apiKey>[ВАШ КЛЮЧ]</apiKey>
	</root>

Ответ 200

Всегда возвращает код 200 даже при логических ошибках.

Тело ответа на запрос

Параметр	Тип данных	Описание
Ref	string[36]	Идентификатор отделения
SiteKey	decimal[9999999999]	Код отделения
Description	string[99]	Название отделения на Украинском
DescriptionRu	string[99]	Название отделения на русском
TypeOfWarehouse	string[36]	Тип отделения
Number	int[99999]	Номер отделения
CityRef	string[36]	Идентификатор населенного пункта
CityDescription	string[50]	Название населенного пункта на Украинском
CityDescriptionRu	string[50]	Название населенного пункта на русском
Longitude	int[50]	Долгота
Latitude	int[50]	Широта
PostFinance	int[1]	(1/0) Наличие кассы Пост-Финанс
POSTerminal	int[1]	(1/0) Наличие пос-терминала на отделении
InternationalShipping	int[1]	(1/0) Возможность оформления Международного отправления
TotalMaxWeightAllowed	int[9999999999]	Максимальный вес отправления
PlaceMaxWeightAllowed	int[9999999999]	Максимальный вес одного места отправления
SendingLimitationsOnDimensions	array[3]	Максимальные габариты отправления для отправки
ReceivingLimitationsOnDimensions	array[3]	Максимальные габариты отправления для получения
Reception	array[7]	График приема отправлений
Delivery	array[7]	График отправки день в день
Schedule	array[7]	График работы

application/json
text/xml

{
  "success": true,
  "data": [
    {
      "SiteKey": "10119",
      "Description": "Відділення №1: вул. М. Грушевського, 3",
      "DescriptionRu": "Отделение №1: ул. М. Грушевского, 3",
      "Phone": "0-800-500-609",
      "TypeOfWarehouse": "9a68df70-0267-42a8-bb5c-37f427e36ee4",
      "Ref": "39931b80-e1c2-11e3-8c4a-0050568002cf",
      "Number": "1",
      "CityRef": "20982d74-9b6c-11e2-a57a-d4ae527baec3",
      "CityDescription": "Заболотів (Снятинський р-н)",
      "CityDescriptionRu": "Заболотов (Снятинский р-н)",
      "Longitude": "25.299652300000000",
      "Latitude": "48.470805500000000",
      "PostFinance": "1",
      "BicycleParking": "0",
      "POSTerminal": "1",
      "InternationalShipping": "0",
      "TotalMaxWeightAllowed": 0,
      "PlaceMaxWeightAllowed": 0,
      "SendingLimitationsOnDimensions": {
                "Width": 150,
                "Height": 150,
                "Length": 150
      },
      "ReceivingLimitationsOnDimensions": {
                "Width": 150,
                "Height": 150,
                "Length": 150
      },
      "Reception": {
        "Monday": "15:30-18:00",
        "Tuesday": "15:30-18:00",
        "Wednesday": "15:30-18:00",
        "Thursday": "15:30-18:00",
        "Friday": "15:30-18:00",
        "Saturday": "-",
        "Sunday": "-"
      },
      "Delivery": {
        "Monday": "09:00-15:00",
        "Tuesday": "09:00-15:00",
        "Wednesday": "09:00-15:00",
        "Thursday": "09:00-15:00",
        "Friday": "09:00-15:00",
        "Saturday": "-",
        "Sunday": "-"
      },
      "Schedule": {
        "Monday": "09:00-18:00",
        "Tuesday": "09:00-18:00",
        "Wednesday": "09:00-18:00",
        "Thursday": "09:00-18:00",
        "Friday": "09:00-18:00",
        "Saturday": "09:00-15:00",
        "Sunday": "-"
      }
    }
  ],
  "errors": [],
  "warnings": [],
  "info": {
    "totalCount": 1
  },
  "messageCodes": [],
  "errorCodes": [],
  "warningCodes": [],
  "infoCodes": []
}

<root>
    <success>true</success>
    <data>
        <item>
            <SiteKey>19709</SiteKey>
            <Description>Пункт приймання-видачі (до 30 кг): вул. Андрія Бобира, 13</Description>
            <DescriptionRu>Пункт приема-выдачи (до 30 кг): ул. Андрея Бобырь, 13</DescriptionRu>
            <ShortAddress>Ничипорівка, Андрія Бобира, 13</ShortAddress>
            <ShortAddressRu>Ничипоровка, Андрея Бобырь, 13</ShortAddressRu>
            <Phone>380800500609</Phone>
            <TypeOfWarehouse>841339c7-591a-42e2-8233-7a0a00f0ed6f</TypeOfWarehouse>
            <Ref>e68be3b9-ca66-11e9-b0c5-005056b24375</Ref>
            <Number>1</Number>
            <CityRef>5f732140-8837-11e9-898c-005056b24375</CityRef>
            <CityDescription>Ничипорівка</CityDescription>
            <CityDescriptionRu>Нечипоровка</CityDescriptionRu>
            <SettlementRef>0ea103c8-4b3a-11e4-ab6d-005056801329</SettlementRef>
            <SettlementDescription>Ничипорівка</SettlementDescription>
            <SettlementAreaDescription>Київська</SettlementAreaDescription>
            <SettlementRegionsDescription>Яготинський р-н</SettlementRegionsDescription>
            <SettlementTypeDescription>село</SettlementTypeDescription>
            <Longitude>31.830721000000000</Longitude>
            <Latitude>50.196648000000000</Latitude>
            <PostFinance>1</PostFinance>
            <BicycleParking>0</BicycleParking>
            <PaymentAccess>0</PaymentAccess>
            <POSTerminal>0</POSTerminal>
            <InternationalShipping>0</InternationalShipping>
            <SelfServiceWorkplacesCount>0</SelfServiceWorkplacesCount>
            <TotalMaxWeightAllowed>30</TotalMaxWeightAllowed>
            <PlaceMaxWeightAllowed>0</PlaceMaxWeightAllowed>
            <SendingLimitationsOnDimensions>
                <Width>150</Width>
                <Height>150</Height>
                <Length>150</Length>
            </SendingLimitationsOnDimensions>
            <ReceivingLimitationsOnDimensions>
                <Width>150</Width>
                <Height>150</Height>
                <Length>150</Length>
            </ReceivingLimitationsOnDimensions>
            <Reception>
                <Monday>09:40-17:00</Monday>
                <Tuesday>-</Tuesday>
                <Wednesday>09:40-17:00</Wednesday>
                <Thursday>-</Thursday>
                <Friday>09:40-17:00</Friday>
                <Saturday>-</Saturday>
                <Sunday>-</Sunday>
            </Reception>
            <Delivery>
                <Monday>-</Monday>
                <Tuesday>-</Tuesday>
                <Wednesday>-</Wednesday>
                <Thursday>-</Thursday>
                <Friday>-</Friday>
                <Saturday>-</Saturday>
                <Sunday>-</Sunday>
            </Delivery>
            <Schedule>
                <Monday>09:00-15:00</Monday>
                <Tuesday>09:00-17:00</Tuesday>
                <Wednesday>09:00-17:00</Wednesday>
                <Thursday>09:00-17:00</Thursday>
                <Friday>09:00-17:00</Friday>
                <Saturday>09:00-15:00</Saturday>
                <Sunday>-</Sunday>
            </Schedule>
		</item>
	</data>
	<errors />
	<warnings />
	<info />
</root>