واجهة التكاملات الخارجية v1

الحالة: عقد مستقر ومتوافق مع الإصدارات السابقة تاريخ الإصدار: 2026-08-14 بيئة التطوير: https://dev.chataman.com

هذا هو المرجع الرسمي لمفاتيح API، واختيار قناة الإرسال، وقراءة بيانات المؤسسة، وWebhooks الموقعة، وإعادة المحاولة، ومراقبة التسليم. تظل مسارات /api/* وسجلات Webhook القديمة مدعومة.

بداية سريعة

1. من أدوات المطور ← رموز الوصول أنشئ مفتاحًا، واختر أقل نطاقات لازمة، وحدد قناة افتراضية اختياريًا، ثم احفظ المفتاح الكامل فورًا. يخزن Chat Aman بصمة SHA-256 فقط ولا يعرض المفتاح كاملًا مرة أخرى.
2. اعرض القنوات ومعرفاتها وأسماءها المختصرة:

curl https://dev.chataman.com/api/v1/integrations/channels \
  -H "Authorization: Bearer $CHATAMAN_API_KEY" \
  -H "Accept: application/json"

3. أرسل عبر قناة محددة. يتطلب كل طلب كتابة v1 ترويسة Idempotency-Key جديدة للعملية المنطقية:

curl -X POST https://dev.chataman.com/api/v1/integrations/messages \
  -H "Authorization: Bearer $CHATAMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-7842-confirmation-v1" \
  -d '{
    "channel_slug": "support-telegram",
    "contact_uuid": "CONTACT_UUID",
    "message": "طلبك جاهز."
  }'

4. سجل نقطة Webhook عامة تستخدم HTTPS واحفظ signing_secret المعروض مرة واحدة عند الإنشاء أو التدوير.

المصادقة والنطاقات

أرسل Authorization: Bearer <key> في كل طلب. المفاتيح الجديدة عشوائية عالية القوة، ومربوطة بالمؤسسة، ومخزنة كبصمة، وقابلة للإلغاء وتحديد تاريخ انتهاء وقناة افتراضية. تبقى المفاتيح النصية القديمة صالحة حتى إلغائها، وتعمل المفاتيح السابقة لنظام النطاقات بصلاحية * للحفاظ على التوافق.

النطاقات المتاحة:

• channels:read
• contacts:read, contacts:write
• groups:read, groups:write
• messages:read, messages:write
• campaigns:write
• templates:read
• canned_replies:read, canned_replies:write
• users:read
• permissions:read
• events:read
• webhooks:read, webhooks:write
• flow:read, flow:write
• * لمفتاح غير مقيد عن قصد

استخدم مفتاحًا منفصلًا لكل نظام وبيئة، واحفظه في مدير أسرار، ولا تضعه في كود الواجهة، ودوّره عند الاشتباه في تسربه أو تغير المسؤول عنه.

اختيار القناة

يقبل إرسال v1 واحدًا فقط من:

• channel_id: المعرف الرقمي من نقطة القنوات.
• channel_slug: الاسم المختصر، أو UUID، أو معرف المزود، أو اسم القناة المطبع.
• عدم إرسال أي منهما: تستخدم القناة الافتراضية للمفتاح، ثم القناة الافتراضية للمؤسسة.

إرسال الحقلين معًا يعيد 422. كذلك تُرفض قناة مؤسسة أخرى أو قناة غير نشطة أو مفقودة أو غير قابلة للإرسال. تظهر قناة Snapchat الخاصة باستقبال العملاء المحتملين بالقيمة can_send_messages: false. تتضمن استجابة الإرسال القناة الفعلية، وتستخدم Webhooks الشكل نفسه لتحديد قناة المصدر.

دليل نقاط النهاية

تظل نقاط العملاء والمجموعات والردود والقوالب والحملات والتدفقات و/api/send* القديمة متاحة. يجب أن يحمل المفتاح المحدد النطاقات الصلاحية المطابقة؛ وتحتفظ المفاتيح القديمة بسلوكها السابق.

منع التكرار

تتطلب مسارات POST /api/v1/integrations/messages* ترويسة بطول 1–120 حرفًا. تكرار المفتاح نفسه مع الطلب نفسه يعيد النتيجة المحفوظة وترويسة Idempotency-Replayed: true. استخدامه مع طريقة أو مسار أو جسم مختلف يعيد 409 idempotency_conflict، وتكرار عملية لم تكتمل يعيد 409 idempotency_in_progress. تُحفظ السجلات سبعة أيام افتراضيًا.

بنية Webhook

{
  "event": "message.sent",
  "data": {
    "message_id": 9182,
    "contact_uuid": "95cc16a4-cf69-41f8-b2c4-923de17d3fc6",
    "status": "sent"
  },
  "metadata": {
    "event_id": "6e1eb478-2888-47aa-8dce-e6f830ead865",
    "event_type": "message.sent",
    "api_version": "v1",
    "occurred_at": "2026-08-14T10:45:32+00:00",
    "organization_id": 17
  },
  "channel": {
    "id": 42,
    "uuid": "dcb67374-4d88-4930-b834-86c64359745d",
    "slug": "sales-whatsapp",
    "type": "whatsapp",
    "name": "Sales WhatsApp",
    "identifier": "PROVIDER_CHANNEL_IDENTIFIER"
  }
}

تبقى event وdata للحفاظ على التوافق. استخدم metadata.event_id لمنع المعالجة المكررة. تكون channel بقيمة null فقط للحدث الذي لا يرتبط بقناة. الحقول داخل data إضافية حسب الحدث، لذلك يجب تجاهل الحقول غير المعروفة.

الدليل الكامل لأحداث Webhook

يضم v1 عدد 146 حدثًا. نقطة /webhook-events هي المرجع النهائي للنسخة المنشورة. يمكن الاشتراك باسم كامل أو * أو نمط مساحة مثل message.*.

• account: account.email_verification_requested, account.email_verified, account.password_changed, account.password_reset_requested, account.registered
• ai: ai.agent_failed, ai.cost_threshold_reached, ai.knowledge_sync_completed, ai.knowledge_sync_failed, ai.quota_exceeded, ai.quota_low
• audit: audit.recorded
• automation: automation.failed
• autoreply: autoreply.created, autoreply.deleted, autoreply.updated
• billing: billing.auto_recharge_failed, billing.credit_critical, billing.credit_depleted, billing.credit_low, billing.credit_recharged, billing.invoice_approved, billing.invoice_due, billing.invoice_generated, billing.invoice_overdue, billing.invoice_paid, billing.invoice_sent, billing.payment_failed, billing.payment_refunded, billing.payment_succeeded
• broadcast: broadcast.completed, broadcast.failed
• bulk_operation: bulk_operation.completed, bulk_operation.failed
• campaign: campaign.completed, campaign.contact_replied, campaign.failed, campaign.paused, campaign.resumed, campaign.scheduled, campaign.started
• channel: channel.connected, channel.disconnected, channel.health_degraded, channel.health_restored, channel.token_expiring
• commerce: commerce.cart_abandoned, commerce.catalog_sync_failed, commerce.order_canceled, commerce.order_created, commerce.order_fulfilled, commerce.order_paid, commerce.order_refunded, commerce.order_status_changed, commerce.payment_link_created, commerce.store_disconnected
• contact: contact.created, contact.deleted, contact.updated
• conversation: conversation.agent_mentioned, conversation.assigned, conversation.closed, conversation.created, conversation.customer_replied, conversation.reassigned, conversation.reopened, conversation.sla_breached, conversation.sla_warning, conversation.unassigned
• crm: crm.deal_assigned, crm.deal_closing_soon, crm.deal_created, crm.deal_lost, crm.deal_rotting, crm.deal_stage_changed, crm.deal_won, crm.lead_assigned, crm.lead_converted, crm.lead_created, crm.lead_stale, crm.meeting_booked, crm.meeting_canceled, crm.meeting_reminder, crm.meeting_rescheduled, crm.quote_accepted, crm.quote_expired, crm.quote_rejected, crm.quote_sent, crm.quote_viewed, crm.sequence_completed, crm.sequence_failed, crm.task_assigned, crm.task_completed, crm.task_due, crm.task_overdue
• drip_campaign: drip_campaign.completed, drip_campaign.failed
• feedback: feedback.csat_low, feedback.csat_received
• group: group.created, group.deleted, group.updated
• integration: integration.sync_failed, integration.sync_restored, integration.test
• message: message.received, message.sent, message.status.update
• organization: organization.activated, organization.suspended
• scheduled_message: scheduled_message.canceled, scheduled_message.failed, scheduled_message.sent
• security: security.api_key_created, security.api_key_revoked, security.new_login, security.two_factor_changed
• storage: storage.migration_completed, storage.migration_failed, storage.threshold_reached
• subscription: subscription.canceled, subscription.downgraded, subscription.expired, subscription.expiring, subscription.renewed, subscription.started, subscription.upgraded
• support: support.ticket_assigned, support.ticket_created, support.ticket_reopened, support.ticket_replied, support.ticket_resolved
• survey: survey.completed
• team: team.invitation_accepted, team.invitation_created, team.invitation_expired, team.member_added, team.member_removed, team.role_changed
• trial: trial.expired, trial.expiring, trial.started
• usage: usage.quota_exceeded, usage.threshold_reached
• webhook: webhook.delivery_failed, webhook.endpoint_disabled

التوقيع والتحقق

تستقبل النقاط الحديثة الترويسات X-ChatAman-Event وX-ChatAman-Delivery وX-ChatAman-Timestamp وX-ChatAman-Attempt وX-ChatAman-Signature. قيمة التوقيع هي v1=<HMAC-SHA256 hex> للبايتات:

timestamp + "." + raw_request_body

تحقق من الجسم الخام قبل تحويل JSON، وارفض توقيتًا أقدم من خمس دقائق، واستخدم مقارنة ثابتة الزمن. لا يمكن للترويسات المخصصة استبدال ترويسات التفويض أو النقل أو المحتوى أو التوقيع.

تقبل عناوين Webhook العامة التي تستخدم HTTPS والمنفذ 443 فقط. تُرفض بيانات الاعتماد داخل الرابط، وlocalhost، وعناوين IP الخاصة أو المحجوزة، والنطاقات الداخلية، وتحويل DNS إلى عنوان غير عام. أسرار التوقيع مشفرة في قاعدة البيانات. تبقى نقاط الوحدة القديمة غير موقعة حتى نقلها إلى النقاط الحديثة.

التسليم وإعادة المحاولة والمراقبة

يُحفظ التسليم قبل استدعاء الشبكة ويعالج عبر Queue. أي 2xx نجاح. تعاد أخطاء الاتصال و408 و425 و429 و5xx بعد 30 ثانية ثم 5 دقائق ثم 30 دقيقة، وبحد أقصى أربع محاولات افتراضيًا. بقية 4xx رفض دائم. تزيد الأعطال المتكررة عداد صحة النقطة وقد توقفها بعد عشر حالات فشل، ويعيد النجاح العداد إلى الصفر.

استخدم /webhook-deliveries لمراجعة معرف التسليم والحدث والنقطة وعدد المحاولات وحالة HTTP وكود الخطأ وموعد المحاولة التالية ووقت النجاح. تُحفظ سجلات التسليم 90 يومًا افتراضيًا. لا تسجل أجسام الأحداث أو مفاتيح API أو أسرار التوقيع.

الأخطاء وحدود المعدل

الحدود الافتراضية: 120 قراءة تكامل في الدقيقة، و30 عملية إرسال في الدقيقة، و10 اختبارات نقاط في الدقيقة. يمكن للبيئة تغييرها؛ اعتمد دائمًا على ترويسات الاستجابة.

الإصدارات وسجل التغييرات

يستخدم العقد إصدار المسار /api/v1/integrations وإصدار الغلاف metadata.api_version. إضافة حقول أو أحداث متوافقة لا تغير الإصدار الرئيسي. حذف أو إعادة تسمية أو تغيير معنى حقل أو خوارزمية توقيع يتطلب مسارًا رئيسيًا جديدًا أو فترة توافق موثقة.

2026-08-14 — v1

• اختيار صريح للقناة وقناة افتراضية لكل مفتاح.
• مفاتيح مخزنة كبصمة مع نطاقات وانتهاء وإلغاء وحدود معدل وتوافق المفاتيح القديمة.
• إرسال idempotent للرسائل.
• نقاط اكتشاف القنوات والرسائل والمستخدمين والصلاحيات والتدقيق.
• توحيد Webhooks الحديثة والقديمة دون تكرار التسليم للرابط نفسه.
• معرف حدث ثابت وقناة المصدر، وأسرار مشفرة، وتوقيع، وQueue، وإعادة محاولة، وسجل تسليم، وصحة النقطة، وحماية SSRF.
• توسيع الدليل ليغطي أحداث الرسائل والعملاء والمجموعات والحملات والقنوات والحسابات والمؤسسات والفرق والأمان والتدقيق والفوترة وCRM والتجارة وAI والدعم والتخزين والتشغيل.