Интеграция при помощи REST API

Общая информация

Открыть статью в новой вкладке

getalon* REST API – это программный интерфейс для взаимодействия системы поставщика с getalon*. С помощью методов, которые предоставляет API, можно совершать такие действия, как создание складов, выгрузка номенклатуры и пр., и тем самым автоматизировать различные процессы, не прибегая к ручному взаимодействию в личном кабинете поставщика.

Работа с API

Основной сценарий работы с API – это отправка запросов на сервер getalon* и получение ответа об успешной операции или ошибке. Реализация отправки запросов, получения и разбора ответов происходит на уровне кода учетной системы, соответственно, этим обычно занимаются разработчики данных систем.

Но также можно просматривать спецификацию и использовать методы API при помощи специального пользовательского интерфейса, который доступен по следующей ссылке – https://api.getalon.ru/v1/rest-api-documentation/index.html, либо используя такие инструменты, как Postman и Insomnia.

Что позволяет делать API

На текущий момент, в версии 1.0, API позволяет совершать следующие базовые операции:

Операции со складами

  • добавление
  • обновление
  • удаление

Операции с номенклатурой (товарами)

  • добавление
  • обновление
  • удаление

Операции с остатками товаров на складах

  • добавление
  • обновление
  • удаление

Прочие операции

  • проверка работоспособности сервера getalon*
  • получение статуса операций

Начало работы с API

По-умолчанию API доступно для любого зарегистрированного в getalon* поставщика. Но для того, чтобы getalon* начал принимать и обрабатывать запросы необходимо получить специальный секретный ключ, которым необходимо подписывать каждый запрос, чтобы сервер getalon* смог идентифицировать и авторизовать внешнюю систему.

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

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

Как использовать ключ для подписи запросов

В API getalon* используется Bearer аутентификация. Bearer аутентификация - это способ проверки пользователя при обращении к серверу getalon*. Когда происходит попытка обратиться к каком-либо методу API, то необходимо подставить специальный токен, который называется "Bearer token". Этот токен действует как ключ, который доказывает, что у пользователя есть право на доступ к ресурсу.

Полученный секретный ключ необходимо передавать в любом запросе к серверу getalon*, в заголовке Authorization:

Authorization: Bearer <ЗДЕСЬ_УКАЗАН_КЛЮЧ>

Что делать, если ключ попал не в те руки

Если вы заподозрили, что ключ попал в общий доступ или его могло заполучить нежелательное лицо, то сразу же обратитесь в getalon* по любому доступному для вас каналу связи, в частности по телефону 8 800 777 6000 и/или адресу электронной почты info@getalon.ru.

Передача данных в getalon*

Склады

Склады – это место, где товары хранятся перед тем, как они будут проданы, распределены или использованы. Местоположение склада доступно покупателю для расчета логистики. Также склады необходимы для выгрузки остатков товаров.

Добавление

За создание склада отвечает метод /locations/upsert.

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

Ниже перечислены обязательные атрибуты для создания склада:

Атрибут

Тип

Описание

title

Строка

Уникальное наименование склада

operationId 

Строка (UUID)

Идентификатор операции, требующийся getalon* для внутреннего обслуживания запросов.

id 

Строка

Уникальный внутренний идентификатор склада

description

Строка

Описания или уточняющая информацию по складу

С полным списком атрибутов можно ознакомиться в спецификации метода, в вкладке Schema.

Обновление

Для обновления информации по существующим складам также используется метод /locations/upsert, где в качестве указателя на обновляемый склад используется уникальный внутренний идентификатор склада – id (см. обязательные атрибуты для создания склада).

Обратите внимание, что возможно обновление как одного склада, так и множества.

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

Удаление

За удаление склада из маркетплейса отвечает метод /locations/delete. В качестве указателя на удаляемый склад используется уникальный внутренний идентификатор склада – id (см. обязательные атрибуты для создания склада).

Ниже перечислены атрибуты для удаления склада:

Атрибут

Тип

Описание

id        

Строка

Уникальный внутренний идентификатор склада переданные в атрибуте id при создании склада

operationId        

Строка (UUID)

Идентификатор операции, требующийся getalon* для внутреннего обслуживания запросов.

Обратите внимание, что возможно удаление как одного склада, так и множества.

Важно! Удаленные склады не подлежат восстановлению!

Номенклатура

Номенклатура – это список товаров или продукции, которые представлены в ассортименте предприятия. Выгрузка номенклатуры необходима для последующей выгрузки остатков по ней.

Добавление

Перед выгрузкой остатков на складах необходимо осуществить выгрузку номенклатуры. За это отвечает метод /offers/upsert.

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

