# دليل المطوّرين · 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/ar/docs.md)
