Читать 7

API-метод получения статистики SMS по базе


Описание

В статье описан API-метод получения статистики SMS по базе.

Запрос

URL: 

https://api.calltouch.ru/lead-service/v1/api/sms-to-clients/result

Метод: POST

HTTP-заголовки: 

Заголовок    Описание   
Content-Type: application/json  Тело запросов/ответов будет в формате JSON.
Access-Token: <token> Авторизация через стандартный API-токен Calltouch
SiteId: <site_id> Идентификатор проекта в Calltouch, по которому необходимо получить результаты 

Пример запроса

{
    "dateFrom": "01-04-2024 09:00:00",
    "dateTo": "15-04-2024 15:35:21",
    "phoneNumbers": ["89209383654","+7 920 938 35 21", "79952125854","(936) 969-65-21"],
    "pageOfResult": 2
}

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

Параметр    Формат    Обязателен  Описание    Валидация   
dateFrom  string  Да  Начальная дата и время периода (включительно), в котором отправлялись SMS.

Валидные значения:

  • тип — string;
  • формат: любой формат с разделителем "-" или ".", см. документ.
    Важно: разделитель между датой и временем пробел;
  • не может быть больше текущего дня;
  • не может быть больше dateTo.
dateTo  string Да  Конечная дата и время периода (включительно), в котором отправлялись SMS. 

Валидные значения:

  • тип — string;
  • формат:
  • любой формат с разделителем "-" или ".", см. документ.
    Важно: разделитель между датой и временем пробел;
  • не может быть больше текущего дня;
  • не может быть меньше dateFrom.
 
phoneNumbers  массив string'ов  Нет  Фильтр номеров телефонов, по которым необходимо получить детализацию SMS. Не более 10000 номеров. 

Валидные значения:

  • ['89209383654','+7 920 938 35 21', '79952125854','(936) 969-65-21'];
  • каждый элемент — string;
  • номера доступно передавать по любой маске, главное — наличие кода города/оператора;
  • в массиве не более 10000 элементов.
pageOfResult  integer  Нет  Пагинация результатов. Если в ответе будет более 10000 смс, то результат будет разбит на несколько страниц. Чтобы получить доступ к следующим страницам, передайте номер страницы в запросе. Например, для получения смс с 10001 по 20000 передайте page=2.       Валидные значения:
  • каждый элемент — integer;
  • валидные значения — больше 1 и не больше максимального количества смс в запросе.

Ответ

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

{
    "meta": [],
    "data": {
        "totalCountSms": 25352,
        "pageOfResult": 2,
        "smsDetails":[
            {
                "phoneNumber": "79209383654",
                "dateSent": "01-04-2024 15:05:32",
                "smsStatus": "delivered",
                "smsStatusDetail": "Доставлено",
                "smsMessage": "Внимание, скидки!
Только сегодня"
            },
            {
                "phoneNumber": "79209383521",
                "dateSent": "02-04-2024 11:15:17",
                "smsStatus": "error",
                "smsStatusDetail": "Невозможно доставить",
                "smsMessage": "Ваш код авторизации: 14111"
            },
            {
                "phoneNumber": "79952125854",
                "dateSent": "04-04-2024 08:15:17",
                "smsStatus": "sent",
                "smsStatusDetail": "Просрочено",
                "smsMessage": "Ваш код авторизации: 14111"
            },
            {
                "phoneNumber": "79952126521",
                "dateSent": "05-04-2024 05:15:17",
                "smsStatus": "unknown",
                "smsStatusDetail": "Статус еще не получен",
                "smsMessage": "Ваш код авторизации: 14111"
            }
        ]
    }
}

Параметры ответа

