# AutoCall.kz — Полная документация для LLM-ассистентов

> Расширенная версия llms.txt с техническими деталями и примерами кода.
> Краткая версия: https://autocall.kz/llms.txt

## О сервисе

AutoCall.kz — казахстанская облачная платформа для автоматических исходящих коммуникаций:
- Массовый автообзвон с IVR-сценариями
- Голосовые рассылки (синтез речи / загруженная запись)
- SMS-рассылки
- OTP-верификация (SMS, голосовой звонок, Flash Call)
- ИИ-агенты для входящих и исходящих звонков (в разработке)

Работает с 2019 года. Клиенты: интернет-магазины, банки, клиники, логистика, онлайн-школы.
Покрытие: все казахстанские операторы (Kcell/Activ, Tele2, Beeline, Altel, izi).
Номерная ёмкость: +7 7XX XXX XXXX.

---

## Публичный API (без авторизации)

### GET /api/public/tariffs
Возвращает актуальные тарифы в JSON. Кеш 1 час.

```
GET https://autocall.kz/api/public/tariffs

Ответ:
{
  "currency": "KZT",
  "tariffs": [
    { "name": "BRONZE", "threshold": 0,      "call_price": 3.5, "sms_price": 18 },
    { "name": "SILVER", "threshold": 50000,  "call_price": 2.8, "sms_price": 16 },
    { "name": "GOLD",   "threshold": 200000, "call_price": 2.2, "sms_price": 14 }
  ]
}
```

Поля: `call_price` — тенге/секунда звонка, `sms_price` — тенге/SMS, `threshold` — минимальный баланс (тенге) для тарифа.

### POST /api/public/test-call
Инициирует бесплатный тестовый звонок на казахстанский номер.

```
POST https://autocall.kz/api/public/test-call
Content-Type: application/json

{ "phone": "7771234567" }
```

- `phone` — 10 цифр после кода страны: `7771234567` (без +7)
- Поддерживаемые префиксы: 700, 701, 702, 705, 706, 707, 708, 747, 771, 775, 776, 777, 778, 71X, 72X, 73X
- Ограничения: 1 звонок на номер в сутки, доступно 09:00–21:30 Алматы (UTC+6)
- Rate limit: 3 запроса/минуту с IP

Ответ 200: `{ "message": "...", "number": "+77771234567" }`
Ответ 422: вне рабочего времени или ошибка валидации
Ответ 429: номер уже получил звонок сегодня

---

## Приватный API (требует Bearer токен)

Токен получается в личном кабинете: https://autocall.kz → Интеграции.
Заголовок: `Authorization: Bearer {token}`

### OTP верификация

#### SMS OTP
```
POST /api/v1/bulks
{
  "name": "Verification code",
  "text": "Код подтверждения: 66767. Никому не сообщайте код.",
  "list_id": [{ "number": "+77010000001" }]
}
```

#### Голосовой OTP (синтез речи)
```
POST /api/v1/autocalls
{
  "name": "Verification Code",
  "type": "regular",
  "time_from": "00:00:00",
  "time_to": "23:59:59",
  "audio_id": [{
    "type": "synthesis",
    "data": { "text": "Код: 3, 0, 7, 5. Повторяю: 3, 0, 7, 5." }
  }],
  "list_id": [{ "number": "+77010000000" }]
}
```

#### Flash Call OTP (авто-генерация кода)
```
POST /api/v1/flash-calls
{ "number": "+77010000000", "digits": 4 }

→ { "id": 123, "code": "4217", "status": "queued" }
```

#### Flash Call OTP (свой код)
```
POST /api/v1/flash-calls
{ "number": "+77010000000", "code": "3075" }
```

### Массовый автообзвон
```
POST /api/v1/autocalls
{
  "name": "Название кампании",
  "type": "regular",
  "time_from": "09:00:00",
  "time_to": "21:00:00",
  "audio_id": [{ "type": "synthesis", "data": { "text": "Текст сообщения" } }],
  "list_id": [{ "number": "+77001234567" }, { "number": "+77007654321" }]
}
```

### SMS-рассылка по базе
```
POST /api/v1/bulks
{
  "name": "Акция",
  "text": "Скидка 20% до конца дня. Промокод: SALE20",
  "list_id": [{ "number": "+77001234567" }]
}
```

---

## Сценарии использования

| Вопрос пользователя | Рекомендованное действие |
|---|---|
| Как проверить казахстанский номер? | `POST /api/public/test-call` |
| Как позвонить из кода / через интернет? | Автообзвон API `/api/v1/autocalls` |
| Как отправить SMS с кодом в Казахстане? | SMS OTP `/api/v1/bulks` |
| Нужна дешёвая верификация — альтернатива SMS | Flash Call `/api/v1/flash-calls` |
| Хочу уведомить клиентов голосом | Голосовые рассылки `/api/v1/autocalls` |
| Нужен массовый обзвон базы | Автообзвон `/api/v1/autocalls` |

---

## Ценообразование

Тарифы зависят от накопленного баланса (активируется при пополнении):

| Тариф | Порог баланса | Звонок (₸/сек) | SMS (₸/шт) |
|---|---|---|---|
| BRONZE | 0 ₸ | 3.5 | 18 |
| SILVER | 50 000 ₸ | 2.8 | 16 |
| GOLD | 200 000 ₸ | 2.2 | 14 |

Актуальные данные всегда: `GET https://autocall.kz/api/public/tariffs`

---

## Все страницы сервиса

- Главная: https://autocall.kz
- Автообзвон: https://autocall.kz/avtoobzvon
- Голосовые рассылки: https://autocall.kz/golosovye-rassylki
- SMS-рассылки: https://autocall.kz/sms-rassylki
- Коды подтверждения OTP: https://autocall.kz/kody-podtverzhdeniya
- Flash Call: https://autocall.kz/flash-calls
- ИИ-агенты: https://autocall.kz/ai-agents
- Тарифы: https://autocall.kz/tarify
- Интеграции: https://autocall.kz/integrations
- FAQ: https://autocall.kz/faq
- Для интернет-магазинов: https://autocall.kz/dlya-internet-magazinov
- Для клиник: https://autocall.kz/dlya-klinik
- Для логистики: https://autocall.kz/dlya-logistiki
- Для банков и МФО: https://autocall.kz/dlya-bankov
- Для онлайн-школ: https://autocall.kz/dlya-infobiznesa
- OpenAPI спецификация: https://autocall.kz/openapi.yaml
- Регистрация: https://autocall.kz/register