1. Получите ключ
Тестовый ключ показывается один раз. Храните его в секретах backend.
REST · JSON · HTTPS
Документация ОКЗвонок API
Подключите проверку репутации номера по HTTPS. Для запросов нужен ключ в заголовке X-API-Key; тело и ответы передаются в JSON.
Быстрый старт
2. Отправьте запрос
Передайте номер и режим в JSON-теле POST-запроса.
3. Обработайте три статуса
Не объединяйте ok и unknown в одно бизнес-правило.
4. Добавьте retry
Повторяйте только сетевые ошибки и 5xx с exponential backoff.
bash
curl -X POST "https://api.okzvonok.ru/v1/unified-spam-check" \
-H "X-API-Key: okz_..." \
-H "Content-Type: application/json" \
-d '{"number":"+79991234567","mode":"offline"}'Авторизация
Передавайте ключ в заголовке X-API-Key. Не размещайте его в URL, браузерном bundle, мобильном приложении или публичном репозитории.
X-API-Key: okz_...
Форматы номера
Поддерживаются российские номера: +79991234567, 79991234567, 89991234567 и десять цифр без префикса. Результат нормализуется к коду страны 7.
Endpoints
POST
/v1/unified-spam-checkОдин номер: verdict, score, источники и история.POST
/v1/bulk-spam-checkДо 1000 номеров в одном запросе.GET
/v1/lookup?number=Оператор и регион по справочнику диапазонов.Модель результата
verdictspam, ok или unknown
scoreсуммарный вес сигналов 0–100
sourcesдетализация доступных источников
previously_spamистория снятых меток
operator / regionсправочная метаинформация
billed_asфактический режим списания
Коды ошибок
| Код | Значение | Действие |
|---|---|---|
| 400 | Некорректный номер | исправить формат |
| 401 | Ключ отсутствует или неизвестен | проверить секрет |
| 403 | Ключ отозван | запросить новый |
| 422 | Тело не соответствует схеме | исправить поля |
| 429 | Квота исчерпана | увеличить квоту или ждать |
| 502 | Проверка не выполнена | retry с backoff |
| 503 | Сервис не готов | retry и status page |
Квоты и списание
Offline и Online учитываются отдельно. Поле billed_as показывает фактический режим. При деградации Online и возврате офлайн-результата онлайн-квота не списывается.