Получение справочника ПВЗ курьерской службы

Если у курьерской службы есть собственные точки выдачи, использование которых подразумевается подписанным договором, то ИС Золотого Яблока необходимо обладать таким справочником на своей стороне для предоставления информации о доступных точках выдачи заказа клиентам. Эндпоинт должен быть опубликован по защищенному протоколу HTTPS. Перед полноценным запуском интеграции в продакшен - ИС Золотого Яблока выполняет запрос к ИС курьерской службы, чтобы получить полный список всех доступных ПВЗ в формате, требуемом ИС Золотого Яблока. Данный запрос также может выполняться ИС Золотого Яблока после запуска интеграции по мере необходимости для актуализации справочника ПВЗ. Сформированный на стороне ИС Золотого яблока справочник и отдельные его элементы могут быть изменены по инициативе курьерской службы следующими методами:

• Добавление нового ПВЗ в существующий справочник
• Изменение созданного ранее ПВЗ в справочнике

Основная информация

Тип метода запроса	GET
Путь/URL	/api/v1/pickpoints
Описание	Метод используется для получения списка ПВЗ, предоставляемых курьерской службой
Направление	Запрос выполняет ИС Золотого Яблока. Ответ предоставляется курьерской службой.

Запрос

Параметры заголовка

Параметр	Тип данных	Обязательность	Описание	Комментарий
Authorization	string	1	Access token, полученный при авторизации. Передаётся в формате Bearer <access_token>	Формат передаёт курьерская служба (см. Авторизация в сервисе ВКС)
content-type	string	1	Тип содержимого запроса	Заполняется "application/json"

Пример запроса

curl --location 'https://api.example-cs.com/api/v1/pickpoints' \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" \
-H "Content-Type: application/json"

Ответ

Коды ответов и сообщений

Код	Статус	Сообщение	Причина
200	ОК	Success	Все прошло успешно. Справочник ПВЗ передан в полезной нагрузке ответа
400	Bad Request	Missing or inappropriate required parameters	Не переданы или некорректно заполнены обязательные поля
401	Unauthorized	Token is invalid	Ошибка аутентификации в КС
403	Forbidden	Has no permission	Запрещено в текущем контексте
500	Internal Server Error	Server unavailable	Сервер недоступен

Параметры успешного ответа

№	Параметр			Тип данных	Обязательность	Описание	Комментарий
1	countryISOCode			string (2)	1	Код страны для справочника	Согласно стандарту "ISO 3166-1, alpha-2"
2	deliveryServiceCode			string (100)	1	Код курьерской службы	Оговаривается при интеграции с системой.
3	pickpointsList			array of objects	1	Массив объектов точек выдачи
4		id		string (100)	1	Идентификатор ПВЗ курьерской службы	Передаётся из курьерской службы
5		type		string (20)	1	Тип пункта выдачи	См. "Форматные таблицы" → "Таблица 1"
6		address		address object	1	Объект, содержащий адресные данные
7			Address object type	object	1	Объект, содержащий адресную информацию.	Адресный объект (см. Приложение: Адресные типы данных)
8		openingHours		array of objects	1	Массив объектов с часами работы ПВЗ
9			dayOfWeek	enum	1	Идентификатор дня для которого назначается режим работы	См. "Форматные таблицы" → "Таблица 3"
10			workingDay	bool	1	Признак рабочего дня	Если включен - то ПВЗ работает в этот день недели
11			opens	string (15)	1	Время открытия ПВЗ	Согласно стандарту "ISO 8601" (hh:mm:ss)
12			closes	string (15)	1	Время закрытия ПВЗ	Согласно стандарту "ISO 8601" (hh:mm:ss)
13		phoneNumber		string (20)	0	Номер телефона ПВЗ	Без спецсимволов, только цифры (код страны и федеральный код)
14		isAvailable		boolean	1	Статус доступности ПВЗ	Если флаг включен, то ПВЗ активен, если выключен - то нет
15		orderStoragePeriod		int	1	Срок хранения заказа в календарных днях	Например: 5
16		options		object	1	Объект с опциями, доступными для ПВЗ
17			orderIssuing	bool	1	Есть возможность выдачи заказа	Если включен - то ПВЗ может выдавать заказы
18			orderReturning	bool	1	Есть возможность возврата заказа	Если включен - то ПВЗ может принимать возвраты
19			haveTryOn	bool	1	Есть примерочные и возможность примерки	Если включен, то в ПВЗ есть примерочные
20			havePartialBuy	bool	1	Есть возможность частичного выкупа	То есть, на ПВЗ могут провести частичную выдачу
21			packageMinWeight	int	1	Минимальный вес посылки для этого ПВЗ в граммах
22			packageMaxWeight	int	1	Максимальный вес посылки для этого ПВЗ в граммах
23			packageMaxLength	decimal	1	Максимальная длина посылки для ПВЗ в сантиметрах.	По оси X. С точностью до двух знаков после разделителя
24			packageMaxHeight	decimal	1	Максимальная высота посылки для ПВЗ в сантиметрах.	По оси Y. С точностью до двух знаков после разделителя
25			packageMaxWidth	decimal	1	Максимальная ширина посылки для ПВЗ в сантиметрах.	По оси Z. С точностью до двух знаков после разделителя
26		paymentOptions		object	1	Объект с вариантами оплаты при получении
27			haveCashPayment	bool	1	Есть оплата наличными (касса)	Если включен - то на ПВЗ возможна оплата наличными
28			haveCardPayment	bool	1	Есть оплата картой (терминал)	Если включен, то на ПВЗ принимают оплату картой
29			haveQrCodePayment	bool	1	Есть оплата QR-кодом (терминал, ПО на ПВЗ)	Если включен, то на ПВЗ есть оплата по QR-коду

