ChatGetz API для разработчиков

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

1. Войдите и откройте Панель → API-ключи.
2. Создайте ключ с нужными правами и скопируйте его (он показывается только один раз).
3. Передавайте его в заголовке Authorization: Bearer cgk_…

curl https://www.chatgetz.uz/api/v1/account/balance \
  -H "Authorization: Bearer $CHATGETZ_API_KEY"

curl https://www.chatgetz.uz/api/v1/ai/generate \
  -H "Authorization: Bearer $CHATGETZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c6f5e-order-42" \
  -d '{
    "model": "deepseek/deepseek-v4-flash",
    "prompt": "Write a 60-word description for a cotton kids hoodie",
    "instructions": "Answer in Uzbek (Latin script)."
  }'

Аутентификация и права

Каждый запрос должен содержать личный API-ключ в заголовке Authorization: Bearer cgk_… (или X-API-Key). У каждого ключа свои права (scopes) и лимит запросов; ключ можно отозвать в любой момент.

Храните ключи на своём сервере или в настройках плагина, но никогда в публичном фронтенд-коде. ChatGetz хранит только SHA-256-хеш каждого ключа.

Лимиты и цены

• Global Pro: безлимитные запросы к API.
• Basic: 1,000 запроса в месяц (сброс 1-го числа по ташкентскому времени).
• Без тарифа API недоступен.
• У каждого ключа свой лимит (10–120 запросов в минуту). При превышении API отвечает 429 с заголовком Retry-After.
• Генерация текста AI списывается по открытому прайсу: сначала из месячного AI-лимита, затем с баланса ChatGetz.
• Передавайте заголовок Idempotency-Key в ИИ-запросах: повторный запрос с тем же ключом никогда не спишется дважды.

Эндпоинты

• get/api/v1/account/balanceТариф, баланс, включённый ИИ-лимит и квота APIaccount:read
• get/api/v1/modelsТекстовые модели и их доступность для вашего ключаai:generate
• post/api/v1/ai/generateГенерация текста; списывается с баланса (сначала из включённого лимита)ai:generate
• get/api/v1/market/listingsВаши объявления в ChatGetz Marketmarket:read
• post/api/v1/market/listingsСоздать объявление в Market (по умолчанию черновик)market:write
• post/api/v1/ingest/eventsПриём заказа или лида из плагина (вебхук)ingest:write
• get/api/v1/openapi.jsonСпецификация OpenAPI 3.1 этого API

Плагины отправляют новые заказы и лиды на POST /api/v1/ingest/events. Повторная отправка события с теми же source, type и externalId безопасна: оно сохраняется один раз.

curl https://www.chatgetz.uz/api/v1/ingest/events \
  -H "Authorization: Bearer $CHATGETZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order", "source": "woocommerce", "externalId": "1042",
    "customer": { "name": "Aziza", "phone": "+998901234567" },
    "total": { "amount": "249000", "currency": "UZS" },
    "items": [{ "name": "Hoodie", "quantity": 1, "price": "249000" }]
  }'

Ошибки

Ошибки возвращаются в JSON со стабильным машинно-читаемым кодом и сообщением на английском. Стройте интеграцию на коде.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly Basic API quota exhausted. ..."
  }
}

Плагины

Все плагины с открытым кодом (совместимы с GPL) и используют ваш API-ключ. Ключ хранится в настройках плагина, а не в коде.