واجهة marv.Inbox للمطورين

ما الذي يمكنك بناؤه

عنوان الأساس والوصول

الواجهة فعّالة في الإنتاج اليوم. لا تحتاج إلى ترقية أو حساب مطورين منفصل.

عنوان الأساس

https://api.marvinbox.com

الحصول على بيانات الاعتماد

سجّل الدخول إلى app.marvinbox.com وافتح الإعدادات، المطورون. أنشئ integration client للحصول على client id و client secret للواجهة، وسجّل webhook endpoint لاستقبال الأحداث. تتطلب إدارة الاثنين دور مشرف مساحة العمل.

بداية سريعة

ثلاث خطوات من الصفر إلى أول طلب موثّق.

1. 1

   أنشئ integration client

   من الإعدادات، المطورون، Integration clients، أنشئ client واختر الـ scopes التي يحتاجها. انسخ client id و client secret. يظهر الـ secret مرة واحدة فقط.

2. 2

   بدّل بيانات الاعتماد برمز وصول

   استدعِ نقطة نهاية الرمز بـ client id و secret. ستحصل على bearer token قصير العمر، صالح لساعة واحدة.

3. 3

   استدعِ الواجهة

   أرسل الرمز في ترويسة 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 التي يحتاجها فقط. تذكر كل نقطة نهاية أدناه الـ 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 يصف المشكلة.

الأسئلة الشائعة