API13 — актуальный публичный HTTP API для интеграций со складом и кассой ARM20. Через него сайт, CRM, ERP, мобильное приложение или другой сервис может безопасно вызывать разрешённые операции ARM20 в формате JSON.

API13 работает как защищённый шлюз: интеграция передаёт имя публичного метода и его параметры, а сервер сам определяет базу клиента, проверяет доступ и выполняет только операцию из официального каталога. Прямого доступа к базе данных, произвольного SQL или внутренних команд ARM20 API не предоставляет.

Важно для действующих интеграций: контракт API полностью обновлён. Старые URL, авторизацию через Basic Auth или логин и пароль в JSON, поля auth, meta.user_card и старые имена методов нельзя переносить в API13 без переработки.

Открыть документацию API13

Быстрый старт

Что изменилось в API13

Единый RPC-маршрут: POST https://api13.arm20.com/v1/rpc.
Авторизация ключом: в обычных RPC-запросах постоянный ключ формата a13k1.… передаётся только в заголовке Authorization: Bearer ….
Новый каталог: используйте точные имена методов из глобального поиска. Старые get.*, set.* и другие вызовы не следует считать совместимыми.
Базу определяет сервер: не передавайте tenant, реквизиты базы, URL, SQL или внутренние action/op.
Запись защищена от повторов: для каждой операции, изменяющей данные, обязателен заголовок Idempotency-Key.
Диагностика в ответе: сервер возвращает request_id и заголовок X-Request-Id. Сохраняйте их для поиска конкретного обращения.

Поля operator_id и user_id больше не определяют автора записи. API13 выполняет системные записи от технического пользователя Api_user с ID 1313. Если в конкретной бизнес-операции нужно выбрать пользователя или консультанта, используйте только отдельный параметр, описанный в карточке этого метода.

Возможности API

Текущий публичный каталог API13 содержит 273 именованных метода в десяти бизнес-блоках. Для каждого метода документация показывает тип операции, необходимый scope, параметры, точную форму результата, возможные ошибки и связанные методы.

Справочники — контрагенты, поставщики, дисконтные карты, категории, переводы и настройки.
Товары и склад — карточки товаров, цены, штрихкоды, аналоги, остатки, FIFO, изображения и массовые операции.
Накладные — создание, редактирование, импорт, проведение и налоговые реквизиты.
Финансы — движение средств, оплаты, долги, бонусы и лояльность.
Продажа — чеки, продажи, возвраты, скидки и смешанная оплата.
Касса — средства кассы, клиенты, сертификаты, FIFO, ценники и служебные документы.
ПРРО — фискализация, онлайн- и офлайн-очереди, повторная обработка и акцизные марки.
Отчёты — дневные итоги, напечатанные чеки, ресторанные и кухонные заказы.
Шаблоны печати — чтение, создание и сохранение шаблонов чеков и документов.
Сервис — безопасная проверка доступности API для базы текущего клиента.

Готовые последовательности методов для создания накладной, продажи, возврата, движения средств, дисконтной карты, карточки товара и очереди ПРРО приведены в разделе «Сценарии».

Как получить ключ и настроить доступ

Войдите в нужную базу в программе Windows Склад.
Откройте меню «Информация о лицензии».
Нажмите кнопку получения ключа API13 и скопируйте значение, начинающееся с a13k1..
Сохраните ключ в защищённой конфигурации конкретного пользователя интеграции.

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

Постоянный ключ имеет профиль администратора текущей базы, а роли операторов Windows к нему не применяются. Фактический перечень доступных ключу операций возвращает POST /v1/operations. Короткий токен формата a13s1.… — это отдельный сеансовый тип доступа с минимальными методами чтения согласно scopes. Подробнее: «Ключ и доступ».

Первый безопасный запрос

Начните с метода чтения service.ping или products.find_code. Не проверяйте новое подключение операцией записи.

curl https://api13.arm20.com/v1/rpc \
  -X POST \
  -H "Authorization: Bearer ВАШ_API_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "service.ping",
    "params": {},
    "id": "ping-001"
  }'

Поле id необязательно: это ваш идентификатор для сопоставления запроса с ответом. Сервер отдельно возвращает request_id. Успешный ответ имеет ok: true, а результат операции находится в data.result.

