واجهة REST

كل طلب يُرسل إلى https://api.inboxy.chat مع مفتاح API في ترويسة Authorization. المفتاح يحدد الشركة، ولا يوجد معرّف شركة في أي طلب.

طبقتان: عقد v1 العام (/api/v1/public/*، للقراءة فقط ومُرقَّم الإصدار) ومسارات لوحة التحكم التي يستطيع المفتاح استدعاءها بالصلاحية المناسبة. كلاهما في المرجع الحي.

1. سجّل الدخول إلى Inboxy بحساب مدير الشركة وافتح المطورون ← API keys في لوحة التحكم ‏(/developer-center/keys).
2. اختر "أنشئ مفتاح API" وسمِّ المفتاح باسم تعرفه لاحقاً (مثل "Claude على جهازي").
3. اختر الصلاحيات التي تحتاجها فقط. لا توجد صلاحيات افتراضية، ولا يمكن إنشاء مفتاح بلا صلاحيات. أدوات القراءة تحتاج صلاحيات ":read" ‏(contacts:read وorders:read ...).
4. اختر مدة الصلاحية: 30 أو 90 (الافتراضي) أو 180 أو 365 يوماً أو بلا انتهاء. الافتراضي 90 يوماً.
5. انسخ المفتاح عند ظهوره، وهو يبدأ بـ"inboxy_". احفظه في مدير أسرار أو في سلسلة مفاتيح النظام، ولا تضعه أبداً في مستودع كود.

إرسال المفتاح

أرسله كرمز Bearer، عبر HTTPS فقط.

curl https://api.inboxy.chat/api/v1/public/company \
  -H "Authorization: Bearer $INBOXY_API_KEY"

import { InboxyClient } from '@inboxychat/sdk';

const inboxy = new InboxyClient({ apiKey: process.env.INBOXY_API_KEY! });
const { data } = await inboxy.getCompany();

inboxy auth login   # approve in the browser once
inboxy whoami

Authorization: Bearer inboxy_YOUR_KEY

معلومات مهمة

• مدير الشركة فقط يستطيع إنشاء المفاتيح. يعمل المفتاح لشركته فقط، ولا يقبل أي طلب معرّف شركة.
• يمكن للشركة الاحتفاظ بـ10 مفاتيح فعالة كحد أقصى. ألغِ أي مفتاح من الصفحة نفسها.
• يعمل المفتاح باسم المدير الذي أنشأه، ويتوقف عند انتهائه أو إلغائه أو إيقاف الشركة أو إذا لم يعد منشئه مديراً.
• كل طلب ينفّذه المفتاح يظهر في صفحة المطورون ← Request logs.

تحقّق من المفتاح ثم اقرأ أحدث خمسة طلبات. ضع مفتاحك مكان المثال (واحفظه في متغير بيئة).

export INBOXY_API_KEY="inboxy_YOUR_KEY"
curl -s https://api.inboxy.chat/api/v1/public/company \
  -H "Authorization: Bearer $INBOXY_API_KEY"

curl -s "https://api.inboxy.chat/api/v1/public/orders?limit=5" \
  -H "Authorization: Bearer $INBOXY_API_KEY"

{
  "success": true,
  "data": [ { "id": "...", "orderNumber": "..." } ],
  "meta": { "limit": 5, "hasMore": true, "nextCursor": "..." }
}

التنقل بين صفحات القائمة

القوائم تستخدم المؤشرات (cursor). مرّر limit ‏(1-100، الافتراضي 20)، وما دام meta.hasMore يساوي true أرسل meta.nextCursor في المعامل cursor.

curl -s "https://api.inboxy.chat/api/v1/public/contacts?limit=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $INBOXY_API_KEY"

إرسال رسالة واتساب نصية

يحتاج messages:send ورقم واتساب مربوطاً. الرسالة النصية الحرة تُرسل فقط داخل نافذة خدمة العملاء (24 ساعة)؛ وخارجها أرسل قالباً معتمداً.

curl -s -X POST https://api.inboxy.chat/api/v1/whatsapp/messages/text \
  -H "Authorization: Bearer $INBOXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "966500000000", "body": "Your order has shipped." }'

الرد داخل محادثة

يعمل على أي قناة مربوطة. يحتاج messages:send.

curl -s -X POST https://api.inboxy.chat/api/v1/inbox/conversations/CONVERSATION_ID/messages \
  -H "Authorization: Bearer $INBOXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "text", "content": "Thanks, we are on it." }'

استقبال الـWebhooks والتحقق منها

سجّل عنوان HTTPS ‏(webhooks:write) مع الأحداث التي تريدها؛ قائمة الأحداث في https://api.inboxy.chat/api/v1/webhooks/catalog. كل تسليم يحمل X-Inboxy-Timestamp وX-Inboxy-Signature: sha256=HMAC-SHA256(secret, "<timestamp>.<raw body>"). ارفض أي تسليم أقدم من 300 ثانية.

curl -s -X POST https://api.inboxy.chat/api/v1/webhooks \
  -H "Authorization: Bearer $INBOXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Order sync", "url": "https://example.com/webhooks/inboxy", "events": ["ecommerce.order.*"] }'

import crypto from 'node:crypto';

export function verifyInboxy(rawBody, headers, secret) {
  const ts = headers['x-inboxy-timestamp'];
  const sig = headers['x-inboxy-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

الإصدار العام v1 (قراءة فقط)

كل المسارات تحت https://api.inboxy.chat/api/v1/public.

مسارات لوحة التحكم المتاحة للمفتاح (أمثلة)

القائمة الكاملة، مع جسم الطلب ومعاملات الاستعلام، في المرجع الحي ومستند OpenAPI.

• 60 طلباً في الدقيقة لكل مفتاح، إضافة إلى حد دقيقة واحد مشترك بين كل مفاتيح الشركة. ‏GET /api/v1/public/company يعيد الرقمين.
• عند تجاوز الحد يصلك الرمز 429 مع ترويسة Retry-After؛ انتظر عدد الثواني المذكور.
• حدود الباقة تنطبق على المفاتيح كما تنطبق في لوحة التحكم تماماً.
• أعطِ كل تكامل مفتاحاً خاصاً بأقل الصلاحيات ومع تاريخ انتهاء. لا تضع المفتاح أبداً في كود المتصفح أو في مستودع عام.

كل الأخطاء بصيغة واحدة: { "success": false, "error": { "code", "message", "details" } }. وأمر CLI ‏inboxy doctor يفحص المفتاح من البداية للنهاية.