جهات الاتصال

أبقِ جهات الاتصال والوسوم والحقول المخصصة متزامنة مع أنظمتك.

أبقِ جهات اتصال مساحة العمل متزامنة مع نظام CRM أو متجرك أو نظام ERP لديك: ادفع التغييرات لحظة حدوثها عبر upsert، واعرف بالتغييرات التي تُجرى هنا عبر أحداث contact.*.

كيف يعمل: مزامنة جهات الاتصالرقم واحد يعني جهة اتصال واحدة · ادفع التغييرات عبر upsert · الوسوم والحقول المخصصة · الموافقة · اعرف بالتغييرات التي تُجرى هنا · اللحاق بما فاتك · احذف جهة اتصال

رقم واحد يعني جهة اتصال واحدة#

تُعرَّف جهة الاتصال برقم هاتفها. أرسله بأي صيغة شائعة (+966 50 123 4567 أو 00966501234567 أو 0501234567)، ويُحفظ ويُعاد بصيغة E.164 (+966501234567). يُرفض إنشاء جهة اتصال ثانية بالرقم نفسه بالخطأ resource_exists، ويوضح existing_id جهة الاتصال الموجودة.

ادفع التغييرات عبر upsert#

يبحث POST /contacts/upsert عن جهة الاتصال برقم الهاتف ويغيّر الحقول المرسلة فقط، أو ينشئها. يرد بـ 201 عند الإنشاء و200 عند التحديث، فيغطي طلب واحد حالتي "عميل جديد" و"عميل تغيّرت بياناته":

JSON

{
  "phone": "0501234567",
  "first_name": "سارة",
  "email": "sara@example.com",
  "language": "ar",
  "tags": ["عملاء VIP"],
  "fields": { "loyalty_points": 180, "branch": "riyadh" }
}

أرسل Idempotency-Key أيضًا: فلا يُطبَّق upsert المعاد مرتين أبدًا.

الوسوم والحقول المخصصة#

الوسوم تقبل المعرّفات (tag_…) أو الأسماء، ويُنشأ الاسم غير الموجود. في upsert أو PATCH يستبدل tags وسوم جهة الاتصال كاملة. للإضافة دون حذف استخدم POST /contacts/{id}/tags، ولإزالة وسم واحد DELETE /contacts/{id}/tags/{tag}.
الحقول المخصصة تُرسل في fields بالمفاتيح الواردة من GET /contact_fields. تُفحص القيم حسب الحقل: رقم، أو تاريخ بصيغة YYYY-MM-DD، أو أحد خيارات القائمة. القيمة الفارغة تمسح الحقل، وتعود القيم نصية.

يوضح opted_in هل تقبل جهة الاتصال رسائل الأعمال.

إلغاء الاشتراك. إرسال PATCH بالقيمة "opted_in": false يعمل كرسالة "إيقاف" من العميل: تُلغى رسائل الحملات المجدولة له، وتحتاج القوالب المرسلة إليه بعدها إلى consent_confirmed.
إعادة الاشتراك تحتاج سجلًا بكيفية موافقته: "opted_in": true, "consent": {"source": "paper_form"}. المصادر هي website_form وpaper_form وexisting_customer وwhatsapp_conversation، أو other مع note.
يستطيع العملاء أيضًا إلغاء الاشتراك وإعادته بأنفسهم عبر رسالة (انظر العربية والسوق السعودي)، ويصلك ذلك عبر contact.opted_out وcontact.opted_in.

اعرف بالتغييرات التي تُجرى هنا#

اشترك بنقطة استقبال في contact.* ليبقى نظامك محدّثًا بالتغييرات القادمة من المنصة والاستيراد والتدفقات والواجهة البرمجية:

الحدث	متى
`contact.created`	أُضيفت جهة اتصال
`contact.updated`	تغيّرت البيانات أو الوسوم أو الحقول
`contact.opted_out` و`contact.opted_in`	تغيّرت الموافقة
`contact.deleted`	حُذفت جهة الاتصال، فاحذف نسختك

تنتظر أحداث جهات الاتصال بضع ثوانٍ لتحمل جهة الاتصال مكتملة (تُكتب وسوم جهة الاتصال الجديدة وحقولها بعد إنشائها مباشرة)، وتصل عدة تغييرات سريعة كحدث contact.updated واحد. يكون data.object دائمًا جهة الاتصال كاملة، فطبّقه كلقطة كاملة لا كفرق.

