CareWay API v1

Встройте ИИ-диагностику CareWay в свой продукт

Чаты, поток событий, оценка ответа и состояние тарифа доступны через один стабильный серверный API. Начать можно с готового SDK для Python или Node.js.

Получить API-ключ Быстрый старт OpenAPI YAML

API-ключ — серверный секрет. Не размещайте его в браузерном JavaScript или мобильном приложении.

POST /api/v1/chats/{id}/messages

{
	"text": "На холодную давление топлива ниже нормы",
	"idempotencyKey": "case-1042-turn-1"
}

Быстрый старт

Два SDK без сторонних зависимостей

Выберите язык, установите версионированный пакет и храните ключ в переменной окружения.

Python3.9+

Синхронные методы и генератор событий SSE на стандартной библиотеке.

pip install https://carewayrussia.ru/assets/sdk/careway-python-v1.zip

from careway import CareWay

client = CareWay("cw_v1_...")
chat = client.create_chat("Диагностика")
result = client.send_message(
		chat["id"],
		"Ошибка P0087, что проверить сначала?"
)
print(result["assistantMessage"]["content"])

Скачать Python SDK

Node.js18+

Async API, типы TypeScript и async generator для Server-Sent Events; используется встроенный fetch.

npm install https://carewayrussia.ru/assets/sdk/careway-node-v1.tgz

import { CareWay } from "@careway/api";

const client = new CareWay({
	apiKey: process.env.CAREWAY_API_KEY
});
const chat = await client.createChat();
const result = await client.sendMessage(chat.id, {
	text: "Ошибка P0087, что проверить сначала?"
});
console.log(result.assistantMessage.content);

Скачать Node.js SDK

Авторизация

API-ключ в Bearer-заголовке

Создайте ключ в личном кабинете в разделе «API-ключи». Полный секрет показывается один раз. В базе CareWay хранится только его необратимый хэш.

curl https://api.carewayrussia.ru/api/v1/subscription \
	-H "Authorization: Bearer $CAREWAY_API_KEY"

Также поддерживается заголовок X-API-Key. Для серверных SDK рекомендуется Authorization: Bearer.

Контракт

Методы API v1

GET/api/v1/subscription

Тариф, дата окончания, остатки лимитов и предупреждение.

GET/api/v1/chats

Список диалогов текущего аккаунта.

POST/api/v1/chats

Создать диалог. Тело: {"title":"Диагностика"}.

GET/api/v1/chats/{chatId}

Диалог, сообщения и актуальное состояние тарифа.

DELETE/api/v1/chats/{chatId}

Удалить принадлежащий ключу диалог.

POST/api/v1/chats/{chatId}/messages

Отправить сообщение и получить финальный JSON-ответ.

POST/api/v1/chats/{chatId}/messages/stream

Отправить сообщение и получать события по SSE.

POST/api/v1/chats/{chatId}/messages/{messageId}/feedback

Сохранить или заменить оценку ответа.

Идемпотентная отправка

Поля text и idempotencyKey обязательны. Передавайте уникальный ключ длиной до 128 символов для каждого сообщения. Повтор запроса с тем же ключом в том же диалоге вернёт уже созданный результат и не спишет лимит повторно.

{
	"text": "После замены фильтра ошибка осталась",
	"idempotencyKey": "repair-1042-turn-2"
}

Server-Sent Events

Поток событий

Ответ имеет тип text/event-stream. Текст ответа приходит в событии completed; до него интеграция получает безопасные продуктовые статусы. Ошибка внутри потока приходит событием error, после которого всегда следует done.

СобытиеНазначение

subscriptionТариф и предупреждение о скором окончании.

progressЭтап: accepted, processing или finalizing.

sourcesПубличные источники, если они есть в ответе.

heartbeatПоддерживает соединение во время долгого разбора.

completedФинальный ответ, сообщения и состояние тарифа.

errorБезопасная публичная ошибка.

doneПоток завершён.

for event in client.stream_message(
		chat["id"], "Покажи следующий безопасный тест"
):
		if event["event"] == "progress":
			print(event["data"]["message"])
		if event["event"] == "completed":
			print(event["data"]["assistantMessage"]["content"])

Обратная связь

Кнопки «верно» и «неверно»

Для ответа ассистента передайте correct или incorrect. Повторный вызов заменяет предыдущую оценку, поэтому кнопки можно переключать.

{
	"rating": "incorrect",
	"actualCause": "Причиной оказался разъём датчика"
}

Поле actualCause необязательное и полезно, когда партнёр уже знает фактическую причину.

Тарификация

Тот же тариф, что в кабинете CareWay

API использует общие чаты, лимиты и подписку аккаунта. Покупка и продление остаются в личном кабинете; отдельного баланса для API нет.

{
	"plan": "ai_master",
	"status": "active",
	"expiresAt": "2026-08-02T12:00:00Z",
	"isExpiringSoon": true,
	"daysRemaining": 7,
	"warning": "Тариф закончится через 7 дн. Продлите его в личном кабинете.",
	"usage": { "liteMonthly": 21, "deepMonthly": 4 },
	"limits": { "liteMonthly": 120, "deepMonthly": 45 }
}

isExpiringSoon становится true за 7 дней до окончания. В streaming-методе те же данные приходят первым событием subscription.

Ошибки

Стабильные публичные коды

HTTPКод и значение

400invalid_request — неверные параметры.

401invalid_api_key — ключ неверен или отозван.

402subscription_required — нужен активный тариф.

403access_restricted — доступ ограничен.

404not_found — диалог или сообщение не найдено.

429rate_limit_exceeded — лимит тарифа исчерпан.

503service_unavailable — временная недоступность.

Продуктовый слой без внутренней реализации

API возвращает только сообщения, публичные источники, тариф, лимиты и нейтральные этапы обработки. В контракт не входят используемые модели, поставщики технологий, системные инструкции, промпты, внутренние агенты, трассировки или служебные ошибки.

Версия находится в URL. Несовместимые изменения будут выпускаться только в новой версии; v1 сохраняет обратную совместимость.

Готово к интеграции

Создайте ключ и отправьте первый запрос

Чаты из API появятся в том же аккаунте CareWay и останутся видимыми в CRM.

Перейти к API-ключам