Запрос должен быть UTF-8 JSON размером не более 2 097 152 байт. Параметры проверяются строго: не добавляйте поля, которых нет в схеме метода. Точные денежные значения и количества часто возвращаются как десятичные строки, а бинарные или XML-данные — в Base64.

Полный формат запроса и типы результатов описаны на странице «Запросы RPC». JSON Schema конкретного метода доступна по адресу /v1/schemas/ИМЯ_МЕТОДА.json.

Пагинация коллекций

Для методов чтения со строковым результатом используйте POST /v1/rpc/page. Передайте тот же метод и параметры, limit от 1 до 500 и полученный cursor. Ответ содержит page.returned, page.total и page.next_cursor. Cursor не является snapshot: если данные между страницами изменились, выборку следует начать заново.

Операции записи и безопасные повторы

Для каждой новой бизнес-операции, изменяющей данные, интеграция до первой отправки создаёт отдельный Idempotency-Key — удобнее всего UUID v4 или UUID v7. Значение должно содержать 8–255 разрешённых ASCII-символов.

Idempotency-Key: nakl-create-0195d2d7-2a68-7d31-8f3a-7b6c5d4e3210

Новая запись: создайте новый ключ и сохраните его вместе с локальной операцией.
Timeout или обрыв: повторите тот же method и семантически те же params с тем же ключом.
Другое действие: создайте другой ключ, даже если оно относится к тому же документу или товару.
Чтение: Idempotency-Key не нужен.

Не генерируйте новый ключ во время автоматического retry. Завершённая операция вернёт сохранённый результат с Idempotency-Replayed: true; другой запрос с тем же ключом даст конфликт. Если результат отмечен как неопределённый, API13 намеренно не повторяет опасную запись: сначала сверьте документ, чек или платёж. Журнал завершённых и неопределённых операций хранится 90 дней. Полные правила: «Запись и повторы».

Ошибки: когда повторять запрос

400/422 — исправьте JSON, параметр, тип или формат; без исправления не повторяйте.
401 — проверьте Bearer credentials; для короткого токена получите новый сеанс.
403 — проверьте доступность метода через /v1/operations.
404 — проверьте точное имя публичного метода.
409 — выполните правило, соответствующее конкретному коду idempotency.
429 — подождите время из заголовка Retry-After.
502/503 — чтение можно повторить с backoff; после неопределённой записи сначала проверьте бизнес-результат.

HTTP-статус определяет общее действие клиента, а error.code — точную причину. Смотрите актуальный справочник ошибок.

Инструменты для разработчика

Глобальный поиск — поиск всех методов по имени, описанию, параметру, scope или термину Windows.
Проверка JSON — валидация метода, scope и параметров через /v1/rpc/validate без выполнения операции.
OpenAPI 3.1 — полная машинная схема; также есть меньшие схемы по бизнес-блокам.
SDK и коллекции — готовые клиенты для C#/.NET 8+, JavaScript/Node.js 18+, PHP 8.2+ и Postman.
Изменения API — версии публичного контракта и правила совместимости.

Чек-лист перехода со старого API

Получите отдельный ключ API13 в Windows Складе и сохраните его безопасно.
Для каждого старого вызова найдите новый именованный метод в каталоге и сверьте его JSON Schema.
Переведите RPC на POST /v1/rpc, Bearer-авторизацию и новый envelope method + params + id.
Удалите старые credentials в JSON, meta.user_card, реквизиты базы, operator_id/user_id и внутренние команды.
Добавьте сохранение request_id, корректную обработку HTTP-кодов и повторы чтения с backoff.
Для всех записей реализуйте постоянное хранение Idempotency-Key до первого запроса.
Сначала проверьте JSON через validate-only, затем выполните service.ping и один безопасный метод чтения.

Перед операциями записи создайте резервную копию рабочей базы: «Склад → Сервис → Резервная копия». API13 предназначен для профессиональных пользователей; некорректный запрос может повредить данные. Восстановление возможно только из резервной копии пользователя и может быть платной услугой.

Актуальная документация, схемы и примеры: api13.arm20.com/manual/.

API13 ARM20: открытый API для склада и кассы