Справочные эндпоинты

Коротко: кроме отправки кодов, OMNI API предоставляет справочные методы — узнать доступные каналы, статус отправителей, баланс, шаблоны и работу Telegram Gateway.

Кому подходит

• Роль: Разработчик, Интегратор
• Уровень: Опытный

Что это

Справочные эндпоинты возвращают данные, которые нужны для настройки и проверки интеграции. Они не отправляют сообщения, а показывают текущее состояние вашего аккаунта.

Каналы, доступные компании

Эндпоинт: GET /channels

Возвращает список каналов, которые подключены у вашей компании. Не все каналы из общей таблицы могут быть доступны — этот метод покажет фактические.

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

curl --location 'https://web.otpcod.ru/api/v1/channels' \
  --header 'X-API-Key: <ваш-ключ>'

Успешный ответ 200 OK:

{
  "error": false,
  "data": [
    {
      "id": 1,
      "type": "SMS",
      "description": "Sms channel type"
    },
    {
      "id": 2,
      "type": "RCS",
      "description": "Rcs channel type"
    },
    {
      "id": 3,
      "type": "VIBER",
      "description": "Viber channel type"
    },
    {
      "id": 4,
      "type": "WHATSAPP",
      "description": "Whatsapp channel type"
    },
    {
      "id": 6,
      "type": "WECHAT",
      "description": "Wechat channel type"
    },
    {
      "id": 7,
      "type": "EMAIL",
      "description": "Email channel type"
    },
    {
      "id": 8,
      "type": "TELEGRAM_GATEWAY",
      "description": "Telegram Gateway"
    },
    {
      "id": 10,
      "type": "PUSH",
      "description": "Push"
    },
    {
      "id": 11,
      "type": "TTS",
      "description": "Text To Speech (TTS)"
    },
    {
      "id": 14,
      "type": "FLASH_CALL",
      "description": "Flash call"
    }
  ]
}

Поля ответа:

Имена отправителей

Эндпоинт: GET /senders

Возвращает список имён отправителей компании с их статусами и каналами.

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

curl --location 'https://web.otpcod.ru/api/v1/senders' \
  --header 'X-API-Key: <ваш-ключ>'

Успешный ответ 200 OK:

{
  "data": [
    {
      "channel": 1,
      "displayName": "SMS Sender",
      "senderId": "1112223334",
      "status": 2,
      "vendorType": "transit_http_sms",
      "webhookGuid": "8ed6b786-9701-4984-9c50-bc2c66b2ffed",
      "webhookUrl": "https://test.site.com/webhook"
    }
  ],
  "error": false
}

Поля ответа:

Статусы отправителя:

Когда использовать:

• Проверить, что имя отправителя имеет статус 2 (Active) перед отправкой.
• Узнать, к какому каналу привязано имя.
• Проверить, что новое имя уже одобрено.

Баланс договора

Эндпоинт: GET /balance

Возвращает баланс по всем договорам компании. У одной компании может быть несколько договоров — каждый со своим балансом.

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

curl --location 'https://web.otpcod.ru/api/v1/balance' \
  --header 'X-API-Key: <ваш-ключ>'

Успешный ответ 200 OK:

[
  {
    "agreementId": 0,
    "amount": 0,
    "balanceId": 0,
    "currency": "string",
    "name": "string"
  }
]

Поля ответа:

Когда использовать:

• Перед массовой отправкой — убедиться, что баланса достаточно.
• В мониторинге — проверять баланс автоматически.
• При интеграции с биллингом — синхронизировать данные.

Шаблоны сообщений

Эндпоинт: GET /templates

Возвращает список шаблонов сообщений компании.

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

curl --location 'https://web.otpcod.ru/api/v1/templates' \
  --header 'X-API-Key: <ваш-ключ>'

Успешный ответ 200 OK:

