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המיילים שכלולים בתוכנית נגמרו החודש.

לכלי AI

בונים עם Lovable, Cursor, Base44, Supabase או כלי AI אחר? הנה הוראות מוכנות וטקסט שאפשר פשוט להעתיק.

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

אותו תיעוד כטקסט רגיל, כדי שכלי AI יוכלו לקרוא אותו לבד: