Справочник 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>