اللحاق بما فاتك#

إن توقف نظامك، اعرض ما تغيّر منذ آخر مزامنة عبر GET /contacts?updated_since=2026-10-01T00:00:00Z وتنقّل بين الصفحات بـ cursor. أما الحذف فلا يُبلَّغ عنه إلا بأحداث contact.deleted، التي تستمر إعادة محاولتها وفق الجدول المعتاد ويمكن إعادة إرسالها من سجل التسليم.

احذف جهة اتصال#

يحذف DELETE /contacts/{id} جهة الاتصال ووسومها وقيم حقولها، ويلغي رسائل الحملات التي ما زالت مجدولة لها: وهو الرد على طلب حذف البيانات. يبقى سجل محادثاتها في صندوق الوارد.

نقاط الواجهة

getعرض الحقول المخصصة/contact_fields
getعرض جهات الاتصال/contacts
postإنشاء جهة اتصال/contacts
postإنشاء أو تحديث جهة اتصال برقم الهاتف/contacts/upsert
getجلب جهة اتصال/contacts/{id}
patchتحديث جهة اتصال/contacts/{id}
DELحذف جهة اتصال/contacts/{id}
postإضافة وسوم لجهة اتصال/contacts/{id}/tags
DELإزالة وسم من جهة اتصال/contacts/{id}/tags/{tag}
getعرض الوسوم/tags
postإنشاء وسم/tags
patchإعادة تسمية وسم/tags/{id}
DELحذف وسم/tags/{id}

عرض الحقول المخصصة

gethttps://api.saei.automize.sa/v1/contact_fields

الصلاحية: contacts:read
يعمل في وضع الاختبار

الحقول المخصصة لجهات الاتصال (تُنشأ من جهات الاتصال ← الحقول). استخدم key لكل حقل داخل fields لجهة الاتصال.

حقول الاستجابة200· كل الحقول المخصصة بترتيبها في المنصة.

object"list"مطلوب
dataarray<ContactField>مطلوب
الحقول الفرعية (7)
- idstringمطلوب
- object"contact_field"مطلوب
- keystringمطلوب
- labelstringمطلوب
- typestringمطلوب
  إحدى القيمtextnumberdateselect
- optionsarray | nullاختياري
  القيم المسموح بها لحقل من نوع select.
- requiredbooleanمطلوب
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة1

429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/contact_fields \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

كل الحقول المخصصة بترتيبها في المنصة.

