Перейти до основного вмісту

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

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

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

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

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

Rate limit​

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

429 Too Many Requests

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

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

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

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

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

Важливо:

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

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

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

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

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

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

429 Too Many Requests

з помилкою:

Concurrent write locked
попередження

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

Пагінація​

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

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

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

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

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

  • updated_from;
  • updated_to.

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

інформація

Зміна кількості залишків або резерву не оновлює updated_at товару. Для залишків використовуйте API-звіти, а не тільки фільтр updated_from по товарах.

Read і write запити​

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

  • GET /v1/products
  • GET /v1/contragents
  • GET /v1/documents
  • GET /v1/reports/remains

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

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

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

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

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

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

Підсумок​

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

Останнє оновлення