📱 API V2 - Документация по отправке SMS

📖 Описание

API V2 позволяет отправлять SMS-сообщения с индивидуальным текстом для каждого номера телефона. Каждый номер может иметь свой уникальный текст сообщения.

🔗 Endpoint

POST /api/v2/sms/contacts

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

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

Authorization: Bearer YOUR_AUTH_TOKEN

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

Headers

Параметр	Тип	Обязательный	Описание
Authorization	string	Да	Bearer токен пользователя
Content-Type	string	Да	application/json

Body (JSON)

Параметр	Тип	Обязательный	Описание
token	string	Да	Токен компании
apiVersion	string	Да	Версия API (должна быть "V2")
data	array	Да	Массив объектов с номерами и текстами SMS
data[].number	string	Да	Номер телефона в формате +7XXXXXXXXXX или 8XXXXXXXXXX
data[].text	string	Да	Текст SMS сообщения для данного номера

Формат номера телефона

• Номера автоматически форматируются
• Удаляются все нечисловые символы
• Если номер начинается с 7 и содержит 11 цифр, он преобразуется в формат с 8
• Финальный формат: 8XXXXXXXXXX (11 цифр)

---

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

🐍 Python (requests)

import requests

url = "https://timeleads.xn--b1ajetccdi.xn--p1ai/api/v2/sms/contacts"
auth_token = "<YOUR_AUTH_TOKEN>"
company_token = "<YOUR_COMPANY_TOKEN>"

arrayVar = {
    "token": company_token,
    "data": [
        {"number": "+71234567890", "text": "Текст смс"},
        {"number": "+71234567891", "text": "Текст смс2"},
    ],
    "apiVersion": "V2"
}

