Оформление
Общие контракты JSON API
Эта страница определяет форматы и результаты, используемые действиями версии 2020-01-01. Правила кабинетов могут отличаться; например, кабинет использует другие минимальные сроки рассылки.
Идентификаторы, телефоны и время
ID документов — строки из 24 строчных шестнадцатеричных символов, например 000000000000000000000001. UUID-подобная строка ключа API имеет другой формат; ключом нельзя заменить ID подписи, справочника или SMS.
Номер одиночной SMS, черного списка и записи JSON-справочника — + и 9–15 цифр без разделителей. Ручной phonelist дополнительно принимает оформленные номера с пробелами, дефисами и скобками, с необязательным начальным плюсом; для единообразия передавайте международные номера с плюсом. Дубликаты phonelist объединяются. Дубликат внутри entries справочника отклоняется. В ответах публичного API телефон — строка с плюсом.
Расписание и expire принимают точный формат YYYY-MM-DDTHH:MM:SS+HH:MM или с отрицательным смещением. Для UTC используйте +00:00: сокращенное Z, дробные секунды и дата без времени не соответствуют строгой проверке этой версии. Даты результата представлены ISO 8601 в часовом поясе пользователя.
Повтор создания
sms-create и sms-create-bulk принимают необязательный request_id длиной 1–64 символа: латинские буквы, цифры, -, _. Повтор с тем же request_id возвращает ранее созданный документ того же пользователя и проекта. Одиночные SMS и рассылки используют отдельные области ключей. Полезный сценарий — повтор запроса после таймаута с тем же request_id.
Повтор не сравнивает новый текст, номер и расписание с исходными. Не используйте один request_id для разных операций. При этом проверка формата, подписи, маршрута и подготовка выполняются до возврата существующей записи: изменившиеся условия могут привести к отказу повтора. Полная отмена удаляет документ, поэтому request_id не служит бессрочной защитой от создания новой операции после ее удаления. Без request_id повтор создает новое сообщение или рассылку.
Результат SMS
| Поле | Тип | Значение |
|---|---|---|
id | string | ID SMS. |
created, updated | string | Время создания и обновления. |
signature | string | Строка отправителя. |
phone | string | Международный номер с плюсом. |
message | string | Подготовленный текст. |
parts | integer | Число частей SMS; длинный текст может оплачиваться несколькими частями. |
price | number | Стоимость одной части. |
total | number | Полная стоимость SMS. |
status | string | Текущее состояние, таблица ниже. |
paused | boolean | Пауза перед отправкой; независима от status. |
paid | boolean | Есть резерв ИЛИ окончательное списание. Не признак доставки и не подтверждение именно списания. |
schedule и expire в этом результате не возвращаются. Сохраняйте их из своего запроса, если они нужны вашей интеграции.
| Состояние | Смысл |
|---|---|
init | Подготовка, в том числе SMS, принятой по SMPP. |
reserve | Резервирование стоимости. |
ready | Готова к передаче шлюзу; учитываются paid, paused и плановое время. |
route | Повторный выбор шлюза. |
enroute | Передана шлюзу, итог еще определяется. |
unpaid | Резерв не получен из-за недостатка средств. |
noroute | Маршрут не найден. |
cancel | Принят запрос отмены; после обработки одиночная SMS удаляется. |
cancelled | Неотправленная SMS массовой рассылки отменена. |
delivered | Сообщение отмечено как доставленное. |
undeliverable, rejected, deleted, expired, unknown, error | Отказ, истечение, неизвестный итог или ошибка; детали различаются по этапу. |
Для длинного сообщения общий статус delivered не подтверждает доставку всех частей текста.
Результат рассылки
| Поле | Тип | Значение |
|---|---|---|
id | string | ID рассылки. |
created, updated | string | Время создания и обновления. |
signature, message | string | Подпись и исходный общий текст. |
num | integer | Число созданных SMS; при частичной отмене остается исходным. |
total | number | Сумма стоимости; уменьшается при отмене неотправленного остатка. |
status | string | reserve, ready, paused, unpaid, cancel, done; модель также предусматривает init. |
paid | boolean | Есть общий резерв либо списание. |
done означает завершение обработки рассылки и финансового итога. Это не обещание доставки всех сообщений. В ответе нет списка дочерних SMS, флага paused и расписания. После полной отмены рассылка удаляется, последующее чтение ее ID дает NOT-FOUND.
cancel у рассылки подтверждает принятый асинхронный запрос, а не освобождение всего резерва. Подходящие свободные ready SMS приостанавливаются вместе с приемом запроса; ранее начатая часть может продолжиться и остается в стоимости. Последующее чтение может сразу показать более поздний результат. Окончательный результат проверяйте запросом статуса. Контракт отмены рассылки.
Остальные результаты
| Результат | Поля |
|---|---|
| Расчет SMS | parts (integer), price и total (number). |
| Расчет рассылки | num (integer), total (number); поля details нет. |
| Запись черного списка | id, created, updated, category, phone — строки; необязательный comment — строка. |
| Телефонный справочник | id, created, updated, name — строки; num — integer. Записи не включены. |
| SMS/Viber-подпись | id, created, updated, category, signature, status — строки. |
Категории SMS-подписей — sms_promo и sms_service; Viber — viber. Состояния подписи: new, approved, rejected; deleted предусмотрен моделью, но действующее удаление физическое, а поиск исключает deleted. Отправку разрешает одобренная SMS-подпись. Отдельные операторские согласования доступны в кабинетах; публичный результат их не включает.
Стоимость и ограничения
Стоимость определяется маршрутом и количеством частей после нормализации и подстановок. Денежные значения JSON возвращаются числами. Для собственных расчетов денег используйте десятичную арифметику. Расчет не фиксирует цену будущего создания и не резервирует средства.
Текст — до 1000 символов после нормализации. Справочник и ручной список — до 500 000 элементов до обработки. Эти ограничения не отменяют 2 МиБ на запрос. Расписание одиночной SMS — до 30 суток вперед с допуском 5 минут в прошлом; начало рассылки — до 30 суток с допуском одного часа. Явный expire — от часа до трех суток после планового времени (рассылка — после till). У одиночной SMS expire по умолчанию отсчитывается от текущего времени, поэтому для будущего schedule задавайте его явно. Вебхуки, отправка Viber и действия phonebook-update, template-* и sms-signature-create этим JSON API не предоставляются.