Ліміти та безпечна робота з API

API Skynum має ліміти, які допомагають платформі й інтеграціям працювати стабільно.

Базові правила

Усі інтеграції мають:

• не робити агресивний polling;
• не обходити повторно дані, які не змінювалися;
• зберігати на своїй стороні документи, платежі та інші дані, які потрібні інтеграції;
• для документів і платежів після первинного завантаження використовувати тільки інкрементальну синхронізацію через updated_from / updated_to;
• використовувати пагінацію;
• не запускати паралельно запити на запис;
• обробляти 429 Too Many Requests;
• повторювати запит тільки після паузи;
• логувати помилки й відповіді API;
• не видаляти та не активувати обʼєкти без явної бізнес-логіки.

Rate limit

API може повернути:

429 Too Many Requests

Це означає, що запитів було занадто багато за короткий час або компанія перевищила доступний ліміт виконання.

Якщо отримали 429:

1. зменште частоту запитів;
2. додайте паузу перед повтором;
3. уникайте пакетів із великою кількістю одночасних запитів;
4. перевірте, чи інтеграція не робить зайвий polling;
5. для запису використовуйте чергу.

Ліміт часу виконання

Для кожної компанії діє ліміт сумарного часу обробки API-запитів: 5 хвилин у межах рухомого 1-годинного вікна, якщо для компанії не налаштовано індивідуальний ліміт.

Якщо вашій інтеграції справді потрібно більше, напишіть у підтримку — індивідуальний ліміт налаштовується.

Важливо:

• рахується саме час виконання запитів;
• вікно рухоме, воно не скидається в конкретну хвилину;
• коли ліміт перевищено, нові запити відхиляються одразу;
• відповідь містить кількість секунд, яку потрібно зачекати перед повтором.

Один write-запит одночасно

Для однієї компанії одночасно може виконуватися тільки один запит на запис.

До write-запитів належать:

• POST;
• PUT;
• PATCH;
• DELETE.

Якщо інший write-запит уже виконується, API поверне:

429 Too Many Requests

з помилкою:

Concurrent write locked

попередження

Не відправляйте паралельно кілька запитів на створення або оновлення документів, платежів, товарів чи контрагентів. Запити на запис мають проходити через чергу.

Ліміти окремих ресурсів

Крім загальних лімітів, окремі розділи API мають власні правила частоти. Зібрали їх тут, щоб усе було в одному місці.