Примеры успешного ответа

{
  "countryISOCode": "RU",
  "deliveryServiceCode": "EXAMPLE_CS",
  "pickpointsList": [
    {
      "id": "PVZ-SPB-001",
      "type": "PICKPOINT",
      "address": {
        "addressType": "gar",
        "fullAddress": "190000, г Санкт-Петербург, Невский проспект, д 28",
        "regionFias": "c2deb16a-0330-4f05-821f-1d12d16a218a",
        "cityFias": "f1a154e5-7982-4d4b-a70d-5e9a01350320",
        "houseFias": "a1b2c3d4-5678-90ef-1234-567890abcdef",
        "flat": "",
        "latitude": 58.0167,
        "longitude": 56.235,
        "addressComment": "Цокольный этаж, вход с Невского проспекта"
      },
      "openingHours": [
        {
          "dayOfWeek": 1,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 2,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 3,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 4,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 5,
          "workingDay": true,
          "opens": "09:00:00",
          "closes": "21:00:00"
        },
        {
          "dayOfWeek": 6,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "20:00:00"
        },
        {
          "dayOfWeek": 7,
          "workingDay": false,
          "opens": null,
          "closes": null
        }
      ],
      "phoneNumber": "78121234567",
      "isAvailable": true,
      "orderStoragePeriod": 5,
      "options": {
        "orderIssuing": true,
        "orderReturning": true,
        "haveTryOn": true,
        "havePartialBuy": true,
        "packageMinWeight": 150,
        "packageMaxWeight": 10000,
        "packageMaxLength": 100,
        "packageMaxHeight": 100,
        "packageMaxWidth": 100
      },
      "paymentOptions": {
        "haveCashPayment": true,
        "haveCardPayment": true,
        "haveQrCodePayment": true
      }
    },
    {
      "id": "PVZ-MOS-005",
      "type": "POSTOMAT",
      "address": {
        "addressType": "coord",
        "fullAddress": "125009, г Москва, Тверская ул, д 7",
        "cityFias": "2763c110-cb8b-416a-9dac-ad28a55b4402",
        "latitude": 55.755816,
        "longitude": 37.617633,
        "flat": "",
        "addressComment": "ТЦ Этажи, 1 этаж, у главного входа"
      },
      "openingHours": [
        {
          "dayOfWeek": 1,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 2,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 3,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 4,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 5,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 6,
          "workingDay": true,
          "opens": "10:00:00",
          "closes": "22:00:00"
        },
        {
          "dayOfWeek": 7,
          "workingDay": true,
          "opens": "11:00:00",
          "closes": "21:00:00"
        }
      ],
      "phoneNumber": null,
      "isAvailable": false,
      "orderStoragePeriod": 7,
      "options": {
        "orderIssuing": true,
        "orderReturning": false,
        "haveTryOn": false,
        "havePartialBuy": false,
        "packageMinWeight": 50,
        "packageMaxWeight": 3000,
        "packageMaxLength": 45,
        "packageMaxHeight": 27.9,
        "packageMaxWidth": 30
      },
      "paymentOptions": {
        "haveCashPayment": false,
        "haveCardPayment": true,
        "haveQrCodePayment": true
      }
    }
  ]
}

Параметры неуспешного ответа

Параметр	Тип данных	Обязательность	Описание	Комментарий
error	string	1	Человекочитаемое описание ошибки	см. п. "Коды ответов и сообщений"

Пример неуспешного ответа

Неуспешный ответ

{
  "error": "Token is invalid"
}

Форматные таблицы

Таблица 1: Допустимые типы точек выдачи

Тип	Код	Описание
ПВЗ	PICKPOINT	Пункт выдачи заказа с оператором на месте, кассой, примерочными, e.t.c
Постомат	POSTOMAT	Терминал выдачи заказа в торговой точке или ТЦ, ТРЦ, постомат

Таблица 2: Типы адресной информации

Тип	Код	Описание
Государственный адресный реестр РФ	gar	Адресный объект, использующий идентификаторы ГАР и ФИАС
Координатная система (широта, долгота, адрес)	coord	Адресный объект, использующий координаты и адрес в свободной форме
Свободная форма адреса	custom	Адресный объект, использующий адрес в свободной форме и уточняющие поля

Таблица 3: Перечисление дней недели

День недели	Идентификатор
Понедельник	1
Вторник	2
Среда	3
Четверг	4
Пятница	5
Суббота	6
Воскресенье	7