Описание API

API предназначено для экспорта заказов и ТТН(товарно-транспортных накдажных) в складскую систему и отслеживания их статусов.

Формат обмена

В качестве протокола в API используется JSON RPC.
Сообщение отправляется методом POST и в общем случае имеет вид:
{"jsonrpc": "2.0", "method": "echo", "params": {"say": "Привет"}, "id": 1}

  • jsonrpc - всегда "2.0"
  • method - вызываемая функция
  • params - параметры (необязательное поле)
  • id - идентификатор запроса
Идентификатор запроса возвращается в ответе и может быть любым но уникальным в случае пакетного (batch) запроса, поскольку сервер может быть асинхронным и вернуть ответы в произвольном порядке. В случае отсутствия идентификатора считается что запрос - нотификация то есть не требует ответа от сервера.
Пакетный запрос
[{"jsonrpc": "2.0", "method": "echo", "params": {"say": "Привет"}, "id": 1}, {"jsonrpc": "2.0", "method": "echo", "params": {"say": "Пока"}, "id": 1} ]
Ответ имеет в общем случае вид
{"jsonrpc": "2.0", "result": {"answer": "Привет"}, "id": 1}
  • jsonrpc - всегда "2.0"
  • result - ответ
  • error - в случае ошибки возвращается вместо result
  • id - соответствующий идентификатор из запроса

Авторизация

Тип авторизации задается в настройках системы и может быть на основе JWT токена, Basic аутентификации или авторизация может не использоватся (внутри корпоративной сети например). Bearer и Basic аутентификация отправяется стандартным образом в заголовке Authorization. Для Bearer предварительно необходимо получить JWT токен.

Список функций

