Обзор
API WEBRA связывает учётную систему поставщика с B2B-порталом. Здесь описано, как устроен обмен и с чего начать подключение.
Что делает API
Через API учётная система передаёт на портал всё, что видит покупатель: товары и категории, цены, остатки, клиентов, договоры, документы и взаиморасчёты. С портала учётная система забирает новые заказы и сообщает, что с ними происходит дальше.
Учётная система может быть любой. Все интеграции идут через API WEBRA, отдельных модулей под конкретную систему нет.
Портал работает на своих данных
WEBRA хранит переданные данные у себя. Поэтому портал и мобильное приложение работают, даже когда учётная система недоступна: покупатели видят каталог, свои цены и остатки на момент последнего обмена и оформляют заказы. Новые заказы ждут на портале, пока учётная система их не заберёт.
Отсюда главное правило интеграции: учётная система сама отправляет изменения и сама забирает заказы. Портал не обращается к учётной системе по своей инициативе. Исключение составляют вебхуки, о них ниже.
Как устроен обмен
У API одна точка входа. Все запросы отправляются методом POST с телом в JSON:
POST https://api.<домен портала>/api/v1/jsonВ теле указывают ключ, модель и метод. Модель означает тип данных, например Orders (заказы) или Prices (цены). Метод задаёт действие с ними.
{
"baseID": "YOUR_BASE_ID",
"apiKey": "YOUR_API_KEY",
"modelName": "Measures",
"calledMethod": "set",
"methodProperties": [
{ "ref": "e13dc1b8-cbef-11e9-80b9-9fcdd98760c5", "deletionFlag": false, "code": "2009", "name": "шт" }
]
}Из учётной системы на портал
Данные передаются методом set, а для цен, остатков и товаров есть ещё update, который меняет только переданные позиции.
API проверяет запрос и ставит данные в очередь. Ответ "status": "success" означает, что данные приняты, а не что они уже на портале. Обычно портал обрабатывает очередь в течение минуты. Результат обработки каждого объекта виден в админке портала, в журнале «Обработка запросов обмена».
С портала в учётную систему
Новые заказы учётная система забирает сама методом get. Создав заказ у себя, она подтверждает его методом confirm. Пока заказ не подтверждён, он возвращается при каждом запросе, поэтому заказ не потеряется, если обмен прервался.
Вебхуки
Портал может сам сообщать о двух событиях: новый заказ и новый пользователь. Он отправляет POST с данными события на адрес, который вы укажете. Вебхук не заменяет Orders/get: это сигнал, что пора забрать заказ, или способ передать событие в другую систему, например в CRM.
Основные понятия
| Понятие | Что означает |
|---|---|
ref | Идентификатор объекта в учётной системе, обычно GUID. Портал связывает все данные по ref: товар с ценой, заказ с договором. Свои идентификаторы портал не придумывает. |
deletionFlag | Пометка на удаление. Объект с true скрывается на портале, но остаётся в базе. |
baseID | Идентификатор вашей информационной базы. Помогает отличить рабочую базу от её копии. |
| Пакет | Массив объектов в methodProperties. Справочники и документы передавайте пакетами до 50 объектов. Цены и остатки передавайте по одному объекту в запросе: один тип цен или один склад со всеми товарами. |
set и update | set создаёт или полностью обновляет объект. Для цен и остатков set заменяет весь тип цен или склад, а update меняет только переданные товары. |