API v1 · лише читання

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

Вивантажуйте угоди, криейторів і статистику трекінгу бренду у свою CRM, BI чи сховище. У v1 — лише читання. Доступ — на тарифі «Макс», ключ створює власник акаунта бренду в розділі «Інтеграції», вкладка «API».

Схема OpenAPI 3 (JSON)

Ключі доступу

Ключ належить акаунту бренду. Повний ключ показується один раз — одразу після створення.

Створити ключ

Автентифікація

Кожен запит — із заголовком Authorization: Bearer un_live_…. Ключ належить акаунту бренду, а не людині, і бачить лише дані цього акаунта.

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

curl -H "Authorization: Bearer $UNICORN_API_KEY" \
  "https://<домен платформи>/api/public/v1/deals?limit=50"

Ресурси

Базова адреса — /api/public/v1. Усі ресурси — GET; кожен вимагає свого дозволу ключа.

Ресурс	Дозвіл	Що віддає
`GET /deals`	deals:read	Угоди акаунта: номер, назва, статус, тип угоди, сторона, контрагент, сума й валюта, дедлайн, строк розміщення, дати.
`GET /creators`	creators:read	Криейтори, яких бренд відстежує в трекінгу, з підсумками замовлень і доходу за весь час.
`GET /tracking/campaigns`	tracking:read	Кампанії трекінгу: промокод, період, охоплення, винагорода, підсумки замовлень і доходу.

Гроші — цілими мінорними одиницями (копійками) у полях *_minor, валюта — поруч у currency. Дати — ISO 8601 з часовим поясом.

Пагінація

Курсорна. Відповідь — { data: [...], next_cursor }. За наступною сторінкою — той самий запит із ?cursor=<next_cursor>; null означає, що сторінок більше немає. limit — від 1 до 100, типово 50. Записи йдуть за часом створення, і нові під час обходу не зсувають уже пройдених сторінок. Курсор непрозорий — не розбирайте його.

{
  "data": [{ "id": "…", "number": 1042, "title": "Огляд сироватки", "amount_minor": 1500000, "currency": "UAH", … }],
  "next_cursor": "AZJxk2…"
}

Квоти

Квоти — на акаунт, за тарифом: на «Макс» — 50 000 запитів на місяць і 10 000 на добу (доба й місяць — за київським часом). Окремо — не більше 120 запитів на хвилину з одного ключа. Залишок — у заголовках кожної відповіді.

Заголовок	Що означає
`X-Quota-Day-Limit`	запитів на добу за тарифом
`X-Quota-Day-Remaining`	скільки лишилось сьогодні
`X-Quota-Month-Limit`	запитів на місяць за тарифом
`X-Quota-Month-Remaining`	скільки лишилось цього місяця

Запит понад квоту отримує 429 із Retry-After і не зараховується.

Помилки

Тіло помилки — { type, title, status, detail, errors }.

Код	Коли
`400`	невірний cursor або limit
`401`	немає заголовка, ключ невірний або відкликаний
`403`	у тарифі немає API (errors.feature = api.access) або ключу не надано дозвіл
`429`	вичерпано квоту доби чи місяця або стелю 120 запитів на хвилину; дивіться заголовок Retry-After
`503`	API тимчасово вимкнено на платформі

Версії

Поля v1 не перейменовуються й не зникають. Нові поля можуть з'являтись — ігноруйте невідомі. Ламаюча зміна — це нова версія з новою адресою, а не правка v1.