Otipi

دليل المطوّرين

API واحد للبريد وSMS وWhatsApp. كل الطلبات تذهب إلى https://otipi.co.il/v1، بصيغة JSON.

بداية سريعة

أنشئوا مفتاحًا في لوحة التحكم وأرسلوا طلبًا واحدًا:

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 }
  }'

يصل الجواب فورًا، حتى قبل أن تخرج الرسالة:

{
  "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، ضعوه في المشروع واستوردوه:

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

الحقلماذا تكتبون
channelemail أو sms أو whatsapp. إلزامي.
toعنوان بريد أو رقم جوال إسرائيلي، مثل ‎+972501234567. إلزامي.
fromللبريد: عنوان على نطاق مؤكَّد. لـ SMS: اسم مرسِل موافَق عليه. إذا لم تكتبوه، نستخدم أول اسم موافَق عليه.
subjectموضوع البريد. إلزامي للبريد، إلا إذا استخدمتم قالبًا.
textنص الرسالة.
htmlنسخة HTML للبريد. إذا لم ترسلوها، نبنيها بأنفسنا من النص، من اليمين إلى اليسار عند الحاجة.
templateاسم القالب، بدل text.
variablesالقيم التي تدخل في القالب.
languagehe أو ar أو ru أو en، للقوالب الجاهزة. إذا لم تكتبوها، تكون he.

مثال في Node.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 <[email protected]>',
    to: '[email protected]',
    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ارتدّ البريد: العنوان غير موجود، أو لم يقبله.

رموز الدخول

طلبان فقط: الأول يرسل الرمز، والثاني يتحقق مما كتبه المستخدم. نحن ننشئ الرمز ونحفظه ونعدّ المحاولات.

# 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-codecode, app, minutes
order-confirmedname, order, app
receiptname, amount, app

القوالب الخاصة بكم تُنشأ في لوحة التحكم. مكان القيمة يُكتب هكذا: {{name}}.

Webhooks

أضيفوا في لوحة التحكم عنوانًا على خادمكم، ومع كل تغيير في الحالة نرسل إليه طلب POST: message.sent، message.delivered، message.opened، message.failed، message.bounced.

{
  "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. مع المكتبة يتم التحقق منها بسطر واحد:

// body هو جسم الطلب كما وصل، قبل JSON.parse
if (!Otipi.verifyWebhook(body, request.headers['otipi-signature'], secret)) {
  return response.writeHead(400).end();
}

وبدون المكتبة، هكذا:

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.
[email protected]سيرتدّ البريد. يصلح أي عنوان يبدأ بـ bounce.
[email protected]سيصل البريد، ثم يُعَدّ مفتوحًا. يصلح أي عنوان يبدأ بـ 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.

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_....

دليل المطوّرين نفسه كنص عادي، كي تقرأه أدوات الذكاء الاصطناعي بنفسها: