Довідник API

Основні угоди роботи з API Configo — версіонування, автентифікація, формат запитів та обробка помилок.

Базовий URL

Усі запити до API надсилаються на:

https://configo.org/api

Версіонування API

API Configo версіонується через шлях URL. Поточна і єдина доступна версія — v1:

https://configo.org/api/v1/...

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

API Configo використовує OAuth 2.0. Автентифікуйте свої запити, включаючи токен доступу в заголовок Authorization як Bearer-токен:

Authorization: Bearer <access_token>

Запити без валідного токена, або з простроченим чи відкликаним токеном, отримають відповідь 401 Unauthorized.

Області доступу (scopes)

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

Область	Дає доступ до
`identify`	Профілю автентифікованого користувача, підключених акаунтів, рефералів і локалі
`billing`	Підписки, історії платежів та інформації про тариф
`projects`	Деталей проєкту та налаштувань рівня проєкту (ролі, учасники, статуси)
`orders`	Замовлень усередині проєкту
`contacts`	Контактів усередині проєкту, включно з полями контактів і журналами активності
`materials`	Матеріалів усередині проєкту
`configurators`	Калькуляторів усередині проєкту та публічних калькуляторів у вітрині
`products`	Продуктів усередині проєкту
`reports`	Аналітичних і звітних даних усередині проєкту
`files`	Завантаження, отримання та видалення файлів

Більшість ендпоінтів у межах проєкту (замовлення, контакти, матеріали, калькулятори, продукти, звіти) вимагають одночасно область projects і специфічну область ресурсу, оскільки доступ оцінюється в контексті проєкту.

Публічні клієнти (PKCE)

Якщо ваша інтеграція не має власного бекенду — CLI-утиліта, розширення браузера, односторінковий застосунок — зареєструйте її як публічний клієнт, а не як звичайний (конфіденційний). У публічного клієнта немає client_secret: секрет, зашитий у кожну інсталяцію нативного чи браузерного застосунку, насправді не є секретом, тому він не видається взагалі. Натомість обмін коду авторизації захищено лише PKCE (code_challenge / code_verifier, метод S256).

Для публічного клієнта PKCE обов'язковий, а не опціональний: запит до /oauth/authorize має містити code_challenge (з code_challenge_method=S256), а обмін токена на /api/auth/token — відповідний code_verifier. Відсутність будь-якого з них відхиляється з 400 invalid_request. Параметр client_secret у запиті токена не передається взагалі — його не існує.

Публічний клієнт створюється на сторінці OAuth-застосунків увімкненням опції Публічний клієнт під час створення застосунку — покроково це описано в розділі OAuth-застосунки.

Довірені застосунки

Деякі ендпоінти — такі як керування сесіями, зареєстрованими застосунками, тікетами підтримки та видаленням акаунта — обмежені довіреними застосунками, а не конкретною областю доступу. Довірений застосунок — це застосунок, якому Configo явно надала розширений доступ, окремо від стандартного OAuth-флоу згоди. Якщо вашій інтеграції потрібен доступ до цих ендпоінтів, зв'яжіться з підтримкою Configo.

Формат запиту

User-Agent

Усі запити повинні включати заголовок User-Agent, що ідентифікує клієнтську бібліотеку та її версію:

User-Agent: ConfigoClient (library, version)

Content-Type

Запити, що включають тіло, повинні вказувати валідний заголовок Content-Type:

application/json
application/x-www-form-urlencoded
multipart/form-data

HTTP-методи

API використовує стандартні HTTP-методи для позначення дії, що виконується:

Метод	Дія
`GET`	Отримати один або кілька ресурсів
`POST`	Створити новий ресурс
`PUT`	Повністю замінити ресурс
`PATCH`	Частково оновити ресурс
`DELETE`	Видалити ресурс

Коди відповідей

Код	Значення
`200 OK`	Запит успішно виконано.
`201 CREATED`	Ресурс успішно створено.
`204 NO CONTENT`	Запит успішно виконано, але без вмісту у відповіді.
`304 NOT MODIFIED`	Ресурс не було змінено; дію не виконано.
`400 BAD REQUEST`	Запит неправильно сформовано або не може бути зрозумілим.
`401 UNAUTHORIZED`	Заголовок `Authorization` відсутній або невалідний.
`403 FORBIDDEN`	У токена немає прав на доступ до цього ресурсу.
`404 NOT FOUND`	Запитаний ресурс не існує.
`405 METHOD NOT ALLOWED`	HTTP-метод не підтримується для цього ендпоінту.
`409 CONFLICT`	Ресурс вже існує.
`429 TOO MANY REQUESTS`	Вас обмежено за частотою запитів.
`502 GATEWAY UNAVAILABLE`	Не знайдено доступного шлюзу для обробки запиту. Зачекайте й повторіть.
`5xx SERVER ERROR`	Помилка на боці Configo. Трапляється рідко.

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

Ендпоінти під /widget використовують окрему схему автентифікації, призначену для вбудовування Configo на публічному сайті, а не для інтеграцій на основі OAuth. Ці запити автентифікуються токеном віджета, прив'язаним до конкретного проєкту, що передається через заголовок x-widget-token:

x-widget-token: <jwt>