API получения статуса доставки SMS

API для получения информации о статусе доставки SMS сообщений. Позволяет запрашивать статус одного или нескольких сообщений одновременно.

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

Endpoint

POST /api/v1/statisticasms/delivery-status

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

API требует Bearer токен для аутентификации. Взять его можно при создании компании.Токен передается в заголовке запроса:

Authorization: Bearer YOUR_AUTH_TOKEN

Запрос одного сообщения

{
    "message_id": 123
}

Запрос нескольких сообщений

{
    "message_ids": [123, 456, 789]
}

ВАЖНО

Для массива используйте message_ids (множественное число)!

---

Формат ответа

Ответ для одного ID

{
    "status": "success",
    "data": {
        "message_id": 123,
        "from_number": "79001234567",
        "contact_phone": "79007654321",
        "company_id": 10,
        "current_status": "delivered",
        "total_cost": 1.50,
        "billing_status": "billed"
    }
}

Ответ для массива IDs

{
    "status": "success",
    "data": [
        {
            "message_id": 123,
            "from_number": "79001234567",
            "contact_phone": "79007654321",
            "company_id": 10,
            "current_status": "delivered",
            "total_cost": 1.50,
            "billing_status": "billed"
        },
        {
            "message_id": 456,
            "from_number": "79001234567",
            "contact_phone": "79007654322",
            "company_id": 10,
            "current_status": "undelivered",
            "total_cost": 0,
            "billing_status": "failed"
        }
    ],
    "total_found": 2,
    "requested_ids": [123, 456]
}

---

Поля ответа

Поле	Тип	Описание
message_id	integer	ID сообщения в системе
from_number	string	Номер отправителя
contact_phone	string	Телефон контакта (получателя)
company_id	integer	ID компании
current_status	string	Текущий статус доставки (delivered, undelivered, pending, и т.д.)
total_cost	float	Стоимость отправки сообщения
billing_status	string	Статус биллинга (billed, failed, pending)

---

Примеры использования

cURL

Запрос одного сообщения

curl -X POST https://your-domain.com/api/v1/statisticasms/delivery-status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{"message_id": 123}'

Запрос нескольких сообщений

curl -X POST https://your-domain.com/api/v1/statisticasms/delivery-status \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_AUTH_TOKEN>" \
  -d '{"message_ids": [123, 456, 789]}'

PHP

<?php
// Запрос нескольких сообщений
$data = ['message_ids' => [123, 456, 789]];

$ch = curl_init('https://your-domain.com/api/v1/statisticasms/delivery-status');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Authorization: Bearer <YOUR_AUTH_TOKEN>'
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['status'] === 'success') {
    foreach ($result['data'] as $message) {
        echo "ID: {$message['message_id']}, Статус: {$message['current_status']}\n";
        echo "Стоимость: {$message['total_cost']} руб.\n";
        echo "Биллинг: {$message['billing_status']}\n\n";
    }
}

curl_close($ch);
?>

JavaScript (fetch)

// Запрос нескольких сообщений
fetch('https://your-domain.com/api/v1/statisticasms/delivery-status', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer <YOUR_AUTH_TOKEN>'
    },
    body: JSON.stringify({ message_ids: [123, 456, 789] })
})
.then(response => response.json())
.then(data => {
    if (data.status === 'success') {
        console.log(`Найдено сообщений: ${data.total_found}`);

        data.data.forEach(msg => {
            console.log(`ID: ${msg.message_id}`);
            console.log(`Статус: ${msg.current_status}`);
            console.log(`Стоимость: ${msg.total_cost} руб.`);
            console.log('---');
        });
    }
})
.catch(error => console.error('Ошибка:', error));

Python (requests)

import requests
import json

url = 'https://your-domain.com/api/v1/statisticasms/delivery-status'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <YOUR_AUTH_TOKEN>'
}

