---
title: Подключение к API OTP-кодов
description: Подключение к API OTP-кодов — базовый URL, аутентификация, форматы запросов и ответов, коды ответов, Swagger UI
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.



> **Коротко:** для работы с API OTP-кодов нужен базовый URL `https://web.otpcod.ru/api/v1` и API-ключ в заголовке `X-API-Key`. Для 2FA-интеграции — отдельный ключ и Basic Auth.

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

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

## Что вы получите

Готовое подключение к API OTP-сервиса: базовый URL, ключ, формат запросов, который можно использовать в интеграции.

## Перед началом

- [ ] У вас есть API-ключ с нужными правами доступа.
- [ ] У вас есть имена отправителей для каналов, по которым будете отправлять коды.
- [ ] Вы определили URL вебхука (если планируете получать статусы).

<Note>
Если ключа ещё нет — создайте его в разделе **API Подключения**. Подробнее: [API-ключи](/06-reference/01-api/api-keys).
</Note>

## Базовый URL

```
https://web.otpcod.ru/api/v1
```

Все эндпоинты добавляются к базовому URL. Например:

| Эндпоинт | Полный URL |
|---|---|
| `/messages` | `https://web.otpcod.ru/api/v1/messages` |
| `/omnimessages` | `https://web.otpcod.ru/api/v1/omnimessages` |
| `/broadcast/broadcasts` | `https://web.otpcod.ru/api/v1/broadcast/broadcasts` |

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

### OMNI API и Broadcasts API

API-ключ передаётся в заголовке `X-API-Key`:

```
X-API-Key: <ваш-ключ>
```

<Note>
При создании ключа вы выбираете имена отправителей. От выбранных имён зависит, по каким каналам ключ сможет отправлять сообщения. Подробнее: [API-ключи](/06-reference/01-api/api-keys).
</Note>

### 2FA-эндпоинты

2FA-интеграция использует **Basic Auth**. Логин — API-ключ интеграции, пароль — пустой. Ключ и URL выдаются при настройке интеграции в разделе **2FA Service**.

```
Authorization: Basic <base64(API-ключ:)>
```

В curl это передаётся флагом `-u`:

```bash
curl -X POST https://<домен-OTP>/api/v1/2fa/verify -u <API-ключ> -d requestId=<requestId> -d code=<код>
```

## Формат запроса

Все запросы используют JSON или form-data.

### OMNI API и Broadcasts API

| Заголовок | Значение |
|---|---|
| Content-Type | `application/json` |
| X-API-Key | Ваш API-ключ |

**Пример:**

```bash
curl --location 'https://web.otpcod.ru/api/v1/messages' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <ваш-ключ>' \
  --data-raw '{
    "contact": "905063565285",
    "channel": 1,
    "senderId": "<senderID>",
    "isOtp": true,
    "payload": {
      "text": "Ваш код: 1234"
    }
  }'
```

### 2FA-эндпоинты

| Заголовок | Значение |
|---|---|
| Content-Type | `application/x-www-form-urlencoded` |
| Authorization | Basic `<base64(API-ключ:)>` |

**Пример:**

```bash
curl -X POST https://<домен-OTP>/api/v1/2fa/verify \
  -u <API-ключ> \
  -d requestId=<requestId> \
  -d code=<код>
```

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

### OMNI API

Успешный ответ `202 Accepted`:

```json
{
  "error": false,
  "data": {
    "channel": 1,
    "transactionId": "95e3e0da-9684-4ba4-88a3-e9207ddeca05",
    "messageId": "6719b5f4-36af-4fba-b111-49ff07f4f96b"
  }
}
```

Ошибка содержит `error: true` и `data` с `message` и `requestId`. Подробнее: [Обработка ошибок API](/06-reference/01-api/api-errors).

### Broadcasts API

Успех — `200 OK` (с телом) или `204 No Content` (удаление). Ошибка содержит `execId`, `key`, `code`, `message`, `args`.

### 2FA-эндпоинты

**Проверка кода (`/2fa/verify`)** — успешный ответ `200 OK`:

```json
{
  "number": "12345678910",
  "verifiedAt": 1234567890
}
```

**Статус запроса (`/2fa/requests/{requestId}`)** — успешный ответ `200 OK`:

```json
{
  "id": "<requestId>",
  "number": "<номер>",
  "rate": 0.0248,
  "status": "SUBMIT",
  "sender": "<имя отправителя>",
  "goals": ["NUMBER_VERIFIED"],
  "createdAt": 1234567891011
}
```

## Коды ответов

| Код | Что означает |
|---|---|
| 200 OK | Успешно |
| 202 Accepted | Запрос принят, код в очереди |
| 204 No Content | Успешно, тело пустое |
| 400 Bad Request | Ошибка в параметрах запроса |
| 401 Unauthorized | Неверный или отсутствующий ключ |
| 403 Forbidden | Нет прав на операцию |
| 404 Not Found | Ресурс не найден |
| 500 Internal Server Error | Ошибка сервера |

## Swagger UI

- OMNI API: https://web.otpcod.ru/api/v1/swagger-ui/index.html?urls.primaryName=OMNI_API
- Broadcasts API: https://web.otpcod.ru/api/v1/swagger-ui/index.html?urls.primaryName=Broadcasts_API

<Note>
Swagger UI для 2FA-эндпоинтов не предусмотрен. Ключ и URL выдаются в разделе **2FA Service** личного кабинета.
</Note>

## Результат

Вы знаете базовый URL, умеете передавать ключ и понимаете формат ответов. Можно переходить к работе с конкретными эндпоинтами.

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

<Accordion title="401 Unauthorized">
**Причина:** заголовок `X-API-Key` не передан, ключ неверный.

**Решение:** проверьте заголовок и скопируйте ключ заново. Подробнее: [Ошибка 401](/06-reference/03-troubleshooting/ts-mapi-401).
</Accordion>

<Accordion title="403 Forbidden">
**Причина:** у ключа нет нужного scope.

**Решение:** откройте ключ и добавьте нужный scope в правах доступа. Подробнее: [API-ключи](/06-reference/01-api/api-keys).
</Accordion>

<Accordion title="400 Bad Request: sender not found">
**Причина:** в запросе указано имя отправителя, которое не привязано к этому ключу.

**Решение:** откройте ключ в разделе **API Подключения** и добавьте нужное имя отправителя.
</Accordion>

## См. также

<Columns cols={2}>
  <Card title="Обзор API OTP" icon="book" href="/02-otp/08-api/otp-api-overview">
    OMNI, Broadcasts, 2FA — обзор
  </Card>
  <Card title="OMNI API" icon="paper-plane" href="/02-otp/08-api/otp-api-omni">
    Отправка кодов и шаблонов
  </Card>
  <Card title="Broadcasts API" icon="bullhorn" href="/02-otp/08-api/otp-api-broadcasts">
    Запуск рассылок
  </Card>
  <Card title="API-ключи" icon="key" href="/06-reference/01-api/api-keys">
    Создание и управление ключами
  </Card>
</Columns>

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

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