Параметр  Формат  Описание 
data.totalCountSms  integer  Количество смс в выборке. 
data.pageOfResult  integer Номер страницы с результатами, которую запросили на входе.  
data.smsDetails.N.phoneNumber  string  Номер телефона, по которому отправлялась SMS. 
data.smsDetails.N.dateSent  string  Дата и время отправки SMS.
Пример: 04-04-2024 08:15:17 
data.smsDetails.N.smsStatus  string  Статус. Возможные значения:
  • waiting
  • unknown
  • sent
  • error
  • delivered
data.smsDetails.N.smsStatusDetail  string  Детализация статуса. Возможные значения:
  • Статус еще не получен. PS — передаем эту делать при статусе waiting;
  • Невозможно доставить;
  • Неверный номер;
  • Запрещено;
  • Недостаточно средств;
  • Недоступный номер;
  • Доставлено;
  • Ожидает отправки;
  • Передано оператору;
  • Просрочено.

1. Если от смсц нет статуса, мы выведем вейтинг с деталью
2. Если от смсц статус получен, но мы его не знаем, то статус unknown. Деталь — "Неизвестный статус"

3. Если от смсц статус получен и мы его знаем, то мы знаем, что отдать в ответе 
data.smsDetails.N.smsMessage  string  Текст отправленного SMS-сообщения.  

Типовые ошибки

Ответ с ошибкой в случаях:

  • ошибка авторизации;
  • ошибка параметров.

Ошибочный ответ содержит информацию о типе ошибки и пояснения к ней.

Тип ошибки    Пример   
Отсутствие доступа к методу  
{
 
"meta": [],
 
"data": {
 
     "message": "Пользователь {party_name} не имеет доступа к данному методу API"
 
}
 
}
Ошибка авторизации  
{
 
"message": "Invalid credentials."
 
}
Ошибка в содержимом параметров  
{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "dateFrom",
                    "message": "Значение не может быть больше текущего дня"
                },
                {
                    "fieldPath": "dateFrom",
                    "message": "Значение не может быть больше dateTo"
                },
                {
                    "fieldPath": "dateTo",
                    "message": "Значение не может быть больше текущего дня"
                },
                {
                    "fieldPath": "dateTo",
                    "message": "Значение не может быть меньше dateFrom",
                },
                {
                    "fieldPath": "phoneNumbers",
                    "message": "Эта коллекция должна содержать больше или равно 1 элементу"
                },
                {
                    "fieldPath": "dateFrom",
                    "message": "Значение не должно быть пустым."
                }
           
 
            ]
        }
    }
}
Синтаксическая ошибка JSON 
{
    "meta": [],
    "data": {
        "type": "apiError",
        "apiErrorData": {
            "errorCode": 1,
            "errorMessage": "Синтаксическая ошибка JSON в запросе или запрос пустой",
            "errorDescription": null
        },
        "validationErrorData": null
    }
}
Отсутствие обязательного поля  
{
    "meta": [],
    "data":{
        "message": "В запросе не указано обязательное поле dateTo"
    }
}

Доступ к методу

В систему прав доступов добавляется новый грант: "API-методы для управления SMS рассылками по базе клиентов", на чтение. В будущем появится и на редактирование, когда сделаем методы создания SMS-рассылок.

  • Если выдан доступ на чтение, то пользователь может использовать метод: 
    https://api.calltouch.ru/lead-service/v1/api/calltouch-leads/sms-to-clients/result

  • Если доступ не выдан, то пользоваться API-методом нельзя.

В тултип добавить: 

/lead-service/v1/api/calltouch-leads/sms-to-clients/result

Стоимость запроса в системе API-баллов

Группа методов    URL    Импорт/Экспорт    За успешный вызов    За объект   
API-методы для управления SMS рассылками по базе клиентов  https://api.calltouch.ru/lead-service/v1/api/calltouch-leads/sms-to-clients/result Экспорт  2  2   

Система баллов API Calltouch

Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов. За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch.

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).


12 ноября 2025
Не нашли решение проблемы?
Заполните форму, и мы вам поможем.
Похожие статьи
Недавно просмoтренные