---
title: واجهات برمجة التطبيقات
description: استعلم وعدّل بيانات إدارة علاقات العملاء (CRM) لديك برمجياً باستخدام REST أو GraphQL.
---

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

تم تصميم Twenty ليكون صديقًا للمطورين، حيث يوفر واجهات برمجة قوية تتكيف مع نموذج البيانات المخصص. نحن نوفر أربعة أنواع متميزة من واجهات برمجة التطبيقات لتلبية احتياجات التكامل المختلفة.

## نهج المطوّر أولاً

تقوم Twenty بإنشاء واجهات برمجة التطبيقات خصيصاً لنموذج بياناتك:

* **لا حاجة إلى معرفات طويلة**: استخدم أسماء الكائنات والحقول مباشرة في نقاط النهاية
* **معاملة متساوية للكائنات القياسية والمخصصة**: تحصل كائناتك المخصصة على نفس معاملة واجهة برمجة التطبيقات كما هو الحال مع الكائنات المضمنة
* **نقاط نهاية مخصصة**: يحصل كل كائن وحقل على نقطة نهاية API الخاصة به
* **وثائق مخصصة**: يتم إنشاؤها خصيصًا لنموذج بيانات مساحة عملك

<Note>
وثائق واجهة برمجة التطبيقات المخصصة لك متاحة ضمن **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب** بعد إنشاء مفتاح API. نظرًا لأن Twenty تُنشئ واجهات برمجة تطبيقات تتطابق مع نموذج البيانات المخصص لديك، فإن الوثائق فريدة لمساحة عملك.
</Note>

## نوعا واجهات برمجة التطبيقات

### واجهة برمجة التطبيقات الأساسية

يتم الوصول إليها عبر `/rest/` أو `/graphql/`

تعامَل مع **السجلات** الفعلية لديك (البيانات):

* إنشاء وقراءة وتحديث وحذف الأشخاص والشركات والفرص، إلخ.
* استعلام وتصفية البيانات
* إدارة العلاقات بين السجلات

### واجهة برمجة البيانات الوصفية

يتم الوصول إليها عبر `/rest/metadata/` أو `/metadata/`

إدارة **مساحة العمل ونموذج البيانات** لديك:

* إنشاء أو تعديل أو حذف الكائنات والحقول
* تكوين إعدادات مساحة العمل
* تعريف العلاقات بين الكائنات

## REST مقابل GraphQL

تتوفر واجهات برمجة التطبيقات الأساسية وواجهات البيانات الوصفية بصيغتي REST وGraphQL:

| التنسيق     | العمليات المتاحة                                                              |
| ----------- | ----------------------------------------------------------------------------- |
| **REST**    | CRUD، عمليات الدفعات، إدراج/تحديث                                             |
| **GraphQL** | نفس الشيء + **عمليات إدراج/تحديث مجمعة**، واستعلامات العلاقات في استدعاء واحد |

اختر بناءً على احتياجاتك — كلا الصيغتين تصلان إلى البيانات نفسها.

## نقاط نهاية API

| البيئة                | عنوان URL الأساسي         |
| --------------------- | ------------------------- |
| **السحابة**           | `https://api.twenty.com/` |
| **الاستضافة الذاتية** | `https://{your-domain}/`  |

## المصادقة

كل طلب API يتطلب تضمين مفتاح API في رأس الطلب:

```
Authorization: Bearer YOUR_API_KEY
```

### قم بإنشاء مفتاح API

1. انتقل إلى **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب**
2. انقر على **+ إنشاء مفتاح**
3. التكوين:
   * **الاسم**: اسم وصفي للمفتاح
   * **تاريخ الانتهاء**: متى تنتهي صلاحية المفتاح
4. انقر على **حفظ**
5. **انسخه فوراً** — يظهر المفتاح مرة واحدة فقط

<VimeoEmbed videoId="928786722" title="إنشاء مفتاح API" />

<Warning>
يمنح مفتاح API الخاص بك الوصول إلى بيانات حساسة. لا تشاركه مع خدمات غير موثوقة. إذا تم اختراقه، عطّلْه فوراً وأنشئ مفتاحاً جديداً.
</Warning>

### تعيين دور لمفتاح API

لتحسين الأمان، عيّن دوراً محدداً لتقييد الوصول:

1. اذهب إلى **الإعدادات → الأدوار**
2. انقر على الدور الذي ترغب في تعيينه
3. افتح علامة التبويب **التعيين**
4. ضمن **مفاتيح API**، انقر على **+ تعيين إلى مفتاح API**
5. حدد مفتاح API

سيرث المفتاح أذونات ذلك الدور. راجع [الأذونات](/l/ar/user-guide/permissions-access/capabilities/permissions) للحصول على التفاصيل.

### إدارة مفاتيح API

**إعادة التوليد**: الإعدادات → واجهات برمجة التطبيقات وخطافات الويب → انقر على المفتاح → **إعادة التوليد**

**حذف**: الإعدادات → واجهات برمجة التطبيقات وخطافات الويب → انقر على المفتاح → **حذف**

## ملعب واجهة برمجة التطبيقات

اختبر واجهات برمجة التطبيقات لديك مباشرة في المتصفح باستخدام الملعب المدمج لدينا — متاح لكلٍ من **REST** و**GraphQL**.

### الوصول إلى الملعب

1. انتقل إلى **الإعدادات → واجهات برمجة التطبيقات وخطافات الويب**
2. أنشئ مفتاح API (مطلوب)
3. انقر على **REST API** أو **GraphQL API** لفتح الملعب

### ما الذي ستحصل عليه

* **وثائق تفاعلية**: يتم إنشاؤها لنموذج البيانات المحدد لديك
* **اختبارات حيّة**: تنفيذ استدعاءات API فعلية على مساحة عملك
* **مستكشف المخطط**: تصفح الكائنات والحقول والعلاقات المتاحة
* **منشئ الطلبات**: أنشئ الاستعلامات مع الإكمال التلقائي

يعكس الملعب الكائنات والحقول المخصصة لديك، لذا تكون الوثائق دائماً دقيقة لمساحة عملك.

## عمليات الدفعات

كلٌ من REST وGraphQL يدعمان عمليات الدفعات:

* **حجم الدفعة**: حتى 60 سجل لكل طلب
* **العمليات**: إنشاء وتحديث وحذف سجلات متعددة

**ميزات خاصة بـ GraphQL:**

* **إدراج/تحديث دفعي**: إنشاء أو تحديث في استدعاء واحد
* استخدم الأسماء الجمع للكائنات (على سبيل المثال، `CreateCompanies` بدلاً من `CreateCompany`)

## حدود المعدل

يتم تنظيم طلبات API لضمان استقرار المنصة:

| الحد           | القيمة                 |
| -------------- | ---------------------- |
| **الطلبات**    | 100 استدعاء في الدقيقة |
| **حجم الدفعة** | 60 سجل لكل استدعاء     |

<Tip>
استخدم عمليات الدفعات لزيادة الإنتاجية — عالج ما يصل إلى 60 سجلًا في استدعاء API واحد بدلاً من إجراء طلبات فردية.
</Tip>