Интеграция при помощи 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 

id 

description

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

Обновление

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

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

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

Удаление

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

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

id        

operationId        

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

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

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

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

Добавление

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

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

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

crossNumbers

description    

id

operationId

productCode    

title

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

Обновление

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

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

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

Удаление

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

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

id    

operationId    

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

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

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

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

Добавление

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

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

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

amount

locationId    

offerId    

operationId    

price        

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

Обновление

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

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

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

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

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

Удаление

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

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

locationId    

offerId        

operationId        

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

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

Прочее

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

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

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

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

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

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

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

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

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

Контакты

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

• Сергей Евменов, s.evmenov@getalon.ru
• Григорий Сидоров, g.sidorov@getalon.ru