Документация по партнерскому API gds

Партнерский API — это протокол взаимодействия между учетной системой продавца и goods.

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

Интеграция по API позволит:

Для подготовки API вам понадобится помощь разработчика.

  1. Как подключиться по API
  2. Спецификация API
  3. Сценарий обработки заказов продавцом
  4. Реализация сценария обработки заказа через API
  5. Загрузка прайс-листа в формате YML
  6. Требования к маркировочному листу
  7. Требования к реестру отгрузки
  8. Как пройти проверку при подключении API
  9. Вопросы и ответы

Как подключиться по API

Для использования API выполните следующие шаги:

Шаг 1Зарегистрируйтесь в goods и получите доступ к личному кабинету продавца

Рис. 1 — Регистрация нового магазина в goods
Рис. 1 — Регистрация нового магазина в goods

Шаг 2 — Настройте интеграцию по API в личном кабинете

Шаг 3 — Получите авторизационный токен в личном кабинете

Рис. 2 — Настройка интеграции в личном кабинете продавца
Рис. 2 — Настройка интеграции в личном кабинете продавца

Шаг 4 — Получите уникальный идентификатор магазина (у менеджеров goods)

Шаг 5 — Используйте токен и идентификатор при вызове методов API


Спецификация API

Подробная спецификация доступна по ссылке

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

Запросы к goods

Запросы к продавцу


Сценарий обработки заказов продавцом

Шаг 1 — Размещение товарных предложений на goods

Размещение товарных предложений для продажи на маркетплейсе goods выполняется через формирование прайс-лист в формате YML продавцом (подробнее о прайс-листе), в котором должна поддерживаться актуальность следующей информации:

Покупатель заинтересовавшись выгодным предложением оформляет заказ на goods. Далее заказ передается продавцу через интерфейс личного кабинета или по API.

Шаг 2 — Подтверждение нового заказа

Продавец, получив новый заказ от goods должен удостовериться, что по товарам имеются положительные остатки на складе и заказ может быть отгружен в указанный срок. Подтвердить принятие заказа в личном кабинете продавца (или по API) в течение 3 часов с момента получения заказа. По результатам подтверждения заказа, клиент получит СМС-уведомление.

Если часть товаров отсутствует на складе (или все товары в заказе), то необходимо отклонить принятие отсутствующих товаров (всех или части) с обязательным указанием причины отмены.

Важно: за подтверждение товаров в заказе, которые не смогут быть отгружены в будущем, взымается повышенная комиссия.

  1. После получения заказа продавец подтверждает возможность его отгрузки в указанные сроки, выполняет комплектацию и отгрузку. Базовый сценарий вызовов API-методов изображен ниже.
Рис. 3 — Последовательность обращений по API (базовый сценарий)
Рис. 3 — Последовательность обращений по API (базовый сценарий)

Рассмотрим выполнение каждого из шагов более детально.


Шаг 1 — Размещение товарных предложений на goods

Для размещения товарных предложений для продажи на маркетплейсе goods необходимо сформировать прайс-лист в формате YML (подробнее о прайс-листе).

Товарные предложения описываются характеристиками:


Шаг 2 — Подтверждение нового заказа

  1. Процесс подтверждения нового заказа
  2. Последовательность обращений по API
  3. Примеры вызовов API

2.1 Процесс подтверждения нового заказа

Рассмотрим пример, когда покупатель оформляет заказ состоящий из трех позиций: телефон, планшет, корм для питомца. Телефон и планшет покупается у ’Продавец 1’, а корм для питомца у ’Продавец 2’. Goods сообщает каждому продавцу про его часть заказа.

Рис. 4 — Процесс оформления нового заказа покупателем на goods
Рис. 4 — Процесс оформления нового заказа покупателем на goods

Продавец, получив новый заказ от goods проверяет доступное кол-во остатков по каждой позиции в заказе и дает свое согласие об отгрузке заказа в указанный срок.

Рис. 5 — Процесс оформления нового заказа покупателем на goods
Рис. 5 — Процесс оформления нового заказа покупателем на goods

2.2 Последовательность обращений по API

  1. После оформления покупателем нового заказа, goods передает информацию по заказу продавцу вызовом метода POST order/new, который должен быть реализован на стороне продавца.
  2. Продавец обязуется в течение 3 часов с момента получения заказа сообщить свое решение goods об отгрузки. Решение о подтверждении ожидается по каждому товару в заказе. Сообщается вызовом методов POST order/confirm и POST order/reject.

    По результатам подтверждения заказа, клиент получит СМС-уведомление о подтверждении заказа продавцом.

Рис. 6 — Последовательность обращений по API при подтверждении заказа продавцом
Рис. 6 — Последовательность обращений по API при подтверждении заказа продавцом

2.3 Примеры вызовов API

Goods передает продавцу заказ с двумя товарами

Продавец подтверждает заказ

Продавец частично подтверждает заказ

Продавец отклоняет заказ


Шаг 3 — Комплектация заказа для отгрузки

  1. Процесс комплектации заказа
  2. Последовательность обращений по API
  3. Примеры вызовов API

3.1 Процесс комплектации заказа

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

Продавец сообщает goods об успешной комплектации заказа для того, чтобы goods смог передать информацию о заказе на Сортировочный Центр. После завершения комплектации заказ ожидает отгрузки на складе продавца.

Рис. 7 — Процесс комплектации (сборки и упаковки) заказа продавцом
Рис. 7 — Процесс комплектации (сборки и упаковки) заказа продавцом