{
  "data": [
    {
      "channel": 4,
      "company_id": 1,
      "content": "{\"suggestionsInside\":[],\"cards\":[],\"selectedType\":\"whatsAppText\",\"preview_url\":true,\"text\":{\"body\":\"_test_\"}}",
      "created_at": "2025-01-23T18:31:35.587814Z",
      "created_by": "string",
      "id": 1,
      "message": "{text: {body: \"_test_\"}, type: \"text\", preview_url: true, recipient_type: \"individual\"}",
      "name": "wa_test",
      "updated_at": "2025-01-23T18:31:35.587823Z",
      "updated_by": "string"
    }
  ],
  "error": false,
  "size": 135
}

Поля ответа:

Когда использовать:

• Получить ID шаблона для отправки через template.id.
• Проверить, что шаблон создан.
• Синхронизировать шаблоны между своей системой и платформой.

Шаблоны WhatsApp

Эндпоинт: GET /wa_templates

Возвращает список шаблонов WhatsApp со статусами одобрения.

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

curl --location 'https://web.otpcod.ru/api/v1/wa_templates' \
  --header 'X-API-Key: <ваш-ключ>'

Успешный ответ 200 OK:

{
  "data": [
    {
      "category": "MARKETING",
      "content": "[{\"text\": \"1\", \"type\": \"BODY\"}]",
      "created_at": "2025-01-23T18:31:35.587823Z",
      "description": "my_favorite_template",
      "id": 1,
      "language": "en",
      "language_name_en": "English",
      "last_synced_at": "2025-01-23T18:31:35.587823Z",
      "rejection_reason": "custom_reason",
      "sender_display_name": "MySender",
      "sender_id": "test_sender",
      "status": "APPROVED",
      "status_updated_at": "2025-01-23T18:31:35.587814Z",
      "template_name": "test_template",
      "updated_at": "2025-01-23T18:31:35.587823Z"
    }
  ],
  "error": false,
  "size": 135
}

Поля ответа:

Когда использовать:

• Проверить статус одобрения шаблона в WhatsApp.
• Найти ID шаблона для отправки через template.id.
• Узнать причину отклонения.

Telegram Gateway: отзыв сообщения

Эндпоинт: POST /messages/revoke

Отзывает ранее отправленное верификационное сообщение Telegram Gateway. Например, если пользователь запросил новый код — старый нужно отозвать, чтобы он не сработал.

Тело запроса:

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

curl --location 'https://web.otpcod.ru/api/v1/messages/revoke' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "messageId": "019372a1-d252-7908-9216-028bd36c7af1"
  }'

Успешный ответ 200 OK:

{
  "error": "string",
  "message_id": "019372a1-d252-7908-9216-028bd36c7af1",
  "success": true
}

Поля ответа:

Когда использовать:

• Пользователь запросил повторную отправку кода.
• Отправка устарела или была ошибочной.

Telegram Gateway: проверка статуса

Эндпоинт: POST /messages/verification

Проверяет статус доставки и верификации в Telegram Gateway.

Тело запроса:

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

curl --location 'https://web.otpcod.ru/api/v1/messages/verification' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "messageId": "019372a1-d252-7908-9216-028bd36c7af1",
    "code": "1234"
  }'

Успешный ответ 200 OK:

{
  "delivery_status": "read",
  "error": "string",
  "message_id": "019372a1-d252-7908-9216-028bd36c7af1",
  "success": true,
  "verification_status": "code_valid"
}

Поля ответа:

Когда использовать:

• Узнать, верифицирован ли пользователь.
• Проверить, что код дошёл до получателя.
• Диагностировать проблему, если код не пришёл.

Коды ответов

Лимиты

На один канал действует ограничение — не более 5 одновременных запросов на отправку.

Сообщения становятся в очередь и отправляются асинхронно. Отправка и получение статуса не зависят друг от друга.

Если нужно больше — лимит увеличивается до фактического потребления по запросу в поддержку сервиса.

При превышении лимита API возвращает код 429 Too Many Requests.

Частые проблемы

См. также

Нужна помощь?

• OTP-коды: support@otpcod.ru