Для логического разделения запросов используется несколько точек входа (endpoints)
Название URL (endpoint) Команда Параметры Пример Примечание
проверка API /api/common checkapi
Получить токен /api/common token login - логин
password - пароль
{"login":"admin","password":"admin"}
Список складов /api/items storelist
Список категорий /api/items catlist
Список артикулов /api/items articlelist
Список ТМЦ /api/items itemlist cat_id - id категории {"cat_id":"10"} Если категория не задана возвращается весь список. Поле descriptiion возвращается в кодировке base64
Текущие количества на складах /api/items getqty store_id - id склада {"store_id":"1"} Если склад не задан возвращается весь список.
Записать ТМЦ /api/items save itemname - наименование, обязательное поле
item_code - артикул, обязательное поле
bar_code - штрих-код
measure - ед. измерения
manufacturer - производитель, бренд
cat_id - id категории
price1,... - отпускные цены
desсription - описание, кодированное в base64
{ "item_code":"К001","bar_code":"К001","itemname":"testapi","description":"","measure":"шт","manufacturer":"", "cat_id":"0","price1":50} Если артикул (item_code) существует то ТМЦ перезаписывается, если отсутствует то создается новая запись.
Список контрагентов /api/customers list
Записать контрагента /api/customers save customer_id - id контрагента
customer_name - наименование, обязательное поле
phone - телефон, рекомендуется вводить в виде 10 цифр
email - email
city - город
address - адрес
desсription - описание, кодированное в base64
{"customer_id":"8","customer_name":"\"ООО Вектор2\"","phone":"0991111111","email":"test@ukr.net","city":"","address":""} Если customer_id больше нуля то контрагент перезаписывается, если равно нулю или отсутствует то создается новый.
Список статусов документов /api/docs statuslist Не все статусы подходят ко всем типам документов
Список касс и денежных счетов /api/docs mflist
Список филиалов /api/docs branchlist Если в складской системе включена поддержка филиалов необходимо указывать филиал в создаваемом документе
Создание заказа если обработка и оплата выполняется в складской системе /api/docs createorder number - номер документа. Уникальное значение, связаное с заказом экспортирующей системы. Обязательное поле
phone - телефон, на случай если контакт отличается от телефона контрагента
email - email, на случай если контакт отличается от email контрагента
ship_address - адрес доставки, и прочие данные доставки
decription - коментарий в base64
branch_id - филиал, если включено
amount - итого по документу которое к оплате. На слчучай если отличается от итогов по позициям (например изза скидки)
items - список позиций
item_code - артикул
quantity - количество
price - цена
{"number":"ID0001","phone":"0971111111","ship_address":"Харьков","items":[{"item_code":"cbs500-1","quantity":2,"price":234},{"item_code":"ID0018","quantity":2,"price":234}] }
Создание ТТН если нужно только списание со склада /api/docs createttn number - номер документа. Уникальное значение экспортирующей системы. Обязательное поле
phone - телефон, на случай если контакт отличается от телефона контрагента
email - email, на случай если контакт отличается от email контрагента
ship_address - адрес доставки, и прочие данные доставки
decription - коментарий в base64
branch_id - филиал, если включено
total - итого по документу которое к оплате. На случай если отличается от итогов по позициям (например изза скидки)
items - список позиций
item_code - артикул
quantity - количество
price - цена
{"number":"ID0001","store_id":19,"customer_id":8,"phone":"0971111111","ship_address":"Харьков","items":[{"item_code":"cbs500-1","quantity":2,"price":234},{"item_code":"ID0018","quantity":2,"price":234}] }
Создание расходной накладной /api/docs goodsissue number - номер документа. Уникальное значение экспортирующей системы. Обязательное поле
mf - каcса или банковский счет
branch_id - филиал, если включено
customer_id - контрагент
store_id - склад, обязательное поле
autoexec - true, если надо записать проводки
total - итого по документу которое к оплате. На случай если отличается от итогов по позициям (например изза скидки)
payed - внесена сумма оплаты.
items - список позиций
item_code - артикул
quantity - количество
price - цена
{"number":"ID0001","store_id":19,"customer_id":8,"mf":2,"total":220,"payed":220,"items":[{"item_code":"cbs500-1","quantity":2,"price":234},{"item_code":"ID0018","quantity":2,"price":234}] }
Создание приходной накладной /api/docs goodsissue number - номер документа. Уникальное значение экспортирующей системы. Обязательное поле
mf - каcса или банковский счет
branch_id - филиал, если включено
customer_id - контрагент . Обязательное поле
store_id - склад, обязательное поле
autoexec - true, если надо записать проводки
total - итого по документу которое к оплате. На случай если отличается от итогов по позициям (например изза скидки)
payed - внесена сумма оплаты.
items - список позиций
item_code - артикул
quantity - количество
price - цена
Оприходование ТМЦ /api/docs incomeitem number - номер документа. Уникальное значение экспортирующей системы. Обязательное поле
mf - каcса или банковский счет
branch_id - филиал, если включено
store_id - склад, обязательное поле
autoexec - true, если надо записать проводки
total - итого по документу которое к оплате. На случай если отличается от итогов по позициям (например изза скидки)
items - список позиций
item_code - артикул
quantity - количество
price - цена
{"number":"ID0001","autoexec":true,"store_id":19,"customer_id":8,"mf":2,"total":220,"payed":220,"items":[{"item_code":"cbs500-1","quantity":2,"price":234},{"item_code":"ID0018","quantity":2,"price":234}] }
Статусы документов по списку номеров /api/docs checkstatus numbers - список номеров документов {"numbers":["З-00002","ТТН00034"] } Возвращаются только те документы которые созданы через API. По возвращенным статусам обновляется состояние заказов в экспортируюшей системе
Запрос на удаление. /api/docs cancel number - номер документа
reason - причина
{"number": "ТТН00034","reason":"Тест" } Запрос администратору склада на удаление документа. Например если заказ отменен но уже экспортирован.

Коды ошибок

-1000 Неверный логин
-1001 Пользователь не найден
-1002 Просроченый токен
-1003 Неверный синтаксис
-1004 Неверный запрос
-1005 Неверная команда