Ресурс	Ліміт
Повна синхронізація товарів (GET /v1/products без фільтрів дат)	не частіше 1 разу на добу
Інкрементальна синхронізація товарів (updated_from / updated_to)	можна частіше; орієнтир: раз на 10 хвилин
Документи (GET /v1/documents)	після первинного завантаження: тільки інкрементальна синхронізація через updated_from / updated_to
Платежі (GET /v1/payments)	після первинного завантаження: тільки інкрементальна синхронізація через updated_from / updated_to
Усі звіти (/v1/reports/*, report_tasks)	не частіше 1 разу на годину

Для документів і платежів правило повної синхронізації "раз на добу" не застосовується. Регулярний сценарій має бути таким: інтеграція зберігає отримані записи у себе, а потім забирає тільки записи, які змінилися.

Не робіть регулярний повний обхід усіх існуючих документів або платежів. Мається на увазі сценарій, коли інтеграція щоразу читає всю історію без updated_from / updated_to, а потім відкриває кожен запис окремим запитом, щоб перевірити, чи він змінився.

Нормальний сценарій: отримати через updated_from / updated_to список документів або платежів, які змінилися, і за потреби окремо відкрити тільки ці записи. Якщо інтеграція регулярно робить повний обхід усієї історії, API-доступ компанії або окремого API-користувача може бути обмежений чи заблокований.

Деталі й правильні сценарії синхронізації: Товари через API, Документи через API, Платежі через API, Звіти через API.

Синхронізуйте тільки зміни

Повторні проходи по записах, які не змінювалися, витрачають ліміт часу виконання вашої компанії, тому інтеграція працює повільніше, ніж могла б. Синхронізація тільки змін робить її швидшою і стабільнішою.

Для документів і платежів це обовʼязковий сценарій після первинного завантаження. Регулярне повне перечитування цих ресурсів не підтримується, навіть якщо запускати його раз на добу.

Що допомагає:

• зберігайте на своїй стороні час останньої успішної синхронізації і запитуйте тільки зміни через updated_from / updated_to;
• замість повного перечитування каталогу, документів або контрагентів "про всяк випадок" покладайтеся на інкрементальну синхронізацію;
• зміни зручніше отримувати одним фільтрованим списком, ніж перевіряти записи поштучно окремими запитами;
• результати звітів варто зберігати на своїй стороні й оновлювати за розкладом.

Якщо ресурс не має фільтрів за датою оновлення, синхронізуйте його не частіше, ніж це дозволяють ліміти, або зверніться до нас у підтримку. Ми допоможемо знайти рішення.

Проєктуйте інтеграцію під мінімум запитів

Кількість запитів залежить від того, як спроєктована інтеграція. Ще на етапі дизайну закладайте:

• власне сховище: тримайте копію потрібних даних Skynum у своїй системі й працюйте з нею, а до API ходіть тільки за змінами;
• кешування: результат, який потрібен кільком частинам вашої системи, отримуйте одним запитом і роздавайте зі свого кешу, а не запитуйте з кожного місця окремо;
• агрегацію: один запит зі списком і фільтрами замість серії точкових запитів по одному запису.

Якщо для вашого сценарію доводиться постійно опитувати той самий ресурс, в API може бракувати можливості під ваш кейс. Напишіть у підтримку й опишіть сценарій: ми охоче розглянемо доробку, наприклад фільтр, поле або окремий endpoint. Так ваша інтеграція отримає надійне рішення замість постійного опитування, яке впирається в ліміти.

Пагінація

Спискові запити використовують параметри:

• offset — номер сторінки, за замовчуванням 1;
• limit — кількість записів, за замовчуванням 100, максимум 1000.

Якщо потрібно отримати багато записів, не ставте надмірний limit. Проходьте дані сторінками.

Оновлення за датою

Для частини ресурсів є фільтри:

• updated_from;
• updated_to.

Їх зручно використовувати для інкрементальної синхронізації.

інформація

Зміна залишків, резервів або очікувань оновлює updated_at товару. Для інкрементальної синхронізації товарів використовуйте updated_from і updated_to; якщо разом із товарами потрібні складські показники, додайте extended=true.

Read і write запити

Read-запити й запуск звітів отримують дані:

• GET /v1/products
• GET /v1/contragents
• GET /v1/documents
• POST /v1/reports/product_balances

Write-запити змінюють дані:

• POST /v1/products
• PUT /v1/documents/:id
• PUT /v1/documents/:id/activate
• DELETE /v1/payments/:id

Write-запити потребують особливої обережності, бо вони можуть змінювати облік.

Чеклист інтеграції

Перед запуском перевірте:

• інтеграція використовує окремого API-користувача;
• токен не зберігається в публічному коді;
• дані Skynum кешуються на вашій стороні, а не запитуються повторно;
• усі write-запити йдуть через чергу;
• 429 обробляється без нескінченних повторів;
• списки читаються через offset і limit;
• для синхронізації використовуються фільтри дат, де вони доступні;
• видалення, деактивація й активація виконуються тільки за підтвердженою бізнес-логікою;
• помилки логуються разом із URL, методом, часом і тілом відповіді.

Підсумок

API Skynum призначений для бізнес-інтеграцій, а не для високочастотного опитування. Найважливіше правило: читання можна масштабувати обережно, а всі запити на запис потрібно ставити в послідовну чергу.