#Соглашения API

Статус: Доступно. Общие правила, одинаковые для всех конечных точек серверного API.

Назначение: формат запросов и ответов, ошибки и полный каталог кодов, пагинация, идемпотентность, асинхронные операции, пределы частоты, версионирование и платные операции.

Примеры JSON ниже иллюстративны: имена необязательных полей уточнятся в спецификации OpenAPI 3.1.

#Содержание

1. Формат запросов и ответов
2. Ошибки
3. Каталог кодов ошибок
4. Пагинация
5. Идемпотентность
6. Асинхронные операции
7. Пределы частоты
8. Версионирование
9. Платные операции
10. Кошелёк и остановка обмена

#Формат запросов и ответов

#Заголовки ответа

#Заголовки запроса

#Ошибки

Все ошибки — application/problem+json по RFC 9457. Текст ошибки не содержит трассировок стека и сведений о базе данных.

#Поля

Элемент errors[]:

#Пример

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
X-Request-Id: req_EXAMPLE0003

{
  "type": "https://formula-cream.pro/developers/errors#validation_failed",
  "title": "Запрос не прошёл проверку",
  "status": 422,
  "code": "validation_failed",
  "detail": "Один или несколько параметров некорректны.",
  "request_id": "req_EXAMPLE0003",
  "errors": [
    { "field": "/limit", "code": "out_of_range", "message": "Должно быть от 1 до 100." }
  ]
}

#Как обрабатывать

#Каталог кодов ошибок

HTTP-статусы кодов зафиксированы. Описание каждого кода доступно по адресу из поля type: https://<домен ячейки>/developers/errors#<code>.

#Аутентификация и доступ

#Запрос и состояние ресурса

#Деньги и пределы

#Платформа

#Не ошибки: причины отсутствия ответа ИИ

Эти значения приходят в теле успешного ответа, а не как ошибка. Приём сообщения клиента прошёл успешно; ИИ-продажник не ответил по названной причине. Состояние ответа ИИ передаётся полем ai_reply в ответе на сообщение клиента и в событии message.created; подробно — Серверный API диалогов.

ai_reply — объект {status, reason?}:

Не воспринимайте эти значения как сбой: сообщение принято и сохранено. В клиентском Chat API виджета тот же случай daily_limit сообщается полем queued: true (клиентский Chat API).

#Пагинация

Списки возвращаются курсором («keyset»), а не номерами страниц.

GET /api/public/v1/leads?limit=50&cursor=eyJ2IjoxLC4uLn0 HTTP/1.1

Ответ:

{
  "data": [
    { "id": "lead_EXAMPLE01", "status": "new", "updated_at": "2026-10-11T08:15:30Z" }
  ],
  "next_cursor": "eyJ2IjoxLC4uLn0"
}

Когда next_cursor равен null, список закончился.

#Свойства курсора

#Что происходит при изменениях во время обхода

• Добавленные записи попадут в обход, если окажутся «после» текущей позиции.
• Изменённая запись получает новый updated_at и поэтому может появиться повторно позже. Обрабатывайте записи как «upsert по id», а не «вставить».
• Удалённые записи по умолчанию не возвращаются. С параметром include_deleted=true вместо них приходят «надгробия» — объекты {"id": "…", "deleted_at": "2026-10-11T08:15:30Z"}, чтобы вы могли убрать запись у себя. Надгробия хранятся 30 суток: синхронизируйтесь не реже.
• Записи не пропускаются из-за изменений в соседних строках.

Для синхронизации в реальном времени используйте вебхуки, а периодический обход оставьте для сверки.

#Идемпотентность

Заголовок Idempotency-Key защищает от дублей при повторах после сетевых сбоев и тайм-аутов.

Поведение при повторе с тем же ключом:

Рекомендации:

• Генерируйте ключ до первой отправки и сохраняйте его вместе с задачей в своей очереди, чтобы повтор использовал тот же ключ.
• Для 429 и 5xx повторяйте запрос с тем же ключом.
• Не используйте один ключ для разных операций.

Платформа не хранит ПДн в записях идемпотентности: повтор перерисовывает ответ из актуальных данных ресурса.

#Асинхронные операции

Долгие операции (ответ ИИ-продажника, генерация статьи, ход стратега) не держат соединение. Они подчиняются единой схеме: запрос возвращает 202 Accepted с объектом operation; результат можно подождать, опросить или получить событием.

POST …  (Idempotency-Key)            →  202 Accepted  +  {"operation": {…}}
                                            │
         ┌──────────────────────────────────┼──────────────────────────────┐
         ▼                                  ▼                              ▼
   ?wait=N (до 20 с):               опрос                          событие вебхука
   ждём то же задание               GET /operations/{id}           operation.completed
                                                                    (и событие модуля)

#Конверт operation