# Запрос нескольких сообщений
data = {'message_ids': [123, 456, 789]}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result['status'] == 'success':
    print(f"Найдено сообщений: {result['total_found']}")

    for message in result['data']:
        print(f"ID: {message['message_id']}")
        print(f"Статус: {message['current_status']}")
        print(f"Стоимость: {message['total_cost']} руб.")
        print('---')

---

Обработка ошибок

Сообщение не найдено (404)

{
    "status": "error",
    "message": "Сообщение с указанным ID не найдено"
}

Примечание

При запросе массива ID, если ни одно сообщение не найдено, вернется ошибка 404.

Неверный формат запроса (400)

{
    "status": "error",
    "message": "Необходимо передать либо \"message_id\" (один ID), либо \"message_ids\" (массив ID)"
}

Пустой массив ID (400)

{
    "status": "error",
    "message": "Массив ID не может быть пустым"
}

Ошибка авторизации (401)

{
    "status": "error",
    "message": "Unauthorized"
}

Внутренняя ошибка сервера (500)

{
    "status": "error",
    "message": "Внутренняя ошибка сервера"
}

---

Статусы доставки

Возможные значения поля current_status:

Статус	Описание
pending	Сообщение в очереди на отправку
sent	Сообщение отправлено оператору
delivered	Сообщение доставлено получателю
undelivered	Сообщение не доставлено
failed	Ошибка при отправке
rejected	Сообщение отклонено оператором

Статусы биллинга

Возможные значения поля billing_status:

Статус	Описание
pending	Ожидает тарификации
billed	Тарифицировано успешно
failed	Ошибка тарификации
cancelled	Тарификация отменена

---

Лимиты и ограничения

• Максимальное количество ID в одном запросе: 100
• Частота запросов: не более 60 запросов в минуту
• Timeout: 30 секунд

Рекомендация

Для больших объемов данных используйте пагинацию и разбивайте запросы на батчи по 50-100 ID.

---

Часто задаваемые вопросы

Как узнать ID сообщения?

ID сообщения (message_id) возвращается при отправке SMS через API отправки. Сохраняйте его для последующих запросов статуса.

Как долго хранится информация о статусах?

История статусов доставки хранится бессрочно.

Можно ли получить историю всех статусов сообщения?

Данный endpoint возвращает только текущий статус.

Что делать, если сообщение не найдено?

Проверьте: 1. Правильность ID сообщения 2. Принадлежность сообщения вашей компании 3. Наличие прав доступа к данным

---

Примеры интеграции

Мониторинг доставки

// Проверка статуса доставки каждые 5 секунд
const messageIds = [123, 456, 789];

const checkDelivery = setInterval(async () => {
    const response = await fetch('/api/v1/statisticasms/delivery-status', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer <YOUR_AUTH_TOKEN>'
        },
        body: JSON.stringify({ message_ids: messageIds })
    });

    const data = await response.json();

    if (data.status === 'success') {
        const allDelivered = data.data.every(msg => 
            msg.current_status === 'delivered'
        );

        if (allDelivered) {
            console.log('Все сообщения доставлены!');
            clearInterval(checkDelivery);
        }
    }
}, 5000);

Расчет общей стоимости

<?php
function calculateTotalCost($messageIds) {
    $data = ['message_ids' => $messageIds];

    $ch = curl_init('https://your-domain.com/api/v1/statisticasms/delivery-status');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'Authorization: Bearer <YOUR_AUTH_TOKEN>'
    ]);

    $response = curl_exec($ch);
    $result = json_decode($response, true);

    $totalCost = 0;

    if ($result['status'] === 'success') {
        foreach ($result['data'] as $message) {
            $totalCost += $message['total_cost'];
        }
    }

    return $totalCost;
}

// Использование
$messageIds = [123, 456, 789];
$cost = calculateTotalCost($messageIds);
echo "Общая стоимость: $cost руб.";
?>

---

Changelog

v1.0.0 (2025-10-23)

• Первая версия API статистики доставки SMS
• Поддержка запроса одного и нескольких сообщений
• Добавлена информация о биллинге