# ساعي للمطورين

> أرسل رسائل واتساب، واستقبل الردود وتحديثات التسليم، واربط أنظمتك بواجهة برمجية واحدة. Base URL: https://api.saei.automize.sa/v1. OpenAPI 3.1: https://app.saei.automize.sa/docs/openapi.json

## الأدلة

- [البدء السريع](https://app.saei.automize.sa/docs/md/quickstart)
- [المصادقة والمفاتيح](https://app.saei.automize.sa/docs/md/authentication)
- [وضع الاختبار](https://app.saei.automize.sa/docs/md/test-mode)
- [الطلبات والاستجابات](https://app.saei.automize.sa/docs/md/conventions)
- [الانتقال للتشغيل](https://app.saei.automize.sa/docs/md/going-live)
- [العربية والسوق السعودي](https://app.saei.automize.sa/docs/md/saudi)
- [استقبال الويب هوك](https://app.saei.automize.sa/docs/md/webhooks)
- [سجل التغييرات](https://app.saei.automize.sa/docs/md/changelog)
- [الإصدارات والتغييرات](https://app.saei.automize.sa/docs/md/versioning)

## مرجع الواجهة

- [الحساب والاستهلاك](https://app.saei.automize.sa/docs/md/reference/account): تحقّق من مفتاحك وما يستطيع فعله.
  - [GET /me — تحقّق من مفتاح API](https://app.saei.automize.sa/docs/md/reference/getMe)
  - [GET /usage — جلب الاستهلاك](https://app.saei.automize.sa/docs/md/reference/getUsage)
- [الرسائل](https://app.saei.automize.sa/docs/md/reference/messages): أرسل الرسائل واقرأ حالتها.
  - [GET /messages — عرض الرسائل المرسلة عبر الواجهة](https://app.saei.automize.sa/docs/md/reference/listMessages)
  - [POST /messages — إرسال رسالة](https://app.saei.automize.sa/docs/md/reference/sendMessage)
  - [GET /messages/{id} — جلب رسالة](https://app.saei.automize.sa/docs/md/reference/getMessage)
  - [POST /messages/{id}/read — تعليم رسالة العميل كمقروءة](https://app.saei.automize.sa/docs/md/reference/markMessageRead)
- [الأرقام](https://app.saei.automize.sa/docs/md/reference/numbers): أرقام واتساب المرسِلة وحالتها.
  - [GET /numbers — عرض أرقام واتساب](https://app.saei.automize.sa/docs/md/reference/listNumbers)
  - [GET /numbers/{id} — جلب رقم](https://app.saei.automize.sa/docs/md/reference/getNumber)
- [القوالب](https://app.saei.automize.sa/docs/md/reference/templates): قوالب واتساب المعتمدة: اعرف ما يحتاجه كل قالب وأنشئ قوالب جديدة.
  - [GET /templates — عرض القوالب](https://app.saei.automize.sa/docs/md/reference/listTemplates)
  - [POST /templates — إنشاء قالب](https://app.saei.automize.sa/docs/md/reference/createTemplate)
  - [GET /templates/{id} — جلب قالب](https://app.saei.automize.sa/docs/md/reference/getTemplate)
  - [DELETE /templates/{id} — حذف قالب](https://app.saei.automize.sa/docs/md/reference/deleteTemplate)
- [الوسائط](https://app.saei.automize.sa/docs/md/reference/media): ارفع الملفات مرة واحدة وأرسلها متى شئت.
  - [GET /media — عرض الملفات](https://app.saei.automize.sa/docs/md/reference/listMedia)
  - [POST /media — رفع ملف](https://app.saei.automize.sa/docs/md/reference/uploadMedia)
  - [GET /media/{id} — جلب ملف](https://app.saei.automize.sa/docs/md/reference/getMedia)
  - [DELETE /media/{id} — حذف ملف](https://app.saei.automize.sa/docs/md/reference/deleteMedia)
- [جهات الاتصال](https://app.saei.automize.sa/docs/md/reference/contacts): أبقِ جهات الاتصال والوسوم والحقول المخصصة متزامنة مع أنظمتك.
  - [GET /contact_fields — عرض الحقول المخصصة](https://app.saei.automize.sa/docs/md/reference/listContactFields)
  - [GET /contacts — عرض جهات الاتصال](https://app.saei.automize.sa/docs/md/reference/listContacts)
  - [POST /contacts — إنشاء جهة اتصال](https://app.saei.automize.sa/docs/md/reference/createContact)
  - [POST /contacts/upsert — إنشاء أو تحديث جهة اتصال برقم الهاتف](https://app.saei.automize.sa/docs/md/reference/upsertContact)
  - [GET /contacts/{id} — جلب جهة اتصال](https://app.saei.automize.sa/docs/md/reference/getContact)
  - [PATCH /contacts/{id} — تحديث جهة اتصال](https://app.saei.automize.sa/docs/md/reference/updateContact)
  - [DELETE /contacts/{id} — حذف جهة اتصال](https://app.saei.automize.sa/docs/md/reference/deleteContact)
  - [POST /contacts/{id}/tags — إضافة وسوم لجهة اتصال](https://app.saei.automize.sa/docs/md/reference/addContactTags)
  - [DELETE /contacts/{id}/tags/{tag} — إزالة وسم من جهة اتصال](https://app.saei.automize.sa/docs/md/reference/removeContactTag)
  - [GET /tags — عرض الوسوم](https://app.saei.automize.sa/docs/md/reference/listTags)
  - [POST /tags — إنشاء وسم](https://app.saei.automize.sa/docs/md/reference/createTag)
  - [PATCH /tags/{id} — إعادة تسمية وسم](https://app.saei.automize.sa/docs/md/reference/updateTag)
  - [DELETE /tags/{id} — حذف وسم](https://app.saei.automize.sa/docs/md/reference/deleteTag)
- [المحادثات](https://app.saei.automize.sa/docs/md/reference/conversations): صندوق الوارد المشترك: اقرأ المحادثات وأسندها وأغلقها وأعد فتحها.
  - [GET /conversations — عرض المحادثات](https://app.saei.automize.sa/docs/md/reference/listConversations)
  - [GET /conversations/{id} — جلب محادثة](https://app.saei.automize.sa/docs/md/reference/getConversation)
  - [POST /conversations/{id}/assign — إسناد محادثة](https://app.saei.automize.sa/docs/md/reference/assignConversation)
  - [GET /conversations/{id}/messages — عرض رسائل محادثة](https://app.saei.automize.sa/docs/md/reference/listConversationMessages)
  - [POST /conversations/{id}/reopen — إعادة فتح محادثة](https://app.saei.automize.sa/docs/md/reference/reopenConversation)
  - [POST /conversations/{id}/resolve — إغلاق محادثة](https://app.saei.automize.sa/docs/md/reference/resolveConversation)
  - [GET /members — عرض أعضاء الفريق](https://app.saei.automize.sa/docs/md/reference/listMembers)
- [الحملات](https://app.saei.automize.sa/docs/md/reference/campaigns): أرسل قالبًا معتمدًا إلى جمهور وتابع النتائج.
  - [GET /campaigns — عرض الحملات](https://app.saei.automize.sa/docs/md/reference/listCampaigns)
  - [POST /campaigns — إنشاء حملة](https://app.saei.automize.sa/docs/md/reference/createCampaign)
  - [GET /campaigns/{id} — جلب حملة](https://app.saei.automize.sa/docs/md/reference/getCampaign)
  - [POST /campaigns/{id}/cancel — إلغاء حملة](https://app.saei.automize.sa/docs/md/reference/cancelCampaign)
  - [GET /campaigns/{id}/messages — عرض مستلمي حملة](https://app.saei.automize.sa/docs/md/reference/listCampaignMessages)
  - [POST /campaigns/{id}/resume — استئناف حملة متوقفة](https://app.saei.automize.sa/docs/md/reference/resumeCampaign)
  - [POST /campaigns/{id}/start — بدء حملة](https://app.saei.automize.sa/docs/md/reference/startCampaign)
- [التدفقات](https://app.saei.automize.sa/docs/md/reference/flows): شغّل أتمتة منشئ التدفقات لعميل.
  - [GET /flow_responses — عرض ردود نماذج واتساب](https://app.saei.automize.sa/docs/md/reference/listFlowResponses)
  - [GET /flow_runs/{id} — جلب تشغيل تدفق](https://app.saei.automize.sa/docs/md/reference/getFlowRun)
  - [GET /flows — عرض التدفقات](https://app.saei.automize.sa/docs/md/reference/listFlows)
  - [GET /flows/{id} — جلب تدفق](https://app.saei.automize.sa/docs/md/reference/getFlow)
  - [GET /flows/{id}/runs — عرض تشغيلات تدفق](https://app.saei.automize.sa/docs/md/reference/listFlowRuns)
  - [POST /flows/{id}/runs — تشغيل تدفق لعميل](https://app.saei.automize.sa/docs/md/reference/startFlowRun)
- [الويب هوك](https://app.saei.automize.sa/docs/md/reference/webhooks): استقبل الأحداث (رسائل جديدة، تحديثات التسليم) على خادمك مباشرة.
  - [GET /event_types — عرض أنواع الأحداث](https://app.saei.automize.sa/docs/md/reference/listEventTypes)
  - [POST /webhook_deliveries/{id}/retry — إعادة الإرسال الآن](https://app.saei.automize.sa/docs/md/reference/retryWebhookDelivery)
  - [GET /webhook_endpoints — عرض نقاط استقبال الويب هوك](https://app.saei.automize.sa/docs/md/reference/listWebhookEndpoints)
  - [POST /webhook_endpoints — إضافة نقطة استقبال ويب هوك](https://app.saei.automize.sa/docs/md/reference/createWebhookEndpoint)
  - [GET /webhook_endpoints/{id} — جلب نقطة استقبال](https://app.saei.automize.sa/docs/md/reference/getWebhookEndpoint)
  - [PATCH /webhook_endpoints/{id} — تعديل نقطة استقبال](https://app.saei.automize.sa/docs/md/reference/updateWebhookEndpoint)
  - [DELETE /webhook_endpoints/{id} — حذف نقطة استقبال](https://app.saei.automize.sa/docs/md/reference/deleteWebhookEndpoint)
  - [GET /webhook_endpoints/{id}/deliveries — عرض عمليات الإرسال](https://app.saei.automize.sa/docs/md/reference/listWebhookDeliveries)
  - [POST /webhook_endpoints/{id}/rotate_secret — تدوير سر التوقيع](https://app.saei.automize.sa/docs/md/reference/rotateWebhookSecret)
  - [POST /webhook_endpoints/{id}/test — إرسال حدث تجريبي](https://app.saei.automize.sa/docs/md/reference/testWebhookEndpoint)
- [وضع الاختبار](https://app.saei.automize.sa/docs/md/reference/test-mode): تحكّم في محاكي وضع الاختبار. لمفاتيح الاختبار فقط.
  - [POST /test/inbound_messages — محاكاة رسالة من عميل](https://app.saei.automize.sa/docs/md/reference/simulateInboundMessage)
  - [POST /test/messages/{id}/status — فرض حالة رسالة](https://app.saei.automize.sa/docs/md/reference/simulateMessageStatus)

## أنواع الأحداث

- `message.received`: أرسل عميل رسالة إلى أحد أرقامك. `data.object` هي الرسالة الواردة `message`.
- `message.sent`: أرسل واتساب رسالتك. `data.previous_attributes.status` هي الحالة السابقة.
- `message.delivered`: وصلت رسالتك إلى هاتف العميل.
- `message.read`: فتح العميل رسالتك. يصل فقط إذا كان العميل يشارك إشعارات القراءة.
- `message.failed`: تعذّر تسليم رسالتك. يحمل `data.object.error` رمز واتساب والسبب (مثل 131026 غير قابلة للتسليم، و131047 خارج نافذة الـ24 ساعة).
- `contact.created`: أُضيفت جهة اتصال واتساب، من المنصة أو الاستيراد أو تدفق أو الواجهة. `data.object` هي جهة الاتصال `contact` مع وسومها وحقولها المخصصة.
- `contact.updated`: تغيّرت بيانات جهة اتصال أو وسومها أو حقولها المخصصة. عدة تغييرات سريعة على جهة الاتصال نفسها تصل كحدث واحد يحمل الحالة النهائية.
- `contact.deleted`: حُذفت جهة اتصال. `data.object` هي `{id, object: "contact", deleted: true}`: حُذفت البيانات، فاحذف نسختك أيضًا.
- `contact.opted_out`: طلبت جهة اتصال إيقاف رسائل الأعمال (أرسلت "إيقاف" أو ألغى أحدهم اشتراكها). تُلغى رسائل الحملات المجدولة لها، فأوقف مراسلتها من أنظمتك أيضًا.
- `contact.opted_in`: وافقت جهة اتصال كانت قد ألغت اشتراكها على رسائل الأعمال من جديد (أرسلت "ابدأ" أو سُجّلت موافقتها). يوضّح `consent.source` كيف تمت الموافقة.
- `template.status_changed`: اعتمد واتساب أحد قوالبك أو رفضه أو أوقفه مؤقتًا أو عطّله. `data.object` هو القالب `template`، و`data.previous_attributes.status` حالته السابقة، و`rejection_reason` سبب الرفض إن ذكره واتساب.
- `campaign.started`: بدأت حملة الإرسال، أو جُدولت له. `data.object` هي الحملة `campaign`.
- `campaign.paused`: تم إيقاف حملة مؤقتًا، مثلًا لأن Meta قيّد رقم الإرسال. يوضح `hold_reason` السبب، واستأنفها عبر `POST /v1/campaigns/{id}/resume` بعد إصلاحه. `data.object` هي الحملة `campaign`.
- `campaign.resumed`: عادت حملة متوقفة إلى الإرسال. `data.object` هي الحملة `campaign`.
- `campaign.completed`: انتهت حملة: أُرسل لكل مستلم أو فشل. تحمل `stats` الأرقام النهائية. `data.object` هي الحملة `campaign`.
- `campaign.failed`: تعذّر إرسال حملة، مثلًا لأن Meta أوقف التسليم لسبب يتعلق بالفوترة. `data.object` هي الحملة `campaign`.
- `campaign.cancelled`: أُلغيت حملة، ولن تُرسل رسائلها غير المرسلة. `data.object` هي الحملة `campaign`.
- `flow.run.started`: بدأ تدفق لعميل، من الواجهة أو مشغّل أو صندوق الوارد. `data.object` هو `flow_run`.
- `flow.run.handed_off`: حوّل تدفق العميل إلى فريقك، والمحادثة تحتاج الآن إلى موظف. `data.object` هو `flow_run`.
- `flow.run.completed`: وصل تدفق إلى نهايته لعميل. تحمل `variables` كل ما جمعه. `data.object` هو `flow_run`.
- `flow.run.expired`: توقف تدفق عن انتظار عميل لم يرد في الوقت المحدد. `data.object` هو `flow_run`.
- `flow.response`: أرسل عميل نموذج واتساب (Flow). تحمل `answers` ما أدخله. `data.object` هو `flow_response`.
- `conversation.created`: بدأ عميل محادثة جديدة مع مساحة العمل. `data.object` هي المحادثة `conversation`.
- `conversation.needs_agent`: محادثة تنتظر موظفًا، لأن الروبوت حوّلها أو لأن العميل طلب ذلك. نبّه فريقك أو أسندها عبر `POST /v1/conversations/{id}/assign`.
- `conversation.assigned`: أُسندت محادثة إلى عضو في الفريق (`assignee`)، من شخص أو قاعدة أو عبر الواجهة.
- `conversation.resolved`: أُغلقت محادثة. وقت مناسب لإرسال استبيان رضا أو إغلاق التذكرة في نظام الدعم لديك.
- `conversation.reopened`: عادت محادثة مغلقة إلى النشاط، غالبًا لأن العميل كتب من جديد.
- `webhook.test`: يُرسل عند الضغط على «إرسال حدث تجريبي» (أو استدعاء نقطة الاختبار). لا يحمل بيانات عملاء.

## الأخطاء

- `api_key_missing` (401): أرسل مفتاحك في الترويسة `Authorization: Bearer sk_live_…` (أو `sk_test_…`).
- `api_key_invalid` (401): انسخ المفتاح مرة أخرى من المطورين ← مفاتيح API. تبدأ المفاتيح بـ `sk_live_` أو `sk_test_`.
- `api_key_revoked` (401): ألغى أحدهم هذا المفتاح. أنشئ مفتاحًا جديدًا من المطورين ← مفاتيح API.
- `api_key_expired` (401): تجاوز المفتاح تاريخ انتهائه. أنشئ مفتاحًا جديدًا.
- `subscription_inactive` (402): جدّد اشتراك مساحة العمل من الفوترة. تبقى عمليات القراءة متاحة خلال ذلك.
- `quota_exceeded` (402): استُهلك رصيد الباقة لهذه الفترة. قم بالترقية أو أضف إضافة من الفوترة. يوضّح `entitlement` الرصيد المقصود.
- `insufficient_scope` (403): المفتاح لا يملك الصلاحية الموجودة في `required_scope`. أنشئ مفتاحًا يملكها.
- `api_access_not_in_plan` (403): يتطلب الوصول الحي للواجهة باقة تشمله. مفاتيح الاختبار تعمل في كل الباقات.
- `workspace_suspended` (403): تواصل مع الدعم لإعادة تفعيل مساحة العمل.
- `capability_disabled` (403): هذه الميزة موقوفة لمساحة العمل. تواصل مع الدعم.
- `test_mode_unsupported` (403): هذا الطلب يعمل على بيانات عملاء حقيقية ولا توجد له نسخة محاكاة. استخدم مفتاح تشغيل، أو مساحة عمل منفصلة للتجربة.
- `invalid_json` (400): جسم الطلب ليس JSON صالحًا. راجع علامات الاقتباس والفواصل، وأرسل `Content-Type: application/json`.
- `parameter_missing` (422): يسمّي `param` الحقل المفقود، ويسرد `details` كل الحقول.
- `parameter_invalid` (422): يسمّي `param` الحقل، ويوضح `message` ما الخطأ فيه.
- `resource_missing` (404): لا يوجد عنصر بهذا المعرّف في مساحة العمل. معرّفات الاختبار (`msg_test_…`) تُقرأ بمفتاح اختبار فقط، والمعرّفات الحية بمفتاح تشغيل فقط.
- `route_not_found` (404): راجع المسار والطريقة في مرجع الواجهة. كل المسارات تبدأ بـ `/v1/`.
- `method_not_allowed` (405): الرابط موجود لكن ليس بهذه الطريقة. راجع مرجع الواجهة.
- `payload_too_large` (413): أرسل جسم طلب أصغر.
- `idempotency_key_reused` (422): المفتاح خاص بطلب واحد. استخدم Idempotency-Key جديدًا لجسم مختلف.
- `idempotency_in_progress` (409): الطلب الأول بهذا المفتاح لم ينتهِ بعد. أعد المحاولة بعد ثانية.
- `window_closed` (422): لا يسلّم واتساب الرسائل الحرة إلا خلال 24 ساعة من آخر رسالة للعميل. أرسل قالبًا معتمدًا بدلًا منها، وتُفتح المحادثة من جديد عندما يرد العميل.
- `template_not_found` (422): راجع اسم القالب ولغته، أو استخدم معرّفه `tpl_…`.
- `template_not_approved` (422): لا يُرسل إلا ما اعتمده واتساب من قوالب. انتظر اعتماده، أو أصلح سبب الرفض من صفحة القوالب.
- `template_variables_mismatch` (422): أرسل قيمة واحدة غير فارغة لكل {{n}} في `template.variables.body` وبالترتيب.
- `recipient_not_consented` (409): جهة الاتصال لم توافق على رسائل الأعمال. إن كانت موافقتها لديك في مكان آخر، أعد الإرسال مع `"consent_confirmed": true` (تُسجَّل الموافقة).
- `recipient_opted_out` (422): طلبت جهة الاتصال عدم مراسلتها. لا تُعد المحاولة.
- `sender_not_configured` (422): اربط رقم واتساب من الإعدادات ← القنوات، أو مرّر `from` صحيحًا.
- `sender_not_sendable` (422): يوضّح `reason` السبب (مثل انقطاع الربط أو انتهاء الرمز). أصلح الرقم من الإعدادات ← القنوات.
- `channel_error` (422): يحمل `channel_error` رمز واتساب ورسالته. ابحث عن الرمز في قائمة أخطاء واتساب.
- `send_outcome_unknown` (409): تلقى طلب سابق بنفس Idempotency-Key ردًّا غير واضح من واتساب. تحقق عبر `GET /v1/messages?reference=…` قبل الإرسال مرة أخرى.
- `channel_not_connected` (422): اربط القناة (أو أعد ربطها) من الإعدادات ← القنوات. يوضّح `param` الحقل الذي حدّد القناة.
- `resource_exists` (409): يوجد عنصر آخر يستخدم هذه القيمة الفريدة (رقم هاتف أو بريد أو اسم). يوضّح `existing_id` العنصر الموجود متى أمكن: حدّثه بدلًا من ذلك، أو استخدم نقطة upsert.
- `resource_in_use` (409): ما زال شيء يعتمد على هذا العنصر (حملة جارية تستخدم القالب، أو رسالة تستخدم الملف). يوضّح `details` ما هو. أنهِ ذلك أو احذفه أولًا.
- `state_conflict` (409): الإجراء لا يناسب حالة العنصر الحالية، مثل إغلاق محادثة مغلقة أصلًا أو بدء حملة بدأت. اقرأ العنصر وتحقق من `state` أو `status` ثم قرّر.
- `assignee_invalid` (422): أسند المحادثة لعضو من `GET /v1/members` يستطيع رؤية قناتها. يُرفض المشاهدون والأعضاء الذين لا يملكون صلاحية على ذلك الرقم.
- `media_invalid` (422): يضع واتساب حدودًا لكل نوع وسائط: الصور JPEG/PNG حتى 5 ميجابايت، الفيديو MP4/3GPP حتى 16 ميجابايت، الصوت حتى 16 ميجابايت، المستندات حتى 100 ميجابايت، الملصقات WebP حتى 100 كيلوبايت (500 للمتحركة). يوضّح `message` القاعدة التي لم تتحقق.
- `flow_not_triggerable` (422): لا يمكن تشغيل تدفق عبر الواجهة إلا إذا كان منشورًا ومشغّله "API / ويب هوك". انشره أو غيّر مشغّله من منشئ التدفقات.
- `webhook_url_invalid` (422): استخدم رابط https:// عامًا. العناوين الخاصة والمحلية وعناوين بيانات السحابة مرفوضة.
- `webhook_endpoint_limit` (422): احذف نقطة لم تعد تستخدمها (10 لكل مساحة عمل).
- `rate_limited` (429): انتظر عدد ثواني `Retry-After`. نظّم طلباتك بالاعتماد على ترويسات `RateLimit-*` في كل استجابة.
- `internal_error` (500): أعد المحاولة بنفس Idempotency-Key. إن استمر الخطأ تواصل مع الدعم واذكر `request_id`.
- `platform_paused` (503): الإرسال متوقف على مستوى المنصة لصيانة أو حادث. أعد المحاولة لاحقًا.
- `service_unavailable` (503): أعد المحاولة مع زيادة فترة الانتظار تدريجيًا.