ה-API למפתחים של marv.Inbox

מה אפשר לבנות

כתובת בסיס וגישה

ה-API פעיל בייצור כבר היום. אין צורך בשדרוג או בחשבון מפתחים נפרד.

כתובת בסיס

https://api.marvinbox.com

איך מקבלים הרשאות

התחברו ל-app.marvinbox.com ופתחו הגדרות, מפתחים. צרו integration client כדי לקבל client id ו-client secret ל-API, ורשמו webhook endpoint כדי לקבל אירועים. לניהול שניהם נדרש תפקיד מנהל סביבת עבודה.

התחלה מהירה

שלושה צעדים מאפס ועד הקריאה המאומתת הראשונה.

1. 1

   צרו integration client

   תחת הגדרות, מפתחים, Integration clients, צרו client ובחרו את ה-scopes שהוא צריך. העתיקו את ה-client id ואת ה-client secret. ה-secret מוצג פעם אחת בלבד.

2. 2

   המירו הרשאות לטוקן

   קראו ל-endpoint של הטוקן עם ה-client id וה-secret. בתגובה תקבלו bearer token קצר מועד, בתוקף לשעה.

3. 3

   קראו ל-API

   שלחו את הטוקן בכותרת Authorization בכל בקשה. הטוקן כבר מזהה את סביבת העבודה שלכם, אז אין כותרת tenant להגדיר.

curl -X POST https://api.marvinbox.com/external/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "marv_ic_live_...",
    "client_secret": "marv_cs_..."
  }'

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "customers:write messages:write"
}

curl -X POST https://api.marvinbox.com/external/v1/customers/upsert \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: <unique-key>" \
  -d '{
    "phone": "+972501234567",
    "name": "Jane Doe",
    "externalCustomerId": "crm-001"
  }'

אימות

Scopes

תנו ל-client רק את ה-scopes שהוא צריך. כל endpoint למטה מציין את ה-scope הנדרש לו.

נקודות קצה (REST)

כל נקודות הקצה נמצאות תחת כתובת הבסיס שלמעלה. בקשות כתיבה מקבלות כותרת Idempotency-Key.

Webhooks

Webhooks דוחפים אירועים לשרת שלכם ברגע שהם קורים, כך שאינכם צריכים לבצע polling.

רישום endpoint

תחת הגדרות, מפתחים, Webhooks, הוסיפו את כתובת המקלט שלכם ובחרו את האירועים הרצויים. העתיקו את ה-secret לחתימה שמוצג ביצירה. אפשר לרשום עד עשרה endpoints, להפעיל או לכבות כל אחד, ולסקור ניסיונות מסירה אחרונים באותו מסך.

איך נראית מסירה

כל אירוע הוא בקשת POST עם גוף JSON והכותרות הבאות:

POST /your-receiver HTTP/1.1
Content-Type: application/json
X-Marv-Event: message.created
X-Marv-Delivery: 7c9e6679-7425-40de-944b-e07fc1f90ae7
X-Marv-Timestamp: 2026-06-15T10:23:45.123Z
X-Marv-Signature: v1=3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d...

תגובת 2xx מסמנת מסירה מוצלחת. marv.Inbox ממתינה עד 10 שניות לתגובה שלכם ומנסה שוב פעם אחת אחרי 5 שניות בכישלון. כתובות מקלט חייבות להיות ציבוריות. כתובות פרטיות ו-loopback נדחות.

סוגי אירועים

הירשמו לכל שילוב של האירועים האלה.

אימות מסירה

כל מסירה חתומה כדי שתוכלו לסמוך שהיא הגיעה מ-marv.Inbox. החתימה מחושבת על גוף הבקשה הגולמי:

v1=HMAC-SHA256(secret, "{X-Marv-Timestamp}.{X-Marv-Delivery}.{rawBody}")

חשבו אותה מחדש מול הבייטים המדויקים שקיבלתם, לפני פענוח JSON, דחו כל מסירה שבה חותם הזמן ישן ביותר מחמש דקות, בצעו דה-דופ לפי X-Marv-Delivery, והשוו בזמן קבוע.

import { createHmac, timingSafeEqual } from 'crypto';

// marv.Inbox signs every delivery:
//   v1=HMAC-SHA256(secret, `${timestamp}.${deliveryId}.${rawBody}`)
// Verify against the EXACT raw request body, before JSON parsing.
export function verifyMarvWebhook(headers, rawBody, secret) {
  const signature  = headers['x-marv-signature'];  // "v1=<hex>"
  const timestamp  = headers['x-marv-timestamp'];   // ISO 8601
  const deliveryId = headers['x-marv-delivery'];    // UUID, dedupe on this

  // Reject anything older than 5 minutes (replay protection).
  if (Math.abs(Date.now() - Date.parse(timestamp)) > 300_000) return false;

  const expected = 'v1=' + createHmac('sha256', secret)
    .update(`${timestamp}.${deliveryId}.${rawBody}`)
    .digest('hex');

  const a = Buffer.from(signature ?? '', 'utf8');
  const b = Buffer.from(expected, 'utf8');
  return a.length === b.length && timingSafeEqual(a, b);
}

שגיאות

שגיאות משתמשות בקודי סטטוס סטנדרטיים של HTTP עם גוף JSON שמתאר את הבעיה.

שאלות נפוצות