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

## לכלי 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.

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

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

- [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/he/docs.md)