Один и тот же объект возвращается из создающего запроса, из GET /operations/{id} и в событии operation.completed.

Пример 202:

{
  "operation": {
    "id": "op_EXAMPLE01",
    "type": "conversation.ai_reply",
    "status": "queued",
    "created_at": "2026-10-11T08:15:30Z",
    "resource": { "type": "message", "id": "msg_EXAMPLE01" }
  }
}

Виды операций:

Оценка лида (POST /leads/{id}/score) выполняется синхронно и в конверт не оборачивается.

#Способы получить результат

#GET /operations/{id}

Возвращает операцию вашей интеграции. Отдельной области не требует: чтобы прочитать результат, нужны области самого ресурса (например, conversations:read). Операцию другой интеграции или другого арендатора вернёт как 404 not_found.

Ответ 200:

{
  "operation": {
    "id": "op_EXAMPLE01",
    "type": "conversation.ai_reply",
    "status": "succeeded",
    "created_at": "2026-10-11T08:15:30Z",
    "completed_at": "2026-10-11T08:15:41Z",
    "resource": { "type": "message", "id": "msg_EXAMPLE01" },
    "usage": { "cost": { "amount": "0.42", "currency": "RUB" }, "model": "model-EXAMPLE" }
  }
}

Свойства:

• Задание восстанавливается после сбоя воркера; резерв платных средств возвращается, если операция не выполнена.
• Повторный запрос с тем же Idempotency-Key возвращает ту же операцию.
• Результат платной операции содержит usage (см. ниже).

#Пределы частоты

Пределы считаются скользящим окном на ключ и на арендатора одновременно.

Значения стартовые и могут измениться; пределы по тарифам не зафиксированы. Фактические значения для вашего ключа видны в GET /me (limits). Приём событий и офлайн-конверсий (analytics:write) относится к записи: 120 запросов в минуту, в пакете не более 100 событий.

#Заголовки

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 23
Retry-After: 23

#Отказ хранилища пределов

• Для записи и платных операций режим «закрытый»: при недоступности хранилища пределов возвращается 503 service_unavailable (с Retry-After) — платформа не допустит неконтролируемых расходов.
• Для чтения действует мягкий предел в памяти процесса, и запросы продолжают обслуживаться.

#Рекомендации

• Читайте RateLimit-Remaining и замедляйтесь заранее.
• Повторяйте 429 после Retry-After с «дрожанием» (jitter), а не лавиной.
• Для массовой синхронизации используйте курсорный обход и вебхуки вместо частого опроса.

#Версионирование

• Версия входит в адрес: /api/public/v1.
• Внутри v1 вносятся только добавляющие изменения: новые конечные точки, новые необязательные параметры, новые поля ответа, новые значения перечислений там, где это оговорено. Клиент должен игнорировать неизвестные поля.
• Несовместимое изменение выходит только в новой версии (v2) и никогда не подменяет v1.
• Устаревание объявляется заранее: заголовки Deprecation и Sunset в ответах, запись в журнале изменений — не менее чем за 90 суток до отключения.

#Платные операции

Платные операции списывают деньги с кошелька арендатора: ответ ИИ-продажника, оценка лида, генерация статьи, ход стратега. Они выделены в отдельные области (Аутентификация).

#Защита от неконтролируемых расходов

Когда состояние кошелька неизвестно (источник баланса не ответил), платные операции закрыты: 503 upstream_unavailable с Retry-After. Бесплатное чтение при этом работает и несёт заголовок Sapport-Wallet-State: unknown.

Значения пределов настраиваются в кабинете арендатора; действующие значения параллелизма и дневной траты видны в GET /me (limits.paid_concurrency, wallet.daily_spend).

#Ответы

#Стоимость в ответе

Каждый успешный ответ платной операции, а также конверт operation платной операции содержит поле usage:

Пример (иллюстративный) — оценка лида, синхронная платная операция:

{
  "lead_id": "lead_EXAMPLE01",
  "score": 72,
  "usage": {
    "cost": { "amount": "0.12", "currency": "RUB" },
    "model": "model-EXAMPLE"
  }
}

Тестовые ключи не списывают деньги (Аутентификация).

#Сводная шпаргалка

#Кошелёк и остановка обмена

Если баланс кошелька арендатора ниже нуля или кошелёк заблокирован, обмен данными останавливается целиком: каждый маршрут, кроме GET /me и GET /wallet, отвечает 402 wallet_suspended ещё до проверки областей и до чтения тела запроса, а исходящие вебхуки не отправляются, а откладываются. Ответ несёт topup_url (где пополнить) и balance (остаток на момент отказа). Состояние всегда видно в GET /wallet и в блоке wallet ответа GET /me. Полное описание, состояния и примеры — в разделе Кошелёк и остановка обмена.