3.2 Последовательность обращений по API

  1. Комплектация заказа должна быть выполнена продавцом до окончания времени на отгрузку заказа (передается в запросе POST order/new в элементе shippingDate.
  2. Продавец должен передать в вызове метода POST order/packing номер заказа goods по скомплектованному заказу. Кроме того, сообщить информацию по грузовым местам, в которые укомплектованы товары. При этом:
  3. Решение о комплектации ожидается по каждому товару в заказе. Сообщается вызовом методов POST order/packing и POST order/reject.
Рис. 8 — Последовательность обращений по API при комплектации заказа продавцом
Рис. 8 — Последовательность обращений по API при комплектации заказа продавцом

3.3 Примеры вызовов API

Продавец комплектует заказ в одно грузовое место

Продавец комплектует заказ в разные грузовые места

Продавец комплектует товар в заказе в два грузовых места

Продавец частично комплектует заказ

Продавец отклоняет заказ


Шаг 4 — Отгрузка заказа

  1. Процесс отгрузки заказа
  2. Последовательность обращений по API
  3. Примеры вызовов API

4.1 Процесс отгрузки заказа

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

На Сортировочном Центре выполняется объединение заказов от разных продавцов в единый заказ для покупателя. В согласованное с покупателем время заказ доставляется покупателю.

Рис. 9 — Процесс отгрузки заказа продавцами и доставка покупателю
Рис. 9 — Процесс отгрузки заказа продавцами и доставка покупателю

4.2 Последовательность обращений по API

После физической отгрузки товара курьеру логистической службы goods, продавец передает об этом информацию через вызов метода POST order/shipping.

  1. Отгрузка заказа должна быть выполнена продавцом до окончания времени на отгрузку заказа (передается в запросе POST order/new в элементе shippingDate.
  2. Продавец должен передать в вызове метода POST order/shipping номера отгруженных грузовых мест.
  3. Решение об отгрузке ожидается по каждому грузовому месту в заказе.
Рис. 10 — Последовательность обращений по API при отгрузки заказа продавцом
Рис. 10 — Последовательность обращений по API при отгрузки заказа продавцом

4.3 Примеры вызовов API

Продавец отгружает заказ

Продавец частично отгружает заказ

Продавец отклоняет заказ


Загрузка прайс-листа в формате YML

Скачать шаблон YML-файла

Подробнее про YML-файл: https://yandex.ru/support/webmaster/goods-prices/technical-requirements.html


Требования к маркировочному листу

Скачать шаблон маркировочного листа

Маркировочный лист наклеивается на грузовое место в момент комплектации заказа. Изображение маркировочного листа и описание см. ниже.

Рис. 11 — Пример маркировочного листа
Рис. 11 — Пример маркировочного листа
  1. Штрих-код в формате Code 128 (подробнее о формате)

    Представляет собой закодированный идентификатор грузового места. Используется для распознавания грузового места на Сортировочном Центре goods.

  2. Идентификатор грузового места

    Уникальный идентификатор, однозначно идентифицирующий грузовое место продавца.

    Формируется по шаблону: {Идентификатор продавца}*{Номер заказа продавца}*{Номер грузового места}

    Например,

    7*73606159*1, где:

    7 — идентификатор продавца,

    73606159 — номер заказа продавца,

    1 — идентификатор грузового места.

  3. Юр. наименование продавца

    Полное юридическое наименование продавца.

  4. Идентификатор продавца

    Уникальный идентификатор продавца, выдается goods в момент регистрации личного кабинета.

  5. Адрес доставки

    Адрес доставки

  6. ФИО получателя

    ФИО получателя

  7. Номер доставки

    Номер доставки goods

  8. Номер отправления

    Номер заказа продавца

  9. Дата доставки

    Дата доставки заказа покупателю

  10. Логотип goods

    Логотип goods


Требования к реестру отгрузки

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

Рис. 12 — Пример реестра отгрузки
Рис. 12 — Пример реестра отгрузки
  1. Номер доставки

    Номер доставки goods, получить можно из элемента label / deleveryIdинформации по заказу в запросе POST order/new.

  2. Номер отправления goods

    Номер заказа goods, получить можно из элемента shipmentId запроса POST order/new.

  3. Номер отправления продавца с префиксом

    Идентификатор, формирующийся по шаблону: {Идентификатор продавца}*{Номер заказа продавца}

    Например,

    7*73606159, где:

    7 — идентификатор продавца,

    73606159 — номер заказа продавца,

  4. Количество мест

    Кол-во грузовых мест в заказе

  5. Номер места продавца

    Для каждого из грузового места передается идентификатор грузового места, однозначно идентифицирующий грузовое место продавца.

    Формируется по шаблону: {Идентификатор продавца}*{Номер заказа продавца}*{Номер грузового места}

    Например,

    7*73606159*1, где:

    7 — идентификатор продавца,

    73606159 — номер заказа продавца,

    1 — идентификатор грузового места.

  6. Объявленная стоимость места, руб
  7. Объявленная стоимость отправления, руб

Как пройти проверку при подключении к API

Важное условие работы goods — сохранять доверие пользователей к сервису и к магазинам, которые на нем размещаются. Поэтому при подключении все магазины обязательно проходят проверку или премодерацию.

Что проверяет goods

Как проходит проверка


Вопросы и ответы


© 2018, Константин Заваров