# جهات الاتصال

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

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

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

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

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

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

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

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

## الوسوم والحقول المخصصة {#tags-fields}

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

## الموافقة {#consent}

يوضح `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`.
- يستطيع العملاء أيضًا إلغاء الاشتراك وإعادته بأنفسهم عبر رسالة (انظر [العربية والسوق السعودي](/docs/saudi#opt-out))، ويصلك ذلك عبر `contact.opted_out` و`contact.opted_in`.

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

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

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

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

## اللحاق بما فاتك {#catch-up}

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

## احذف جهة اتصال {#delete}

يحذف [`DELETE /contacts/{id}`](/docs/reference/contacts#deleteContact) جهة الاتصال ووسومها وقيم حقولها، ويلغي رسائل الحملات التي ما زالت مجدولة لها: وهو الرد على طلب حذف البيانات. يبقى سجل محادثاتها في صندوق الوارد.

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

```
GET https://api.saei.automize.sa/v1/contact_fields
```

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

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

### الاستجابة 200

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

```json
{
  "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
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`rate_limited`

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

```
GET https://api.saei.automize.sa/v1/contacts
```

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

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

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `phone` (query): 
- `email` (query): 
- `tag` (query): معرّف وسم (`tag_…`) أو اسمه.
- `opted_in` (query): 
- `updated_since` (query): فقط جهات الاتصال التي تغيّرت في هذا الوقت أو بعده (ISO 8601).

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_invalid`, `test_mode_unsupported`, `rate_limited`

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

```
POST https://api.saei.automize.sa/v1/contacts
```

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

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


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

### المعاملات

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

### الطلب

```json
{
  "phone": "+966501234567",
  "first_name": "سارة",
  "last_name": "القحطاني",
  "email": "sara@example.com",
  "language": "ar",
  "tags": [
    "عملاء VIP"
  ],
  "fields": {
    "loyalty_points": 120
  },
  "consent": {
    "source": "website_form"
  }
}
```

### الاستجابة 201

تم الإنشاء.

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 402

بلغت الباقة حدها من جهات الاتصال.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

توجد جهة اتصال بهذا الرقم أو البريد، ويوضّح `existing_id` معرّفها.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_missing`, `parameter_invalid`, `resource_exists`, `resource_missing`, `quota_exceeded`, `test_mode_unsupported`, `rate_limited`

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

```
POST https://api.saei.automize.sa/v1/contacts/upsert
```

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

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

### المعاملات

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

### الطلب

```json
{
  "phone": "0501234567",
  "first_name": "سارة",
  "fields": {
    "loyalty_points": 180
  }
}
```

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 201

أُنشئت جهة اتصال جديدة.

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_missing`, `parameter_invalid`, `resource_exists`, `resource_missing`, `quota_exceeded`, `test_mode_unsupported`, `rate_limited`

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

```
GET https://api.saei.automize.sa/v1/contacts/{id}
```



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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

جهة الاتصال.

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `test_mode_unsupported`, `rate_limited`

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

```
PATCH https://api.saei.automize.sa/v1/contacts/{id}
```

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

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


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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الطلب: تغيير البيانات

```json
{
  "city": "جدة",
  "fields": {
    "loyalty_points": 200
  }
}
```

### الطلب: إلغاء الاشتراك

```json
{
  "opted_in": false
}
```

### الطلب: إعادة الاشتراك

```json
{
  "opted_in": true,
  "consent": {
    "source": "paper_form"
  }
}
```

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_missing`, `parameter_invalid`, `resource_missing`, `resource_exists`, `test_mode_unsupported`, `rate_limited`

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

```
DELETE https://api.saei.automize.sa/v1/contacts/{id}
```

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

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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

تم الحذف.

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

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `test_mode_unsupported`, `rate_limited`

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

```
POST https://api.saei.automize.sa/v1/contacts/{id}/tags
```

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

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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الطلب

```json
{
  "tags": [
    "tag_12",
    "اشترى مؤخرًا"
  ]
}
```

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_missing`, `resource_missing`, `test_mode_unsupported`, `rate_limited`

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

```
DELETE https://api.saei.automize.sa/v1/contacts/{id}/tags/{tag}
```



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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.
- `tag` (path, مطلوب): معرّف الوسم (`tag_…`) أو اسمه.

### الاستجابة 200

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

```json
{
  "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"
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `test_mode_unsupported`, `rate_limited`

## عرض الوسوم

```
GET https://api.saei.automize.sa/v1/tags
```

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

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

### المعاملات

- `limit` (query): عدد العناصر المطلوبة، من 1 إلى 100.
- `cursor` (query): قيمة `next_cursor` من الصفحة السابقة.
- `name` (query): اسم الوسم بالضبط.

### الاستجابة 200

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

```json
{
  "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
}
```

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_invalid`, `rate_limited`

## إنشاء وسم

```
POST https://api.saei.automize.sa/v1/tags
```



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

### المعاملات

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

### الطلب

```json
{
  "name": "عملاء VIP"
}
```

### الاستجابة 201

تم الإنشاء.

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

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 409

يوجد وسم بهذا الاسم، ويوضّح `existing_id` معرّفه.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "string",
    "message": "string",
    "param": "string",
    "doc_url": "string",
    "request_id": "string",
    "details": [
      {
        "param": "string",
        "code": "string",
        "message": "string"
      }
    ],
    "channel_error": {
      "provider": "string",
      "code": 0,
      "subcode": 0,
      "title": "string",
      "message": "string"
    }
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`parameter_missing`, `resource_exists`, `test_mode_unsupported`, `rate_limited`

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

```
PATCH https://api.saei.automize.sa/v1/tags/{id}
```



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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الطلب

```json
{
  "name": "عملاء ذهبيون"
}
```

### الاستجابة 200

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

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

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 422

الطلب غير صالح. يوضّح `details` كل حقل به خطأ.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The to field is required.",
    "param": "to",
    "details": [
      {
        "param": "to",
        "code": "parameter_missing",
        "message": "The to field is required."
      }
    ],
    "doc_url": "https://app.example.com/docs/errors#parameter_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `resource_exists`, `test_mode_unsupported`, `rate_limited`

## حذف وسم

```
DELETE https://api.saei.automize.sa/v1/tags/{id}
```

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

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

### المعاملات

- `id` (path, مطلوب): معرّف العنصر.

### الاستجابة 200

تم الحذف.

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

### الاستجابة 401

مفتاح API مفقود أو غير صالح أو ملغى أو منتهي الصلاحية.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is not valid.",
    "doc_url": "https://app.example.com/docs/errors#api_key_invalid",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 403

المفتاح ينقصه صلاحية، أو الباقة لا تشمل الوصول للواجهة، أو الطلب غير متاح في هذا الوضع.

```json
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the \"messages:send\" scope. Create a key with it in Developers > API keys.",
    "required_scope": "messages:send",
    "doc_url": "https://app.example.com/docs/errors#insufficient_scope",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

### الاستجابة 404

لا يوجد عنصر بهذا المعرّف في مساحة العمل هذه (وفي هذا الوضع).

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such message: msg_999.",
    "param": "id",
    "doc_url": "https://app.example.com/docs/errors#resource_missing",
    "request_id": "req_01j9x3k2m4n5p6q7r8s9t0v1w2"
  }
}
```

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

`resource_missing`, `test_mode_unsupported`, `rate_limited`