> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# واجهة برمجة تطبيقات AgencyHandy: المصادقة والبدء السريع

> أنشئ مفتاح API، وابحث عن معرّف الشركة، وابدأ ببناء التكاملات مع واجهة برمجة تطبيقات AgencyHandy REST من خلال دليل الإعداد السريع هذا.

تتيح لك واجهة برمجة تطبيقات AgencyHandy أتمتة إنشاء العملاء المحتملين (leads) وإدارة العملاء وتحديثات الطلبات والمزيد من أي نظام خارجي أو سكريبت. كل طلب تتم مصادقته بمفتاح API تقوم بإنشائه من إعدادات مساحة العمل. يرشدك هذا الدليل خلال الحصول على بيانات اعتمادك وإجراء أول استدعاء لواجهة API.

<Note>
  يجب أن تكون **مشرفًا عامًا (SuperAdmin)** أو **مشرفًا (Admin)** في مساحة عمل AgencyHandy لإنشاء مفتاح API.
</Note>

## عنوان URL الأساسي

جميع طلبات API ترسَل إلى:

```
https://api.agencyhandy.com
```

استبدل `{{URL}}` بعنوان URL الأساسي هذا في جميع أمثلة الطلبات عبر وثائق API.

## الخطوة 1: إنشاء مفتاح API

<Steps>
  <Step title="فتح تكوين مساحة العمل">
    انتقل إلى إعدادات مساحة العمل على:

    ```
    {{workspaceUrl}}/workspace-config?tab=api-key
    ```

    يفتح هذا تبويب **مفتاح API** داخل تكوين مساحة العمل.
  </Step>

  <Step title="إنشاء مفتاح API ونسخه">
    انقر على **إنشاء** (أو **إعادة الإنشاء** إذا كان مفتاح موجودًا بالفعل). انسخ مفتاح API واحتفظ به بأمان — عامله ككلمة مرور. لن تعرضه AgencyHandy مرة أخرى بعد مغادرة الصفحة.
  </Step>
</Steps>

<Warning>
  يؤدي إعادة إنشاء مفتاح API إلى إبطال المفتاح السابق فورًا. ستتوقف أي تكاملات موجودة تستخدم المفتاح القديم حتى تقوم بتحديثها بالمفتاح الجديد.
</Warning>

## الخطوة 2: استرداد معرّف الشركة

تتطلب معظم نقاط نهاية API ترويسة `companyid` تُحدد مساحة العمل التي يستهدفها الطلب. استخدم النقطة النهائية التالية لجلب معرّف الشركة.

### النقطة النهائية

```
GET {{URL}}/accounts/companies
```

### الترويسات

| الترويسة    | القيمة             |
| ----------- | ------------------ |
| `x-api-key` | مفتاح API الخاص بك |

### مثال على الطلب

```bash cURL theme={null}
curl --request GET "https://api.agencyhandy.com/accounts/companies" \
  --header "x-api-key: <YOUR_API_KEY>"
```

### مثال على الاستجابة

```json theme={null}
{
  "message": "Companies associated with API token.",
  "companies": [
    {
      "_id": "6525994184e9ddd79853450e",
      "name": "onethread123",
      "logo": "",
      "extraSmallLogo": "",
      "largeLogo": ""
    }
  ]
}
```

<Steps>
  <Step title="تحديد موقع معرّف الشركة">
    في الاستجابة، ابحث عن حقل `_id` داخل مصفوفة `companies`. هذا هو **معرّف الشركة**.

    ```javascript theme={null}
    const companyId = response.companies[0]._id;
    // e.g. "6525994184e9ddd79853450e"
    ```
  </Step>

  <Step title="تخزين معرّف الشركة">
    احفظ معرّف الشركة لاستخدامه في جميع طلبات API اللاحقة. ستمرره كترويسة `companyid`:

    | الترويسة    | القيمة                |
    | ----------- | --------------------- |
    | `x-api-key` | مفتاح API الخاص بك    |
    | `companyid` | معرّف الشركة الخاص بك |
  </Step>
</Steps>

## ملخص المصادقة

كل طلب API مُصادَق يتطلب على الأقل:

```
x-api-key: <YOUR_API_KEY>
companyid: <YOUR_COMPANY_ID>
```

مع مفتاح API ومعرّف الشركة في متناولك، أنت جاهز لاستخدام بقية واجهة برمجة تطبيقات AgencyHandy. تابع إلى أحد أدلة نقاط النهاية أدناه.