Ниже перечислены обязательные атрибуты для создания склада:

Атрибут

Тип

Описание

crossNumbers

Массив строк

На текущий момент не используется системой. Рекомендуется передавать пустой массив.

description    

Строка

Описание товара. Рекомендуется иметь описание для информирования клиента о особенностях товара

id

Строка

Уникальный внутренний идентификатор товара

operationId

Строка (UUID)

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

productCode    

Строка

Артикул товара

title

Строка

Наименование товара

С полным списком атрибутов можно ознакомиться в спецификации метода, в вкладке Schema.

Обновление

Для обновления информации о товарах также используется метод /offers/upsert, где в качестве указателя на обновляемый товар используется уникальный внутренний идентификатор товара – id (см. обязательные атрибуты для создания товара).

Обратите внимание, что возможно обновление как одного товара, так и множества.

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

Удаление

За удаление товара из маркетплейса отвечает метод /offers/delete. В качестве указателя на удаляемый товар используется уникальный внутренний идентификатор товара – id (см. обязательные атрибуты для создания товара).

Ниже перечислены атрибуты для удаления склада:

Атрибут

Тип

Описание

id    

Строка

Уникальный внутренний идентификатор товара переданный в атрибуте id при создании товара

operationId    

Строка (UUID)

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

Обратите внимание, что возможно удаление как одного товара, так и множества.

Важно! Удаленные товары не подлежат восстановлению!

Остатки на складах

Остатки – это доступное для покупки кол-во единиц номенклатуры на тех или иных складах.

Добавление

Для выгрузки/добавления остатков товаров на складе используется метод /inventory_items/upsert.

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

Ниже перечислены обязательные атрибуты для выгрузки остатков:

Атрибут

Тип

Описание

amount

Число

Кол-во доступных единиц на складе

locationId    

Строка

Уникальный внутренний идентификатор склада, который был передан в getalon в атрибуте id при создании склада

offerId    

Строка

Уникальный внутренний идентификатор товара, который был передан в атрибуте id при создании товара

operationId    

Строка (UUID)

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

price        

Число

Цена товара

С полным списком атрибутов можно ознакомиться в спецификации метода, в вкладке Schema.

Обновление

Для обновления информации о товарах также используется метод /inventory_items/upsert, где в качестве указателя на обновляемый товар используется уникальный внутренний идентификатор товара – offerId (см. обязательные атрибуты для выгрузки остатков товара).

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

Обратите внимание, что возможно обновление остатков как для одного товара, так и для множества.

Список атрибутов аналогичен списку атрибутов для добавлению остатков товара.

Важно! По-умолчанию, если не передать атрибут replace явно, система посчитает, что replace равен false, что повлечет за собой создание новых остатков, а не обновление существующих.

Удаление

За удаление остатков на складах отвечает метод /inventory_items/delete. В качестве указателя на товар по которому удаляются остатки используется offerId (уникальный внутренний идентификатор товара, переданный при создании товара в атрибуте id), а в качестве указателя на склад locationId (уникальный внутренний идентификатор склада, переданный в атрибуте id при создании склада).

Ниже перечислены атрибуты для удаления остатков товара со склада:

Атрибут

Тип

Описание

locationId    

Строка

Уникальный внутренний идентификатор склада переданный в атрибуте id при создании склада

offerId        

Строка

Уникальный внутренний идентификатор товара переданный в атрибуте id при создании товара

operationId        

Строка (UUID)

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

Обратите внимание, что возможно удаление остатков по одному товару, так и по множеству.

Важно! Удаленные остатки не подлежат восстановлению!

Прочее

Получение результата операций

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

За получения результата отвечает метод /results/{batchOperationId}, где необходимо подставить полученный от getalon* идентификатор вместо {batchOperationId}.

Проверка статуса сервиса

В случае необходимости убедиться в работоспособности API и сервиса в целом применяется метод /ping. Его задача сводится к тому, чтобы вернуть сообщение о работе сервиса или ошибку.

Поддержка актуальности складов, номенклатур и остатков

На стороне систем учета могут регулярно происходит различные изменения, которые следует транслировать в getalon* в случае, если это затрагивает общие данные.

То есть, если появляется новый склад или изменились данные по существующему, то его необходимо выгрузить в getalon*, чтобы пользователь взаимодействовал с консистентными данными.

Транслирование изменений в getalon* может быть регламентным: любые изменения попадают в журнал и с некой регулярностью выгружаются в getalon*, либо изменения могут транслироваться сразу же после их фиксации.

Контакты

В случае возникновения вопросов, касающихся API, вы можете написать нашим менеджерам по следующим контактам: