Адрес и формат JSON API

JSON API версии 2020-01-01 принимает POST-запросы и возвращает JSON. Список всех действующих действий и общие контракты описывают возможности этой версии. Контракт проверен по версии разработки 2026-10-11.

Адрес

https://api.yesms.ru/api/json/2020-01-01

Путь текущего приложения — /api/json/2020-01-01. Заголовки: Content-Type: application/json; charset=utf-8 и Accept: application/json. Доступность продового домена и его прокси не проверялась в рамках актуализации контракта.

Запрос

{
  "api_key": "00000000-0000-0000-0000-000000000001",
  "action": "sms-status",
  "data": {
    "id": "000000000000000000000001"
  }
}

В примерах используются вымышленные ключи и идентификаторы. Замените их значениями своей учетной записи.

api_key и action — обязательные строки. Поле data передается для действий с параметрами. У blacklist-search, phonebook-search, sms-signature-search и viber-signature-search поля data нет: даже {} в нем отклоняется как лишнее поле. Неизвестные поля запроса и вложенных объектов отклоняются.

Максимальное тело запроса — 2 МиБ (2 097 152 байта), допустимая глубина JSON — 16. Эти границы могут оказаться строже предела количества номеров: 500 000 записей не обязательно помещаются в один запрос.

Ответ

Действия чтения и изменения возвращают success: true и data; data бывает объектом или массивом. Удаление возвращает только {"success": true}. Ошибка возвращается как success: false и строковый код error:

{
  "success": false,
  "error": "SMS-STATUS-ID-NOT-FOUND"
}

Проверяйте HTTP-статус, затем success. Успешный HTTP-ответ может содержать отказ бизнес-операции. Сбой HTTP, неверный JSON ответа и таймаут следует обрабатывать отдельно от кодов ниже. Успех sms-create или sms-create-bulk означает создание для последующей обработки; он не подтверждает доставку и списание денег.

Общие ошибки

Код	Причина
REQUEST-TOO-LARGE	Тело превышает 2 МиБ.
REQUEST-INVALID-FORMAT	Неверный JSON, недопустимая структура, превышенная глубина или лишние поля.
REQUEST-API-KEY-REQUIRED	Нет api_key.
REQUEST-API-KEY-INVALID-TYPE	api_key не строка.
REQUEST-API-KEY-INVALID-FORMAT	Ключ не соответствует формату выдаваемых ключей.
REQUEST-API-KEY-NOT-FOUND	Нет ключа, его пользователя или активного проекта.
REQUEST-API-KEY-NOT-SUPPORTED	Ключ выпущен для другой версии API.
REQUEST-API-KEY-REJECTED	Адрес клиента не прошел ограничения ключа.
REQUEST-USER-BLOCKED	Пользователь заблокирован.
REQUEST-ACTION-REQUIRED	Нет action.
REQUEST-ACTION-INVALID-TYPE	action не строка.
REQUEST-ACTION-NOT-SUPPORTED	Действие не входит в список этой версии.
REQUEST-DATA-REQUIRED	Для выбранного действия нет data.
REQUEST-DATA-INVALID-TYPE	data не является объектом/массивом JSON, ожидаемым действием.
REQUEST-DATA-INVALID-FORMAT	Недопустимые поля data в действиях массового расчета/создания.

Коды проверки конкретных полей перечислены на страницах действий. Клиенту стоит сохранять точный код вместе с действием и своим идентификатором операции.