API Asteril CRM для розробників

Через API зовнішні системи читають і змінюють дані CRM: замовлення, товари, залишки, статуси. Нові методи з'являються у версії v4, яка працює за єдиними правилами: ключі з окремими правами, фільтри, пагінація, дати з часовою зоною.

Довідник методів v4

Ключі API
Правила запитів
Історія змін замовлень
Версії API

Ключі API

Ключі для API v4 створює адміністратор CRM: Адміністрування → Налаштування → Ключі API → Додати ключ API.

Ключ показується повністю лише один раз, одразу після створення. Скопіюйте його і збережіть у надійному місці; далі в списку видно лише останні 4 символи.
Кожному ключу вибираються права (scope), наприклад orders.history. Метод доступний, лише якщо його scope є в ключі, інакше відповідь 403. Видавайте кожній інтеграції окремий ключ з мінімальним набором прав.
Ключ можна вимкнути або видалити. Запити з ним одразу отримають 403.
Перевірити ключ і його права: GET /api/v4/credentials.

Ключ передається в заголовку X-API-KEY (рекомендовано) або в параметрі apiKey:

curl -H "X-API-KEY: ваш_ключ" "https://ваш-субдомен.asteril.com/api/v4/credentials"

{"success": true, "scopes": ["orders.history"], "siteAccess": "all", "sitesAvailable": []}

Ключ, вшитий у код сайту чи браузерного застосунку, видно будь-кому, хто відкриє сторінку. Звертайтеся до API зі свого сервера.

Ключі старих версій API (v3 і SimpleAPI) у v4 не діють. Де їх знайти, описано в документації попередніх версій.

Правила запитів

Адреса	`https://ваш-субдомен.asteril.com/api/v4/…`, той самий домен, на якому ви входите в CRM
Відповідь	JSON: `success`, для списків `pagination`, далі масив сутності
Фільтри	`filter[name]=значення`, кілька значень: `filter[name][]=a&filter[name][]=b`
Пагінація	`limit` зі списку 20, 50, 100 (за замовчуванням 20), `page` від 1. У `pagination` повертаються `totalCount` і `totalPageCount`
Дати	У відповідях і фільтрах `YYYY-MM-DD HH:MM:SS`: `2026-10-03 14:28:24`
Часова зона	Необов'язковий параметр `timezone`, зараз підтримується `Europe/Kyiv` (за замовчуванням). Діє і на фільтри, і на відповідь
Ліміт	До 10 запитів на секунду з одного IP, спільно для всіх методів. Понад ліміт: 503 `Too many requests`

Помилки

{"success": false, "errorMsg": "Errors in the input parameters", "errors": {"limit": "Allowed values: 20, 50, 100"}}

400 — помилка в параметрах, подробиці по кожному полю в errors
403 — неправильний, вимкнений або видалений ключ, чи в ключі немає потрібного scope
404 — метод не існує
503 — перевищено ліміт запитів; повторіть запит за секунду

Робота з методами історії

Методи історії віддають журнал змін: хто, коли і що змінив, старе і нове значення. Так зовнішня система дізнається про зміни без перечитування всіх записів.

Методи

GET /api/v4/orders/history — історія змін замовлень, scope orders.history

Загальні принципи

Записи відсортовані за id за зростанням. Для послідовного обходу історії використовуйте filter[sinceId] замість пагінації: filter[sinceId] разом з page повертає помилку 400.

Перший запит без sinceId, наступні — з filter[sinceId], рівним збереженому id.
Обробіть отримані записи.
Збережіть id останнього запису для наступного запиту.
Якщо pagination.totalPageCount більше 1, одразу зробіть наступний запит з новим sinceId.

Запускайте обробку періодично, раз на 5–15 хвилин.

Поля запису

createdAt — час зміни у форматі YYYY-MM-DD HH:MM:SS, у зоні з timezone.
userId — хто змінив; 0 для змін, зроблених системою.
field — системне ім'я зміненого поля, наприклад status, responsible_id. Набір полів залежить від CRM, зокрема від її власних полів.
oldValue, newValue — старе і нове значення у тому вигляді, як у журналі змін замовлення; текст полів з розширеним форматуванням закодований urlencode.

Параметри, фільтри і приклади відповідей — у довіднику методів.

Версії API

v4	Актуальна версія, нові методи з'являються тут. Ключі з правами по методах. Довідник методів
v3, v3.1, SimpleAPI	Працюють і далі: створення й оновлення замовлень, товари, залишки, склад, завдання, вебхуки. Документація

Якщо потрібного методу ще немає у v4 або є питання щодо інтеграції, напишіть на office@asteril.com або в Telegram.