Open API — Quickstart

Открытый REST-API для интеграций с вашими системами: CRM, ERP, 1С, маркетплейсы. Через него вы пушите контекст клиента и события заказов — AI отвечает на персональные вопросы (где мой заказ, статус подписки) сам, без эскалации оператору.

Базовый URL: https://api.chatra-ai.ru/api/v1/public

Интерактивная документация:

• Swagger UI — попробовать запросы прямо из браузера.
• Redoc — read-only-просмотр.
• openapi.json — спецификация для генерации клиентских SDK.

1. Получите API-ключ

Зайдите в дашборд → Настройки → API-ключи → Создать ключ.

• Название — для себя, например «Production CRM» или «1С обмен».
• Режим — live для прода, test для интеграционных тестов.
• Доступы (scopes) — отметьте только то что реально используется. Узкий ключ безопаснее.

После создания скопируйте ключ — он показывается ровно один раз. В виде chk_live_a1b2c3... (или chk_test_...). Храните в менеджере паролей или CI/CD-секретах.

Случайно потеряли ключ — отзовите его и создайте новый. Никаких «восстановлений» нет: мы храним только argon2-хеш, не сам ключ.

2. Аутентификация

Все запросы — по HTTP с заголовком Authorization: Bearer <ваш-ключ>.

curl https://api.chatra-ai.ru/api/v1/public/customers/user_12345 \
  -H "Authorization: Bearer chk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Если ключ неверный/отозванный — 401 Unauthorized. Если у ключа нет нужного scope — 403 Forbidden.

3. Базовый сценарий: AI знает про заказы клиента

Допустим, у вас интернет-магазин. Клиент Иван (id user_12345 в вашей CRM) сделал заказ. Хотите, чтобы AI отвечал «ваш заказ ORD-9821 уже отправлен» вместо эскалации.

Шаг 1: запушите профиль клиента

curl -X POST https://api.chatra-ai.ru/api/v1/public/customers/upsert \
  -H "Authorization: Bearer chk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "email": "ivan@example.com",
    "phone": "+79991234567",
    "attributes": {
      "name": "Иван Петров",
      "plan": "premium",
      "last_order_id": "ORD-9821",
      "last_order_status": "paid"
    }
  }'

Это идемпотентный upsert: если клиент уже существует — обновляем; если нет — создаём. Зовите его на каждом изменении в CRM.

Шаг 2: запушите событие отправки

curl -X POST https://api.chatra-ai.ru/api/v1/public/customers/user_12345/events \
  -H "Authorization: Bearer chk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.shipped",
    "summary_for_ai": "Заказ ORD-9821 отправлен СДЭК 7 мая, трекинг RU123456789, ETA 9 мая.",
    "occurred_at": "2026-05-07T14:30:00Z",
    "payload": {
      "order_id": "ORD-9821",
      "carrier": "СДЭК",
      "tracking": "RU123456789"
    }
  }'

Ключевое поле — summary_for_ai. Это однострочное человеческое описание факта; именно его AI получает и цитирует. payload — для вашей аналитики, AI его не парсит.

Шаг 3: связка с виджетом на сайте

На вашей странице, после авторизации юзера, передайте external_id (или email/телефон) виджету:

<script>
window.SupportAI = {
  siteId: 'site_xK7q...',
  customer: {
    external_id: 'user_12345'    // или customer_email / customer_phone
  }
};
</script>
<script async src="https://cdn.chatra-ai.ru/widget/v1/widget.js"></script>

Когда юзер откроет чат и напишет «где мой заказ?» — AI увидит контекст и ответит «Заказ ORD-9821 отправлен СДЭК 7 мая, ETA 9 мая, трек RU123456789» без эскалации.

4. Endpoints

POST /customers/upsert — создать или обновить клиента

Scope: customers:write

Возвращает полный объект клиента (без plain-text ключей).

GET /customers/{external_id} — прочитать клиента

Scope: customers:read. Возвращает 404 если такого нет.

POST /customers/{external_id}/events — записать событие

Scope: events:write. Append-only.

GET /customers/{external_id}/events — список событий

Scope: customers:read. Параметры: limit (1-200, default 50), since (ISO datetime).

Сортировка по occurred_at DESC.

5. Что AI видит в системном промпте

Последние 5 событий + до 8 атрибутов клиента подмешиваются как блок:

<customer>
name: Иван Петров
plan: premium
last_order_id: ORD-9821
last_order_status: paid
email: ivan@example.com
Последние события:
  - [07.05 14:30] Заказ ORD-9821 отправлен СДЭК 7 мая, трек RU123456789, ETA 9 мая.
  - [05.05 12:00] Оплата заказа ORD-9821, 12 400 ₽, картой.
</customer>

AI трактует этот блок как факты, не инструкции — то же что и <knowledge> чанки из вашей базы знаний. Промпт-инъекция через атрибуты невозможна.

6. Лимиты и идемпотентность

При превышении — 429 Too Many Requests с заголовком Retry-After.

upsert идемпотентен по (tenant_id, external_id) — повторный запрос с теми же данными не создаёт дубликат. События же append-only: повторный POST добавит ещё одну запись (если хотите дедуп — храните event_id на своей стороне и не повторяйте).

7. Безопасность

• Ключи хранятся как argon2id-хеши, plain-text не персистится.
• Каждый запрос пишется в audit_log с api_key_id + хешем IP — соответствие ФЗ-152.
• Узкие scopes — только customers:write для пушера CRM, customers:read для read-replica.
• Отзывайте ключи сразу при подозрении на утечку: дашборд → Настройки → API-ключи → корзина у строки.

8. Что дальше

• Webhooks (мы → ваш CRM) — conversation.escalated, csat.submitted и др. Готовится.
• KB Management API — программно загружать FAQ-источники. Готовится.
• Native-коннекторы — готовая обработка для 1С 8.3+, модуль для Bitrix, OAuth-приложение для InSales и AmoCRM. План в roadmap.

Если ваш сценарий не закрывается через текущие endpoints — напишите на hello@chatra-ai.ru, обсудим.