Документация API

Интегрируйте функционал проверки телефонных номеров в ваши приложения

Общая информация

Наше API позволяет интегрировать функционал проверки телефонных номеров и работы с отзывами в ваши приложения.
Базовый URL API whocall.su/api.php
Формат данных JSON
Кодировка UTF-8
Аутентификация API Key + App Info (в заголовках)

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

Все запросы к API (кроме OPTIONS) требуют аутентификации через заголовки HTTP:

Заголовки запроса

Заголовок Описание
X-API-Key Ваш секретный API ключ
X-App-Info Идентификатор вашего приложения

Пример на PHP

$apiKey = 'ВАШ_API_КЛЮЧ';
$appInfo = 'ВАШЕ_ПРИЛОЖЕНИЕ';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 
    'https://whocall.su/api.php?action=phone_info&phone=79991234567');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'X-App-Info: ' . $appInfo
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

Коды ответов

Код Описание
200 Успешный запрос
400 Неверные параметры запроса
401 Ошибка аутентификации
404 Ресурс не найден
405 Метод не разрешен
500 Внутренняя ошибка сервера

Методы API

Получить информацию о номере

GET

Возвращает полную информацию о номере телефона, включая оператора, регион, статистику отзывов и сами отзывы.

URL: /api.php?action=phone_info&phone=НОМЕР_ТЕЛЕФОНА

Параметры запроса:

phone Номер телефона в формате 79991234567

Пример ответа:

{
  "success": true,
  "data": {
    "phone": "79991234567",
    "operator": "ПАО «МегаФон»",
    "region": "г. Москва",
    "trust_score": 85,
    "statistics": {
      "total_reviews": 15,
      "positive_reviews": 12,
      "neutral_reviews": 2,
      "spam_reviews": 1
    },
    "reviews": [
      {
        "author_name": "Анна",
        "review_type": "positive",
        "comment": "Вежливый сотрудник",
        "rating": 5,
        "created_at": "2025-09-20 14:30:00"
      }
    ]
  }
}

Поиск оператора

GET

Определяет оператора и регион для указанного номера телефона.

URL: /api.php?action=search_operator&phone=НОМЕР_ТЕЛЕФОНА

Параметры запроса:

phone Номер телефона в формате 79991234567

Пример ответа:

{
  "success": true,
  "data": {
    "phone": "79991234567",
    "operator": "ПАО «МегаФон»",
    "region": "г. Москва"
  }
}

Последние отзывы

GET

Возвращает список последних одобренных отзывов с пагинацией.

URL: /api.php?action=recent_reviews&limit=10&offset=0

Параметры запроса:

limit Количество отзывов (макс. 50, по умолчанию 10)
offset Смещение для постраничного вывода

Пример ответа:

{
  "success": true,
  "data": {
    "reviews": [
      {
        "author_name": "Иван",
        "review_type": "spam",
        "comment": "Навязывали кредит",
        "rating": 0,
        "created_at": "2025-09-25 10:15:00",
        "phone": "79991234567"
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0
    }
  }
}

Добавить отзыв

POST

Добавляет новый отзыв о телефонном номере.

URL: /api.php?action=add_review

Тело запроса (JSON):

{
  "phone": "79991234567",
  "author_name": "Сергей",
  "review_type": "spam",
  "comment": "Предлагали ненужную услугу"
}

Типы отзывов (review_type):

  • positive - Положительный
  • neutral - Нейтральный
  • spam - Спам
  • scam - Мошенничество
  • telemarketing - Телемаркетинг
  • и другие...

Пример ответа:

{
  "success": true,
  "message": "Review added successfully and awaiting moderation"
}

Статистика API ключа

GET

Возвращает статистику использования вашего API ключа.

URL: /api.php?action=api_stats

Параметры запроса:

Не требует дополнительных параметров

Пример ответа:

{
  "success": true,
  "data": {
    "app_info": "my_app",
    "total_requests": 1250,
    "daily_requests": 47,
    "monthly_requests": 892,
    "last_request_date": "2025-09-26"
  }
}

Важные примечания

Внимание: При использовании API соблюдайте следующие правила
  • Номера телефонов должны передаваться в международном формате без знака "+" (например: 79991234567)
  • Минимальная длина комментария при добавлении отзыва - 10 символов
  • Все отзывы проходят модерацию перед публикацией
  • Ответы кешируются на 5 минут для повышения производительности
  • Следите за лимитами запросов в статистике вашего API ключа
  • При ошибке аутентификации (401) проверьте правильность API ключа и идентификатора приложения

Получить API ключ

Для получения API ключа и идентификатора приложения, пожалуйста, свяжитесь с нами:

Email: api@whocall.su
Время ответа: 1-2 рабочих дня
При обращении укажите цель использования API и предполагаемый объем запросов.