headers = {
    "Authorization": f"Bearer {auth_token}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=arrayVar, headers=headers)
print(response.json())

🐘 PHP (cURL)

<?php
$url = "https://timeleads.xn--b1ajetccdi.xn--p1ai/api/v2/sms/contacts";
$auth_token = "<YOUR_AUTH_TOKEN>";
$company_token = "<YOUR_COMPANY_TOKEN>";

$arrayVar = [
    "token"      => $company_token,
    "data"       => [
        ["number" => "+71234567890", "text" => "Текст смс"],
        ["number" => "+71234567891", "text" => "Текст смс2"],
    ],
    "apiVersion" => "V2"
];

$data = json_encode($arrayVar);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer " . $auth_token,
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "HTTP Code: " . $httpCode . "\n";
echo "Response: " . $response;
?>

🔧 cURL (Command Line)

curl --location --request POST 'https://timeleads.xn--b1ajetccdi.xn--p1ai/api/v2/sms/contacts' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>' \
--data '{
    "token": "<YOUR_COMPANY_TOKEN>",
    "data": [
        {"number": "+71234567890", "text": "Текст смс"},
        {"number": "+71234567891", "text": "Текст смс2"}
    ],
    "apiVersion": "V2"
}'

---

📬 Варианты ответов API

✅ 1. Успешная отправка (200 OK)

Описание: SMS успешно добавлены в очередь на отправку.

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

{
    "status": "ok",
    "message": "СМС на отправку успешно создано",
    "data": [
        {
            "number": "81234567890",
            "sms_id": 12345
        },
        {
            "number": "81234567891",
            "sms_id": 12346
        }
    ]
}

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

Поле	Тип	Описание
status	string	Статус выполнения запроса ("ok")
message	string	Сообщение о результате
data	array	Массив созданных SMS
data[].number	string	Отформатированный номер телефона
data[].sms_id	integer	Уникальный ID созданного SMS в системе

📌 Примечания:

• ✓ Каждый номер получает уникальный sms_id
• ✓ Номера автоматически форматируются (например, +7 меняется на 8)
• ✓ sms_id можно использовать для отслеживания статуса доставки через Postback
• ✓ SMS обрабатывается асинхронно в порядке очереди

---

❌ 2. Компания не найдена (200 OK)

Описание: Компания с указанным токеном и версией API не найдена в системе.

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

{
    "status": "error",
    "message": "Компания с таким токеном/версией не найдена"
}

⚠️ Причины:

• ❌ Неверный токен компании (token)
• ❌ Несоответствие версии API в запросе и в настройках компании
• ❌ Токен был отозван или деактивирован
• ❌ Компания была удалена из системы

💡 Рекомендации:

1. ✓ Проверьте правильность токена компании
2. ✓ Убедитесь, что версия API установлена как "V2" в настройках компании
3. ✓ Проверьте активность токена в личном кабинете
4. ✓ Сгенерируйте новый токен, если необходимо

---

⚠️ 3. Неподдерживаемая версия API (200 OK)

Описание: Указана версия API, отличная от "V2", или версия не указана.

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

{
    "status": "error",
    "message": "Указанная версия API не поддерживается"
}

⚠️ Причины:

• ❌ В параметре apiVersion указано значение отличное от "V2" (например, "V3")
• ❌ Параметр apiVersion отсутствует в запросе
• ❌ Параметр apiVersion имеет неверный формат

💡 Рекомендации:

1. ✓ Убедитесь, что в теле запроса присутствует параметр "apiVersion": "V2"
2. ✓ Проверьте регистр букв (должно быть именно "V2")
3. ✓ Убедитесь, что параметр передается в формате JSON

---

🔒 4. Ошибка авторизации (401 Unauthorized)

Описание: Неверный или отсутствующий Bearer токен в заголовке.

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

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

⚠️ Причины:

• ❌ Отсутствует заголовок Authorization
• ❌ Неверный формат токена (должен быть "Bearer TOKEN")
• ❌ Токен пользователя недействителен или истек
• ❌ Токен был отозван

💡 Рекомендации:

1. ✓ Проверьте наличие заголовка Authorization: Bearer YOUR_TOKEN
2. ✓ Убедитесь в правильности токена пользователя
3. ✓ Получите новый токен авторизации в личном кабинете

---

📝 5. Некорректный JSON (400 Bad Request)

Описание: Тело запроса содержит некорректный JSON или отсутствуют обязательные параметры.

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

{
    "status": "error",
    "message": "Invalid JSON"
}

⚠️ Причины:

• ❌ Невалидный JSON в теле запроса
• ❌ Отсутствуют обязательные поля (token, data, apiVersion)
• ❌ Массив data пуст
• ❌ В элементах data отсутствуют поля number или text

💡 Рекомендации:

1. ✓ Проверьте корректность JSON (используйте валидатор JSON)
2. ✓ Убедитесь, что все обязательные поля присутствуют
3. ✓ Проверьте, что массив data содержит хотя бы один элемент
4. ✓ Убедитесь, что каждый элемент в data содержит number и text

---

🔥 6. Внутренняя ошибка сервера (500 Internal Server Error)

Описание: Критическая ошибка на стороне сервера при обработке запроса.

⚠️ Важно: При возникновении ошибки 500 ответ от сервера может не прийти или прийти некорректный.

💡 Рекомендации:

1. ✓ Повторите запрос через некоторое время
2. ✓ Если ошибка повторяется, обратитесь в техническую поддержку
3. ✓ Сохраните данные запроса и время возникновения ошибки для передачи в ТП

---

📊 Коды состояния HTTP

Код	Описание	Иконка
200	Запрос успешно обработан (проверьте status в ответе)	✅
400	Некорректный запрос (невалидный JSON)	📝
401	Ошибка авторизации (неверный Bearer токен)	🔒
500	Внутренняя ошибка сервера	🔥

⚙️ Особенности работы API

📞 Форматирование номеров

• ✓ Все нечисловые символы удаляются автоматически
• ✓ Номера, начинающиеся с +7, преобразуются в формат с 8
• ✓ Итоговый формат: 8XXXXXXXXXX (11 цифр)

Примеры преобразования:

Входной формат	Выходной формат	Статус
+71234567890	81234567890	✅
71234567890	81234567890	✅
8 (123) 456-78-90	81234567890	✅

📏 Ограничения

• ⚠️ Максимальная длина текста SMS не ограничена API, но зависит от оператора связи
• ✓ Рекомендуемая длина текста: до 70 символов (кириллица) или 160 символов (латиница)
• ✓ Количество номеров в одном запросе не ограничено, но рекомендуется не более 1000 за раз

🔄 Обработка SMS

• ✓ SMS обрабатывается асинхронно в порядке очереди
• ✓ Для отслеживания статуса используйте sms_id из ответа
• ✓ Статус доставки можно получить через Postback-уведомления

---

📡 Отслеживание статуса доставки (Postback)

Для отслеживания статуса доставки SMS настройте Postback URL в личном кабинете. Система будет отправлять уведомления о статусе доставки с использованием переменных:

Доступные переменные:

• {{now}} — текущая дата и время
• {{status}} — статус доставки SMS (буквенный)
• {{msg_id}} — ID сообщения (совпадает с sms_id)
• {{number}} — номер получателя
• {{cost}} — стоимость SMS

Пример Postback URL:

https://example.com/webhook?sms_id={{msg_id}}&status={{status}}&number={{number}}&cost={{cost}}

Пример реального вызова:

https://example.com/webhook?sms_id=12345&status=delivered&number=81234567890&cost=1.50

---

📊 Статусы доставки от провайдера

Система возвращает буквенные статусы, получаемые от SMS-провайдера:

Статус	Описание	Иконка
delivered	SMS успешно доставлено получателю	✅
failed	Ошибка доставки SMS	❌
pending	SMS в обработке	⏳
transmitted	SMS передано в сеть оператора	📤
queued	SMS в очереди на отправку	📋
error	Критическая ошибка при обработке	🔥

📌 Примечание:

Статусы приходят в Postback-уведомлениях в переменной {{status}}

---

💬 Поддержка

При возникновении проблем или вопросов:

Перед обращением в поддержку:

1. ✓ Проверьте корректность всех параметров запроса
2. ✓ Убедитесь в валидности токенов
3. ✓ Проверьте формат номеров телефонов
4. ✓ Изучите раздел "Варианты ответов API"

Для обращения в техническую поддержку подготовьте:

• 📋 Пример запроса (с замаскированными токенами)
• 📋 Полученный ответ от API
• 📋 Время возникновения ошибки
• 📋 Код HTTP статуса

---

📝 Changelog

🎉 Версия 2.0 (Текущая)

• ✅ Добавлена возможность отправки индивидуального текста для каждого номера
• ✅ Улучшено форматирование номеров телефонов
• ✅ Добавлена поддержка Postback уведомлений с переменными
• ✅ Возвращается sms_id для каждого созданного SMS
• ✅ Статусы доставки от провайдера в буквенном формате
• ✅ Добавлена переменная {{cost}} в Postback

---

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

1. Получите токены:

• 🔑 Bearer токен авторизации из личного кабинета
• 🔑 Токен компании (сгенерируйте в настройках)

2. Настройте API V2:

• ⚙️ Установите версию API "V2" в настройках компании
• 📡 Настройте Postback URL для получения статусов

3. Отправьте первый запрос:

• 📤 Используйте примеры кода выше
• ✅ Проверьте успешность создания SMS
• 🔍 Отслеживайте статусы через Postback

Готово! 🎉 Ваша интеграция с API V2 настроена!