REGOS API — это инструмент для интеграции сайта или приложения с сервисом REGOS, который позволяет автоматизировать работу с номенклатурой, заказами, остатками, закупками и другими операциями в розничной торговле. Этот гид создан для того, чтобы вы быстро разобрались в структуре и логике API: от получения доступа до работы с ключевыми методами. После прочтения станет ясно, как строятся запросы, как использовать основные сущности и как настраивать уведомления через вебхуки.
Вступайте в наш закрытый Telegram-канал для разработчиков, чтобы быть в курсе обновлений API и лучших практик интеграции и лайфхаков
Чтобы начать работу с API, нужно получить два ключевых элемента: Endpoint и id интеграции (connected_integration_id). Они генерируются автоматически при создании интеграции в REGOS.Online. Endpoint представляет собой базовый адрес, к которому будут отправляться запросы, а connected_integration_id — уникальный идентификатор вашей интеграции.
После создания интеграции в личном кабинете REGOS.Online вы получите Endpoint для выполнения запросов к API, строковый ключ вида 11v5929ba236415hb31346ede021bdi4.
Пример формата Endpoint:
https://integration.regos.uz/gateway/out/{integrationKey}/v1/{method}
Например, если вы хотите получить информацию об аккаунте, запрос будет выглядеть так:
https://integration.regos.uz/gateway/out/11v5929ba236415hb31346ede021bdi4/v1/Account/Get
Все запросы к REGOS API выполняются методом POST. Формат обмена данными — JSON. Это значит, что вы отправляете JSON-тело и получаете структурированный JSON-ответ, в котором всегда есть код выполнения, сообщение и тело ответа. Такой единый подход позволяет работать с любыми сущностями — будь то товары, документы или операции — по одинаковой схеме.
Важно помнить, что запросы требуют обязательных заголовков, а структура ответов стандартизирована.
Если нужно разобраться подробнее в том, как именно строятся запросы, в официальной документации есть отдельная глава, с примерами кода:
Отдельно стоит изучить перечень ошибок, чтобы заранее понимать, как интерпретировать коды и сообщения при работе с API.
Иногда требуется выполнить несколько методов подряд, передавая результат одного шага в другой. Для этого в REGOS: API предусмотрен механизм batch-запросов. Он позволяет объединять до 50 вызовов API в один HTTP-запрос, отправить его на единый и получить массив ответов.
Как работать с пакетными (batch) запросами.
REGOS API имеет встроенные ограничения на частоту запросов. Они нужны для того, чтобы все интеграции работали стабильно и равномерно. Лимиты реализованы по принципу «счётчика запросов», который постепенно пополняется с течением времени.
Это значит, что можно отправлять burst-запросы (то есть пачку подряд), но только в пределах накопленного лимита. Когда счётчик исчерпан, новые запросы будут отклоняться до тех пор, пока счётчик не восстановится.
Подробное описание механизма можно найти в разделе лимиты запросов.
Архитектура REGOS API построена вокруг различных сущностей. Главная из них — номенклатура товаров, которая обозначается как Item. Кроме этого, есть документы (все методы начинаются с Doc*) и операции (Operation*).
Общая логика всегда одинакова: сначала создаётся основной документ, например закупка, продажа или заказ, а затем к нему добавляются операции, которые содержат конкретные позиции с товарами, количеством и ценой. Такой подход обеспечивает атомарность: документ является агрегатором операций и позволяет корректно рассчитывать итоговые суммы, НДС и другие показатели.
Многие методы API поддерживают фильтрацию. Например, при получении данных можно ограничить выборку по датам, ID сущностей или использовать поиск по коду и наименованию.
Независимо от того, работаете ли вы с товарами или документами, все методы вызываются через POST и принимают JSON-тело с параметрами фильтрации.
Номенклатура — это базовая сущность в REGOS. В ней содержатся данные обо всех товарах, и именно она используется при формировании заказов, отчётов, чеков продаж или возвратов.
Для работы с номенклатурой есть несколько методов. Метод Item/Get возвращает базовый список номенклатуры и поддерживает фильтрацию по ID или имени. Более расширенная версия метода — Item/GetExt. Она дополнительно возвращает цены, остатки и ссылки на изображения. Если вам нужно получить только текущее количество товара на складе, то для этого используется метод Item/GetQuantity.
Отдельно стоит отметить работу с изображениями. Так как ресурсы CDN ограничены, рекомендуется скачивать изображения на свой сервер и работать уже с локальными копиями. Это снижает вероятность блокировки по лимитам.
Документы закупки в REGOS обозначаются как DocPurchase. Они отражают поступления товаров от контрагентов. Логика работы всегда одна: сначала создаётся документ, в котором фиксируются основные параметры (дата, код документа, контрагент, склад, валюта и так далее). После этого к документу добавляются операции, где указываются позиции номенклатуры, количество и цены.
Для выборки документов закупки используется метод DocPurchase/Get. Он поддерживает фильтрацию по дате, ID контрагентов, фирм или складов, а также поиск по коду и наименованию. Чтобы создать документ, его сначала нужно добавить через API, а затем наполнить операциями с помощью метода PurchaseOperation/Add. Таким образом обеспечивается целостность данных: документ — это «шапка», а операции — детали.
Для работы с заказами от клиентов используется сущность DocOrderDelivery. Этот тип документа предназначен для того, чтобы передавать заказы с сайта или приложения в систему REGOS.
Создание заказа может выполняться по упрощенной схеме через метод DocOrderDelivery/AddFull. В одном запросе вы указываете партнёра, список позиций с идентификаторами товаров, их количеством и ценами. В результате формируется полный документ заказа, готовый к обработке в системе.
Для мониторинга изменений и событий, которые происходят в REGOS, предусмотрена поддержка вебхуков. Это асинхронный механизм: при наступлении события система сама отправляет POST-запрос на ваш сервер. Например, вы можете получать уведомления об изменении статуса заказа без необходимости опрашивать API вручную.
Чтобы использовать вебхуки, нужно при создании локальной интеграции указать URL вашего обработчика и подписаться на те события, которые вы хотите получать. После этого REGOS будет автоматически отправлять уведомления в ваш сервис. Более подробную информацию можно найти в разделе Вебхуки.
Мы рекомендуем начинать работу с API через тесты в Postman, используя полученный Endpoint . Это позволит вам проверить структуру запросов и убедиться в правильности ответов. Для дальнейшего изучения всегда можно обратиться к полной документации. В случае возникновения вопросов техническая поддержка REGOS поможет разобраться.