# Документация · Otipi

Один API для почты, SMS и WhatsApp. Все запросы идут на `https://otipi.co.il/v1`, данные в формате JSON.

## Быстрый старт

Создайте ключ в кабинете и отправьте один запрос:

```bash
curl https://otipi.co.il/v1/messages \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+972501234567",
    "template": "login-code",
    "variables": { "code": "482917", "app": "MyApp", "minutes": 5 }
  }'
```

Ответ приходит сразу, ещё до того, как сообщение ушло:

```json
{
  "id": "msg_7Qk2LxWb9RtY3nPd5sAe",
  "channel": "sms",
  "to": "+972501234567",
  "status": "queued",
  "mode": "test",
  "segments": 1,
  "created_at": "2026-11-10T08:15:02.000Z"
}
```

## Ключи

Ключ передаётся в каждом запросе, в заголовке `Authorization: Bearer`. Это секрет: используйте его только на сервере, никогда в браузере или в мобильном приложении.

Ключ на `sk_test_` работает в тестовом режиме и никому ничего не отправляет. Ключ на `sk_live_` отправляет по-настоящему.

## Библиотека для Node.js

Один файл, без зависимостей, для Node 18 и новее. [Скачайте otipi.js](https://otipi.co.il/sdk/otipi.js), положите в проект и подключите:

```js
import { Otipi } from './otipi.js';

const otipi = new Otipi(process.env.OTIPI_KEY);

// Код входа: отправляем, потом проверяем, что ввёл человек
await otipi.otp.send({ to: '+972501234567', app: 'MyApp' });
const { valid } = await otipi.otp.verify({ to: '+972501234567', code: '482917' });

// Обычное сообщение
const message = await otipi.send({
  channel: 'sms',
  to: '+972501234567',
  text: 'Ваш заказ уже в пути.',
});

// Что с сообщением
const { status } = await otipi.messages.get(message.id);
```

Если API вернул ошибку, библиотека бросит `OtipiError` с полями `code` и `status`. Без библиотеки всё работает так же, через `fetch` или `curl`: примеры ниже.

## Как отправить сообщение

`POST /v1/messages`

| Поле | Что писать |
| --- | --- |
| `channel` | email, sms или whatsapp. Обязательно. |
| `to` | Адрес почты или израильский мобильный номер, например +972501234567. Обязательно. |
| `from` | Для писем: адрес на подтверждённом домене. Для SMS: одобренное имя отправителя. Не укажете, возьмём первое одобренное имя. |
| `subject` | Тема письма. Для писем обязательна, если нет шаблона. |
| `text` | Текст сообщения. |
| `html` | Письмо в HTML. Не пришлёте, соберём сами из текста, справа налево там, где нужно. |
| `template` | Название шаблона, вместо text. |
| `variables` | Что подставить в шаблон. |
| `language` | he, ar, ru или en, для готовых шаблонов. Если не указать, будет he. |

Пример на Node.js:

```js
const response = await fetch('https://otipi.co.il/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OTIPI_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channel: 'email',
    from: 'MyApp <hello@myapp.co.il>',
    to: 'dana@example.com',
    subject: 'Добро пожаловать',
    text: 'Здравствуйте, Дана! Ваш аккаунт готов.',
  }),
});
const message = await response.json();
```

Чтобы при повторе запроса сообщение не ушло дважды, добавьте заголовок `Idempotency-Key` со своим значением. Повторный запрос с тем же значением просто вернёт первое сообщение.

## Что с сообщением

`GET /v1/messages/:id` покажет сообщение и всё, что с ним было. `GET /v1/messages` покажет последние; отобрать их можно через `limit`, `channel` и `status`.

| Статус | Что значит |
| --- | --- |
| `queued` | Приняли, скоро отправим. |
| `sent` | Передали оператору связи. |
| `delivered` | Дошло до получателя. |
| `opened` | Письмо открыли. |
| `failed` | Отправить не получилось. Причина в поле error. |
| `bounced` | Письмо вернулось: такого адреса нет, или он не принял письмо. |

## Коды входа

Всего два запроса: первый отправляет код, второй проверяет, что ввёл человек. Код придумываем и храним мы, попытки тоже считаем мы.

```bash
# 1. Отправляем код
curl https://otipi.co.il/v1/otp/send \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "+972501234567", "app": "MyApp" }'

# 2. Проверяем, что ввёл человек
curl https://otipi.co.il/v1/otp/verify \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "to": "+972501234567", "code": "482917" }'
```

В `/v1/otp/send` можно добавить `channel` (sms, whatsapp или email), `language` (he, ar, ru или en), `length` (от 4 до 8 цифр) и `ttl_minutes` (сколько минут действует код, до 30). В ответ придёт `{ "id": "otp_...", "status": "pending", ... }`. `/v1/otp/verify` отвечает `{ "valid": true }` или `{ "valid": false, "reason": "wrong_code" }`.

Код действует 5 минут, ввести его можно 5 раз. Одному человеку уходит не больше 5 кодов в час.

В WhatsApp текст всегда один и тот же: код из 6 цифр, действует 5 минут, на иврите или английском. Другие сообщения в WhatsApp пока отправлять нельзя.

## Шаблоны

В каждом аккаунте есть три готовых шаблона, на иврите, арабском, русском и английском:

| Название | Что подставляется |
| --- | --- |
| `login-code` | code, app, minutes |
| `order-confirmed` | name, order, app |
| `receipt` | name, amount, app |

Свои шаблоны создаются в кабинете. Место для значения пишется так: `{{name}}`.

## Webhooks

Добавьте в кабинете адрес на своём сервере, и при каждой смене статуса мы будем присылать туда запрос POST: `message.sent`, `message.delivered`, `message.opened`, `message.failed`, `message.bounced`.

```json
{
  "id": "evt_Hc91VdKq2mZx8LpT4rNb",
  "type": "message.delivered",
  "created_at": "2026-11-10T08:15:04.000Z",
  "data": { "id": "msg_7Qk2LxWb9RtY3nPd5sAe", "channel": "sms", "to": "+972501234567", "status": "delivered" }
}
```

Ответьте кодом 2xx в течение 8 секунд. Не ответите, попробуем ещё раз через 10 секунд и через минуту.

В каждом запросе есть заголовок `Otipi-Signature`. С библиотекой его проверка занимает одну строку:

```js
// body: тело запроса как пришло, до JSON.parse
if (!Otipi.verifyWebhook(body, request.headers['otipi-signature'], secret)) {
  return response.writeHead(400).end();
}
```

А без библиотеки вот так:

```js
import crypto from 'node:crypto';

// body: тело запроса как пришло, до JSON.parse
function isFromOtipi(body, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((part) => part.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
```

## Тестовый режим

С тестовым ключом никому ничего не уходит, но в журнале сообщения выглядят как настоящие. Что с ними будет, зависит от получателя:

| Получатель | Что будет |
| --- | --- |
| `+972500000000` | SMS не отправится. |
| `bounce@example.com` | Письмо вернётся. Подойдёт любой адрес, который начинается на bounce. |
| `open@example.com` | Письмо дойдёт, а потом его «откроют». Подойдёт любой адрес, который начинается на open. |
| Любой другой | Сообщение дойдёт. |

В тестовом режиме `/v1/otp/send` возвращает и сам код, в поле `test_code`. В день можно отправить до 500 тестовых сообщений.

## Ошибки и ограничения

При ошибке приходит подходящий код HTTP и такой ответ: `{ "error": { "code": "invalid_recipient", "message": "..." } }`.

| Код | Что случилось |
| --- | --- |
| `unauthorized` | Нет ключа, ключ неверный или удалён. |
| `invalid_recipient` | Получатель не подходит для этого канала. SMS и WhatsApp пока уходят только на израильские номера. |
| `missing_variables` | Не хватает значений для шаблона. |
| `domain_not_verified` | Адрес отправителя на домене, который ещё не подтверждён. |
| `identity_not_verified` | Чтобы отправлять настоящие SMS, нужно один раз подтвердить личность. |
| `live_unavailable` | В этом канале настоящая отправка ещё не включена. |
| `whatsapp_codes_only` | С рабочим ключом в WhatsApp уходят только коды входа. Используйте `/v1/otp/send`. |
| `rate_limited` | Больше 600 запросов в минуту с одного ключа. |
| `monthly_limit_reached` | Письма по тарифу на этот месяц закончились. |

## Для ИИ-инструментов

Собираете приложение в Lovable, Cursor, Base44, Supabase или другом ИИ-инструменте? Вот готовые инструкции и текст, который можно просто скопировать.

### Supabase Auth (Send SMS Hook)

В Supabase откройте `Auth -> Hooks -> Send SMS Hook`, выберите HTTP Request, вставьте адрес `https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto` и добавьте заголовок `Authorization: Bearer sk_live_...` (или секрет Standard Webhooks). Otipi пришлёт код входа в WhatsApp, а если не получится, то по SMS.

### Lovable и Cursor

Скопируйте этот текст в Lovable или Cursor: он объяснит, как сделать вход по телефону и отправку писем через Otipi.

```text
Add Otipi to this project. Otipi is an API for login codes, SMS and email to recipients in Israel.

Rules:
- Call Otipi from server code only (an API route, a server action or an edge function). The key is a secret: read it from the environment variable OTIPI_KEY and never send it to the browser.
- Base URL: https://otipi.co.il/v1. Every request carries the header "Authorization: Bearer <key>" and a JSON body.
- A key that starts with sk_test_ delivers nothing and returns the code in "test_code". Use it while building.

Phone login in two calls:
1. POST /v1/otp/send {"to": "+972501234567", "app": "<the name of this app>"} -> 201 {"id", "status": "pending", "expires_at"}
   Optional: "channel": "sms" | "whatsapp" | "email" | "auto", "language": "he" | "ar" | "ru" | "en".
2. POST /v1/otp/verify {"to": "+972501234567", "code": "<what the person typed>"} -> {"valid": true} or {"valid": false, "reason": "wrong_code" | "expired_or_missing" | "too_many_attempts"}
   Sign the person in only when "valid" is true.

Supabase Auth (Send SMS Hook):
- In Supabase Dashboard -> Auth -> Hooks -> Send SMS Hook, set URL to https://otipi.co.il/v1/integrations/supabase-sms-hook?channel=auto with Authorization: Bearer <key> (or Standard Webhooks secret).

Base44:
- Connect using OpenAPI specification at https://otipi.co.il/openapi.json (https://otipi.co.il/openapi.json).

Other messages: POST /v1/messages {"channel": "sms" | "email", "to": "...", "text": "..."} -> 202 {"id", "status": "queued"}. An email also needs "subject" and, with a live key, "from" on a verified domain.

Phone numbers are Israeli mobiles written as +9725XXXXXXXX. An error comes as {"error": {"code", "message"}} with a fitting HTTP status: show the person a short message and log the code.

Full reference: https://otipi.co.il/llms-full.txt
OpenAPI: https://otipi.co.il/openapi.json
```

### Base44

В Base44 добавьте внешний API по описанию OpenAPI: адрес `https://otipi.co.il/openapi.json`, ключ `Bearer sk_live_...`.

Та же документация обычным текстом, чтобы ИИ-инструменты могли прочитать её сами:

- [llms.txt](https://otipi.co.il/llms.txt)
- [llms-full.txt](https://otipi.co.il/llms-full.txt)
- [openapi.json](https://otipi.co.il/openapi.json)
- [docs.md](https://otipi.co.il/ru/docs.md)
