Как сделать интеграцию с Мой Склад

В этой статье рассмотрим как сделать интеграцию платформы Falcon Space с Мой Склад на примере вывода отчета из Мой Склад в виде таблицы.

Документация по API Мой Склад: https://dev.moysklad.ru/doc/api/remap/1.2/

Мы будем брать данный отчет: https://dev.moysklad.ru/doc/api/remap/1.2/reports/#otchety-otchet-pribyl-nost-poluchit-pribyl-nost-po-sotrudnikam

Также для интеграции понадобятся логин и пароль от МойСклад. 

1. Для авторизации нам необходимо закодировать в base24 в формате логин:пароль (https://www.base64encode.org/). Данное значение будет использоваться для Basic авторизации через header при каждом запросе к Мой Склад.

Генерация Base64 в SQL Server - https://stackoverflow.com/questions/5082345/base64-encoding-in-sql-server-2005-t-sql

2. Создаем метод исходящего API, например ms1.  Тип GET JSON. 

Настройка запроса request: 

CREATE PROCEDURE [dbo].[api_ms1_request]
	@parameters ExtendedDictionaryParameter READONLY,  
	@username nvarchar(32)  -- текущий пользователь.
AS
BEGIN
    -- SELECT 1  Msg, Result, Url (адрес, куда будет идти запрос)
    declare @url nvarchar(256)
    set @url = 'https://online.moysklad.ru/api/remap/1.2/report/profit/byemployee'
    select '' Msg, 1 Result, @url Url 
    -- SELECT 2 PARAMETERS - параметры, которые будут передаваться во внешний источник
    --select 'Authorization' name, 'Basic XXXXXXXXXXXXXXXXXXX' value, 'header' [type]  
END

Response процедура остается по умолчанию: 

CREATE PROCEDURE [dbo].[api_ms1_response]
	@response nvarchar(max),
	@parameters ExtendedDictionaryParameter READONLY, 
	@username nvarchar(32)
AS
BEGIN
	-- SELECT 1
	select '' Msg, 1 Result, @response Response
	-- SELECT 2 Внешние действия
END

Примечание: процедура request служит для подготовки параметров запроса, а процедура response вызывается для обработки пришедшего ответа от внешней системы.

Здесь мы можем проверить, что выдает нам внешний API (формат JSON) и подготовить обработку этих данных через SQL с функциями работы с JSON. 

Пример для данного варианта отчета: 

declare @s nvarchar(max) = '{ ... большой JSON от API... }' 

SELECT 
	JSON_VALUE(value,'$.employee.name') employeeName,
	JSON_VALUE(value,'$.salesCount') salesCount,
	JSON_VALUE(value,'$.salesAvgCheck') salesAvgCheck,
	JSON_VALUE(value,'$.sellSum') sellSum,
	JSON_VALUE(value,'$.sellCostSum') sellCostSum,
	JSON_VALUE(value,'$.returnCount') returnCount,
	JSON_VALUE(value,'$.returnAvgCheck') returnAvgCheck,
	JSON_VALUE(value,'$.returnSum') returnSum,
	JSON_VALUE(value,'$.returnCostSum') returnCostSum,
    JSON_VALUE(value,'$.profit') profit,
    JSON_VALUE(value,'$.margin') margin
FROM OPENJSON(@s, '$.rows') 

Данный запрос мы сможем в таблице использовать для извлечения данных, полученных от API.

3. Создаем страницу и добавляем на ее сниппет таблицы.

<div class="as-table" data-code="ms1"></div>

Примечание: имя таблицы не обязательно должно совпадать с request API кодом. 

4. Создаем таблицу, создаем колонки с именами полей, прописываем источник API = ms1.  Эта настройка приводит к тому, что перед загрузкой таблицы идет обращение к исходящему запросу API и его ответ поступает на вход процедуры GetItems (в параметре @filters). 

5. Прописываем GetItems таблицы: 

CREATE PROCEDURE [dbo].[crud_ms1_getItems]
	@filters ExtendedDictionaryParameter READONLY,  
	@sort sql_variant,
	@direction nvarchar(8),
	@page int,
	@pageSize int,
	@username nvarchar(32)
AS
BEGIN
	declare   @ids TABLE (id int)

	declare @s nvarchar(max) = (select top 1 Value2 from @filters where [key]='ms1')
	--print @s
	-- SELECT 1
	SELECT 
      JSON_VALUE(value,'$.employee.name') employeeName,
      JSON_VALUE(value,'$.salesCount') salesCount,
      JSON_VALUE(value,'$.salesAvgCheck') salesAvgCheck,
      JSON_VALUE(value,'$.sellSum') sellSum,
      JSON_VALUE(value,'$.sellCostSum') sellCostSum,
      JSON_VALUE(value,'$.returnCount') returnCount,
      JSON_VALUE(value,'$.returnAvgCheck') returnAvgCheck,
      JSON_VALUE(value,'$.returnSum') returnSum,
      JSON_VALUE(value,'$.returnCostSum') returnCostSum,
      JSON_VALUE(value,'$.profit') profit,
      JSON_VALUE(value,'$.margin') margin
	FROM OPENJSON(@s, '$.rows') 

	-- SELECT 2
	select 1

	-- SELECT 3
    select 1 Compact, 1 HideTitleCount
END

Здесь мы извлекаем данные из API Response и трансформируем в табличные данные, которые выводятся в таблице на странице. 

Таким образом, мы извлекли данные по API, трансформировали их в табличные данные из JSON и вывели через компонент Таблица на странице. 

Аналогичным образом можно данные сохранять в БД, вызывать управляющие действия (вызов исходящего запроса API через кнопку Отправить в Форме).