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 для складу та каси