{
  "object": "list",
  "data": [
    {
      "id": "fld_4",
      "object": "contact_field",
      "key": "city_branch",
      "label": "الفرع",
      "type": "select",
      "options": [
        "الرياض",
        "جدة"
      ],
      "required": false
    },
    {
      "id": "fld_5",
      "object": "contact_field",
      "key": "loyalty_points",
      "label": "نقاط الولاء",
      "type": "number",
      "options": null,
      "required": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

عرض جهات الاتصال

gethttps://api.saei.automize.sa/v1/contacts

الصلاحية: contacts:read
لمفاتيح التشغيل فقط

جهات اتصال واتساب، الأحدث أولًا. ابحث عن شخص واحد بـ phone (بأي صيغة: +966 50 123 4567 أو 0501234567…)، أو زامن التغييرات بـ updated_since.

معاملات الاستعلام

limitintegerاختياري
عدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياري
قيمة next_cursor من الصفحة السابقة.
phonestringاختياري
emailstringاختياري
tagstringاختياري
معرّف وسم (tag_…) أو اسمه.
opted_inbooleanاختياري
updated_sincestringاختياري
فقط جهات الاتصال التي تغيّرت في هذا الوقت أو بعده (ISO 8601).

حقول الاستجابة200· صفحة من جهات الاتصال.

object"list"مطلوب
dataarray<Contact>مطلوب
الحقول الفرعية (20)
- idstringمطلوب
- object"contact"مطلوب
- phonestring | nullمطلوب
- emailstring | nullاختياري
- first_namestring | nullاختياري
- last_namestring | nullاختياري
- languagestring | nullاختياري
  اللغة التي يفضّلها، مثل ar أو en.
- countrystring | nullاختياري
- citystring | nullاختياري
- genderstring | nullاختياري
- birth_datestring | nullاختياري
- notesstring | nullاختياري
- opted_inbooleanمطلوب
  تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
- consentobject | nullاختياري
  كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
  الحقول الفرعية (3)
  sourcestringاختياري
  notestringاختياري
  captured_atstringاختياري
- opted_out_atstring | nullاختياري
- bot_enabledbooleanاختياري
  هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
- tagsarray<object>مطلوب
  الحقول الفرعية (2)
  idstringاختياري
  namestringاختياري
- fieldsobjectمطلوب
  قيم الحقول المخصصة حسب المفتاح. القيم نصية.
- created_atstring | nullاختياري
- updated_atstring | nullاختياري
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_invalidحقل غير صالح
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/contacts \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

صفحة من جهات الاتصال.

{
  "object": "list",
  "data": [
    {
      "id": "ct_1052",
      "object": "contact",
      "phone": "+966501234567",
      "email": "string",
      "first_name": "string",
      "last_name": "string",
      "language": "string",
      "country": "string",
      "city": "string",
      "gender": "string",
      "birth_date": "string",
      "notes": "string",
      "opted_in": false,
      "consent": {
        "source": "string",
        "note": "string",
        "captured_at": "2026-10-01T09:30:00Z"
      },
      "opted_out_at": "2026-10-01T09:30:00Z",
      "bot_enabled": false,
      "tags": [
        {
          "id": "string",
          "name": "string"
        }
      ],
      "fields": {},
      "created_at": "2026-10-01T09:30:00Z",
      "updated_at": "2026-10-01T09:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": "string"
}

إنشاء جهة اتصال

posthttps://api.saei.automize.sa/v1/contacts

الصلاحية: contacts:write
لمفاتيح التشغيل فقط
يقبل Idempotency-Key

رقم الهاتف الواحد يعني جهة اتصال واحدة: إن كان الرقم موجودًا فالرد هو resource_exists مع existing_id. للإنشاء أو التحديث في طلب واحد استخدم POST /v1/contacts/upsert.

يقبل tags معرّفات الوسوم أو أسماءها، ويُنشأ الاسم غير الموجود. ويقبل fields قيم الحقول المخصصة حسب key (انظر GET /v1/contact_fields).

الترويسات

Idempotency-Keystringاختياري
أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

phonestringاختياري
بأي صيغة، ويُحفظ بصيغة E.164. تُفهم الأرقام السعودية المكتوبة محليًا (0501234567).
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
إحدى القيمmalefemaleotherprefer_not_to_saynull
birth_datestring | nullاختياري
notesstring | nullاختياري
bot_enabledbooleanاختياري
tagsarray<string>اختياري
معرّفات الوسوم (tag_…) أو أسماؤها. يُنشأ الاسم غير الموجود.
fieldsobjectاختياري
قيم الحقول المخصصة حسب المفتاح، وتُفحص حسب نوع الحقل (رقم، أو تاريخ بصيغة YYYY-MM-DD، أو أحد خيارات القائمة).
opted_inbooleanاختياري
consentobjectاختياري
كيف وافق: website_form أو paper_form أو existing_customer أو whatsapp_conversation أو other مع note.
الحقول الفرعية (2)
- sourcestringمطلوب
  إحدى القيمwebsite_formpaper_formexisting_customerwhatsapp_conversationother
- notestringاختياري

حقول الاستجابة201· تم الإنشاء.

idstringمطلوب
object"contact"مطلوب
phonestring | nullمطلوب
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
اللغة التي يفضّلها، مثل ar أو en.
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
birth_datestring | nullاختياري
notesstring | nullاختياري
opted_inbooleanمطلوب
تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
consentobject | nullاختياري
كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
الحقول الفرعية (3)
- sourcestringاختياري
- notestringاختياري
- captured_atstringاختياري
opted_out_atstring | nullاختياري
bot_enabledbooleanاختياري
هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
tagsarray<object>مطلوب
الحقول الفرعية (2)
- idstringاختياري
- namestringاختياري
fieldsobjectمطلوب
قيم الحقول المخصصة حسب المفتاح. القيم نصية.
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة7

402quota_exceededنفد الرصيد المتاح
403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
422parameter_invalidحقل غير صالح
404resource_missingغير موجود
409resource_existsموجود مسبقًا
429rate_limitedطلبات كثيرة

جرّبها

curl -X POST https://api.saei.automize.sa/v1/contacts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "+966501234567",
  "first_name": "سارة",
  "last_name": "القحطاني",
  "email": "sara@example.com",
  "language": "ar",
  "tags": [
    "عملاء VIP"
  ],
  "fields": {
    "loyalty_points": 120
  },
  "consent": {
    "source": "website_form"
  }
}'

الاستجابة

تم الإنشاء.

{
  "id": "ct_1052",
  "object": "contact",
  "phone": "+966501234567",
  "email": "sara@example.com",
  "first_name": "سارة",
  "last_name": "القحطاني",
  "language": "ar",
  "country": null,
  "city": null,
  "gender": null,
  "birth_date": null,
  "notes": null,
  "opted_in": true,
  "consent": {
    "source": "website_form",
    "captured_at": "2026-10-01T10:02:00Z"
  },
  "opted_out_at": null,
  "bot_enabled": true,
  "tags": [
    {
      "id": "tag_12",
      "name": "عملاء VIP"
    }
  ],
  "fields": {
    "loyalty_points": "120"
  },
  "created_at": "2026-10-01T10:02:00Z",
  "updated_at": "2026-10-01T10:02:00Z"
}

إنشاء أو تحديث جهة اتصال برقم الهاتف

posthttps://api.saei.automize.sa/v1/contacts/upsert

الصلاحية: contacts:write
لمفاتيح التشغيل فقط
يقبل Idempotency-Key

الطلب المناسب لإبقاء نظام CRM لديك ومساحة العمل متزامنين. يبحث عن جهة الاتصال بـ phone (بأي صيغة) ويحدّث الحقول المرسلة، أو ينشئها. 201 عند الإنشاء و200 عند التحديث.

الترويسات

Idempotency-Keystringاختياري
أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

phonestringاختياري
بأي صيغة، ويُحفظ بصيغة E.164. تُفهم الأرقام السعودية المكتوبة محليًا (0501234567).
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
إحدى القيمmalefemaleotherprefer_not_to_saynull
birth_datestring | nullاختياري
notesstring | nullاختياري
bot_enabledbooleanاختياري
tagsarray<string>اختياري
معرّفات الوسوم (tag_…) أو أسماؤها. يُنشأ الاسم غير الموجود.
fieldsobjectاختياري
قيم الحقول المخصصة حسب المفتاح، وتُفحص حسب نوع الحقل (رقم، أو تاريخ بصيغة YYYY-MM-DD، أو أحد خيارات القائمة).
opted_inbooleanاختياري
consentobjectاختياري
كيف وافق: website_form أو paper_form أو existing_customer أو whatsapp_conversation أو other مع note.
الحقول الفرعية (2)
- sourcestringمطلوب
  إحدى القيمwebsite_formpaper_formexisting_customerwhatsapp_conversationother
- notestringاختياري

حقول الاستجابة200· حُدّثت جهة اتصال موجودة.

idstringمطلوب
object"contact"مطلوب
phonestring | nullمطلوب
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
اللغة التي يفضّلها، مثل ar أو en.
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
birth_datestring | nullاختياري
notesstring | nullاختياري
opted_inbooleanمطلوب
تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
consentobject | nullاختياري
كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
الحقول الفرعية (3)
- sourcestringاختياري
- notestringاختياري
- captured_atstringاختياري
opted_out_atstring | nullاختياري
bot_enabledbooleanاختياري
هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
tagsarray<object>مطلوب
الحقول الفرعية (2)
- idstringاختياري
- namestringاختياري
fieldsobjectمطلوب
قيم الحقول المخصصة حسب المفتاح. القيم نصية.
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة7

402quota_exceededنفد الرصيد المتاح
403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
422parameter_invalidحقل غير صالح
404resource_missingغير موجود
409resource_existsموجود مسبقًا
429rate_limitedطلبات كثيرة

جرّبها

curl -X POST https://api.saei.automize.sa/v1/contacts/upsert \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "phone": "0501234567",
  "first_name": "سارة",
  "fields": {
    "loyalty_points": 180
  }
}'

الاستجابة

حُدّثت جهة اتصال موجودة.

{
  "id": "ct_1052",
  "object": "contact",
  "phone": "+966501234567",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "language": "string",
  "country": "string",
  "city": "string",
  "gender": "string",
  "birth_date": "string",
  "notes": "string",
  "opted_in": false,
  "consent": {
    "source": "string",
    "note": "string",
    "captured_at": "2026-10-01T09:30:00Z"
  },
  "opted_out_at": "2026-10-01T09:30:00Z",
  "bot_enabled": false,
  "tags": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "fields": {},
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

جلب جهة اتصال

gethttps://api.saei.automize.sa/v1/contacts/{id}

الصلاحية: contacts:read
لمفاتيح التشغيل فقط

معاملات المسار

idstringمطلوب
معرّف العنصر.

حقول الاستجابة200· جهة الاتصال.

idstringمطلوب
object"contact"مطلوب
phonestring | nullمطلوب
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
اللغة التي يفضّلها، مثل ar أو en.
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
birth_datestring | nullاختياري
notesstring | nullاختياري
opted_inbooleanمطلوب
تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
consentobject | nullاختياري
كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
الحقول الفرعية (3)
- sourcestringاختياري
- notestringاختياري
- captured_atstringاختياري
opted_out_atstring | nullاختياري
bot_enabledbooleanاختياري
هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
tagsarray<object>مطلوب
الحقول الفرعية (2)
- idstringاختياري
- namestringاختياري
fieldsobjectمطلوب
قيم الحقول المخصصة حسب المفتاح. القيم نصية.
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/contacts/ct_1052 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

جهة الاتصال.

{
  "id": "ct_1052",
  "object": "contact",
  "phone": "+966501234567",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "language": "string",
  "country": "string",
  "city": "string",
  "gender": "string",
  "birth_date": "string",
  "notes": "string",
  "opted_in": false,
  "consent": {
    "source": "string",
    "note": "string",
    "captured_at": "2026-10-01T09:30:00Z"
  },
  "opted_out_at": "2026-10-01T09:30:00Z",
  "bot_enabled": false,
  "tags": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "fields": {},
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

تحديث جهة اتصال

patchhttps://api.saei.automize.sa/v1/contacts/{id}

الصلاحية: contacts:write
لمفاتيح التشغيل فقط

يغيّر الحقول المرسلة فقط. يستبدل tags قائمة الوسوم كاملة (لإضافة وسم استخدم POST /v1/contacts/{id}/tags)، ويغيّر fields المفاتيح المرسلة فقط، والقيمة الفارغة تمسح الحقل.

opted_in: false يلغي اشتراك جهة الاتصال كما تفعل رسالة "إيقاف": تُلغى رسائل الحملات المجدولة لها. وopted_in: true يحتاج إلى consent يوضح كيف وافقت.

معاملات المسار

idstringمطلوب
معرّف العنصر.

جسم الطلب

phonestringاختياري
بأي صيغة، ويُحفظ بصيغة E.164. تُفهم الأرقام السعودية المكتوبة محليًا (0501234567).
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
إحدى القيمmalefemaleotherprefer_not_to_saynull
birth_datestring | nullاختياري
notesstring | nullاختياري
bot_enabledbooleanاختياري
tagsarray<string>اختياري
معرّفات الوسوم (tag_…) أو أسماؤها. يُنشأ الاسم غير الموجود.
fieldsobjectاختياري
قيم الحقول المخصصة حسب المفتاح، وتُفحص حسب نوع الحقل (رقم، أو تاريخ بصيغة YYYY-MM-DD، أو أحد خيارات القائمة).
opted_inbooleanاختياري
consentobjectاختياري
كيف وافق: website_form أو paper_form أو existing_customer أو whatsapp_conversation أو other مع note.
الحقول الفرعية (2)
- sourcestringمطلوب
  إحدى القيمwebsite_formpaper_formexisting_customerwhatsapp_conversationother
- notestringاختياري

حقول الاستجابة200· جهة الاتصال بعد التحديث.

idstringمطلوب
object"contact"مطلوب
phonestring | nullمطلوب
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
اللغة التي يفضّلها، مثل ar أو en.
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
birth_datestring | nullاختياري
notesstring | nullاختياري
opted_inbooleanمطلوب
تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
consentobject | nullاختياري
كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
الحقول الفرعية (3)
- sourcestringاختياري
- notestringاختياري
- captured_atstringاختياري
opted_out_atstring | nullاختياري
bot_enabledbooleanاختياري
هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
tagsarray<object>مطلوب
الحقول الفرعية (2)
- idstringاختياري
- namestringاختياري
fieldsobjectمطلوب
قيم الحقول المخصصة حسب المفتاح. القيم نصية.
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة6

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
422parameter_invalidحقل غير صالح
404resource_missingغير موجود
409resource_existsموجود مسبقًا
429rate_limitedطلبات كثيرة

جرّبها

مثال

curl -X PATCH https://api.saei.automize.sa/v1/contacts/ct_1052 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "city": "جدة",
  "fields": {
    "loyalty_points": 200
  }
}'

الاستجابة

جهة الاتصال بعد التحديث.

{
  "id": "ct_1052",
  "object": "contact",
  "phone": "+966501234567",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "language": "string",
  "country": "string",
  "city": "string",
  "gender": "string",
  "birth_date": "string",
  "notes": "string",
  "opted_in": false,
  "consent": {
    "source": "string",
    "note": "string",
    "captured_at": "2026-10-01T09:30:00Z"
  },
  "opted_out_at": "2026-10-01T09:30:00Z",
  "bot_enabled": false,
  "tags": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "fields": {},
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

حذف جهة اتصال

deletehttps://api.saei.automize.sa/v1/contacts/{id}

الصلاحية: contacts:write
لمفاتيح التشغيل فقط

يحذف جهة الاتصال ووسومها وقيم حقولها المخصصة، وتُلغى رسائل الحملات المجدولة لها. يبقى سجل المحادثات في صندوق الوارد.

معاملات المسار

idstringمطلوب
معرّف العنصر.

حقول الاستجابة200· تم الحذف.

idstringمطلوب
objectstringمطلوب
deletedtrueمطلوب

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X DELETE https://api.saei.automize.sa/v1/contacts/ct_1052 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

تم الحذف.

{
  "id": "ct_1052",
  "object": "contact",
  "deleted": true
}

إضافة وسوم لجهة اتصال

posthttps://api.saei.automize.sa/v1/contacts/{id}/tags

الصلاحية: contacts:write
لمفاتيح التشغيل فقط

يضيف الوسوم (معرّفات أو أسماء، والاسم الجديد يُنشئ الوسم) مع الإبقاء على وسوم جهة الاتصال الحالية.

معاملات المسار

idstringمطلوب
معرّف العنصر.

جسم الطلب

tagsarray<string>مطلوب

حقول الاستجابة200· جهة الاتصال مع وسومها.

idstringمطلوب
object"contact"مطلوب
phonestring | nullمطلوب
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
اللغة التي يفضّلها، مثل ar أو en.
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
birth_datestring | nullاختياري
notesstring | nullاختياري
opted_inbooleanمطلوب
تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
consentobject | nullاختياري
كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
الحقول الفرعية (3)
- sourcestringاختياري
- notestringاختياري
- captured_atstringاختياري
opted_out_atstring | nullاختياري
bot_enabledbooleanاختياري
هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
tagsarray<object>مطلوب
الحقول الفرعية (2)
- idstringاختياري
- namestringاختياري
fieldsobjectمطلوب
قيم الحقول المخصصة حسب المفتاح. القيم نصية.
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة4

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X POST https://api.saei.automize.sa/v1/contacts/ct_1052/tags \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "tags": [
    "tag_12",
    "اشترى مؤخرًا"
  ]
}'

الاستجابة

جهة الاتصال مع وسومها.

{
  "id": "ct_1052",
  "object": "contact",
  "phone": "+966501234567",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "language": "string",
  "country": "string",
  "city": "string",
  "gender": "string",
  "birth_date": "string",
  "notes": "string",
  "opted_in": false,
  "consent": {
    "source": "string",
    "note": "string",
    "captured_at": "2026-10-01T09:30:00Z"
  },
  "opted_out_at": "2026-10-01T09:30:00Z",
  "bot_enabled": false,
  "tags": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "fields": {},
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

إزالة وسم من جهة اتصال

deletehttps://api.saei.automize.sa/v1/contacts/{id}/tags/{tag}

الصلاحية: contacts:write
لمفاتيح التشغيل فقط

معاملات المسار

idstringمطلوب
معرّف العنصر.
tagstringمطلوب
معرّف الوسم (tag_…) أو اسمه.

حقول الاستجابة200· جهة الاتصال بدون الوسم.

idstringمطلوب
object"contact"مطلوب
phonestring | nullمطلوب
emailstring | nullاختياري
first_namestring | nullاختياري
last_namestring | nullاختياري
languagestring | nullاختياري
اللغة التي يفضّلها، مثل ar أو en.
countrystring | nullاختياري
citystring | nullاختياري
genderstring | nullاختياري
birth_datestring | nullاختياري
notesstring | nullاختياري
opted_inbooleanمطلوب
تصبح false عند إلغاء الاشتراك (رسالة إيقاف أو المنصة أو الواجهة). تتخطاها الحملات، وتحتاج القوالب التسويقية إلى consent_confirmed.
consentobject | nullاختياري
كيف ومتى وافق على رسائل الأعمال، إن سُجّل ذلك.
الحقول الفرعية (3)
- sourcestringاختياري
- notestringاختياري
- captured_atstringاختياري
opted_out_atstring | nullاختياري
bot_enabledbooleanاختياري
هل ترد عليه الردود الآلية (التدفقات وروبوتات الذكاء الاصطناعي).
tagsarray<object>مطلوب
الحقول الفرعية (2)
- idstringاختياري
- namestringاختياري
fieldsobjectمطلوب
قيم الحقول المخصصة حسب المفتاح. القيم نصية.
created_atstring | nullاختياري
updated_atstring | nullاختياري

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X DELETE https://api.saei.automize.sa/v1/contacts/ct_1052/tags/tag_12 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

جهة الاتصال بدون الوسم.

{
  "id": "ct_1052",
  "object": "contact",
  "phone": "+966501234567",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "language": "string",
  "country": "string",
  "city": "string",
  "gender": "string",
  "birth_date": "string",
  "notes": "string",
  "opted_in": false,
  "consent": {
    "source": "string",
    "note": "string",
    "captured_at": "2026-10-01T09:30:00Z"
  },
  "opted_out_at": "2026-10-01T09:30:00Z",
  "bot_enabled": false,
  "tags": [
    {
      "id": "string",
      "name": "string"
    }
  ],
  "fields": {},
  "created_at": "2026-10-01T09:30:00Z",
  "updated_at": "2026-10-01T09:30:00Z"
}

gethttps://api.saei.automize.sa/v1/tags

الصلاحية: contacts:read
يعمل في وضع الاختبار

الوسوم التي تجمع جهات اتصالك، مع عدد جهات اتصال واتساب التي تحمل كل وسم.

معاملات الاستعلام

limitintegerاختياري
عدد العناصر المطلوبة، من 1 إلى 100.
cursorstringاختياري
قيمة next_cursor من الصفحة السابقة.
namestringاختياري
اسم الوسم بالضبط.

حقول الاستجابة200· صفحة من الوسوم.

object"list"مطلوب
dataarray<Tag>مطلوب
الحقول الفرعية (5)
- idstringمطلوب
- object"tag"مطلوب
- namestringمطلوب
- contact_countintegerاختياري
- created_atstring | nullاختياري
has_morebooleanمطلوب
next_cursorstring | nullمطلوب

الأخطاء المحتملة2

422parameter_invalidحقل غير صالح
429rate_limitedطلبات كثيرة

جرّبها

curl -X GET https://api.saei.automize.sa/v1/tags \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

صفحة من الوسوم.

{
  "object": "list",
  "data": [
    {
      "id": "tag_12",
      "object": "tag",
      "name": "عملاء VIP",
      "contact_count": 348,
      "created_at": "2026-07-01T09:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

إنشاء وسم

posthttps://api.saei.automize.sa/v1/tags

الصلاحية: contacts:write
لمفاتيح التشغيل فقط
يقبل Idempotency-Key

الترويسات

Idempotency-Keystringاختياري
أي نص فريد (يُفضّل UUID). إعادة الطلب بنفس المفتاح ونفس الجسم تُرجع الاستجابة الأولى بدل التنفيذ مرتين. يُحفظ لمدة 24 ساعة.

جسم الطلب

namestringمطلوب

حقول الاستجابة201· تم الإنشاء.

idstringمطلوب
object"tag"مطلوب
namestringمطلوب
contact_countintegerاختياري
created_atstring | nullاختياري

الأخطاء المحتملة4

403test_mode_unsupportedغير متاح في وضع الاختبار
422parameter_missingحقل مفقود
409resource_existsموجود مسبقًا
429rate_limitedطلبات كثيرة

جرّبها

curl -X POST https://api.saei.automize.sa/v1/tags \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "عملاء VIP"
}'

الاستجابة

تم الإنشاء.

{
  "id": "tag_12",
  "object": "tag",
  "name": "string",
  "contact_count": 0,
  "created_at": "2026-10-01T09:30:00Z"
}

إعادة تسمية وسم

patchhttps://api.saei.automize.sa/v1/tags/{id}

الصلاحية: contacts:write
لمفاتيح التشغيل فقط

معاملات المسار

idstringمطلوب
معرّف العنصر.

جسم الطلب

namestringمطلوب

حقول الاستجابة200· تمت إعادة التسمية.

idstringمطلوب
object"tag"مطلوب
namestringمطلوب
contact_countintegerاختياري
created_atstring | nullاختياري

الأخطاء المحتملة4

403test_mode_unsupportedغير متاح في وضع الاختبار
404resource_missingغير موجود
409resource_existsموجود مسبقًا
429rate_limitedطلبات كثيرة

جرّبها

curl -X PATCH https://api.saei.automize.sa/v1/tags/tag_12 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "عملاء ذهبيون"
}'

الاستجابة

تمت إعادة التسمية.

{
  "id": "tag_12",
  "object": "tag",
  "name": "string",
  "contact_count": 0,
  "created_at": "2026-10-01T09:30:00Z"
}

حذف وسم

deletehttps://api.saei.automize.sa/v1/tags/{id}

الصلاحية: contacts:write
لمفاتيح التشغيل فقط

يُزال الوسم من كل جهات الاتصال، وتبقى جهات الاتصال نفسها.

معاملات المسار

idstringمطلوب
معرّف العنصر.

حقول الاستجابة200· تم الحذف.

idstringمطلوب
objectstringمطلوب
deletedtrueمطلوب

الأخطاء المحتملة3

403test_mode_unsupportedغير متاح في وضع الاختبار
404resource_missingغير موجود
429rate_limitedطلبات كثيرة

جرّبها

curl -X DELETE https://api.saei.automize.sa/v1/tags/tag_12 \
  -H "Authorization: Bearer $API_KEY"

الاستجابة

تم الحذف.

{
  "id": "tag_12",
  "object": "tag",
  "deleted": true
}

رقم واحد يعني جهة اتصال واحدة#

ادفع التغييرات عبر upsert#

الوسوم والحقول المخصصة#

الموافقة#

اعرف بالتغييرات التي تُجرى هنا#

اللحاق بما فاتك#

احذف جهة اتصال#

نقاط الواجهة

عرض الحقول المخصصة#

عرض جهات الاتصال#

معاملات الاستعلام

إنشاء جهة اتصال#

الترويسات

جسم الطلب

إنشاء أو تحديث جهة اتصال برقم الهاتف#

الترويسات

جسم الطلب

جلب جهة اتصال#

معاملات المسار

تحديث جهة اتصال#

معاملات المسار

جسم الطلب

حذف جهة اتصال#

معاملات المسار

إضافة وسوم لجهة اتصال#

معاملات المسار

جسم الطلب

إزالة وسم من جهة اتصال#

معاملات المسار

عرض الوسوم#

معاملات الاستعلام

إنشاء وسم#

الترويسات

جسم الطلب

إعادة تسمية وسم#

معاملات المسار

جسم الطلب

حذف وسم#

معاملات المسار

عرض الحقول المخصصة

عرض جهات الاتصال

إنشاء جهة اتصال

إنشاء أو تحديث جهة اتصال برقم الهاتف

جلب جهة اتصال

تحديث جهة اتصال

حذف جهة اتصال

إضافة وسوم لجهة اتصال

إزالة وسم من جهة اتصال

عرض الوسوم

إنشاء وسم

إعادة تسمية وسم

حذف وسم