Skip to content

The open alternative to Salesforce, designed for AI.

5.1 KB
Raw Blame
---
title: واجهات برمجة التطبيقات
sidebarTitle: نظرة عامة
description: واجهات برمجة تطبيقات REST وGraphQL مُولَّدة من مخطط مساحة عملك.
---

import { PageBanner } from "/snippets/page-banner.mdx"
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

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

لا توجد مرجعية ثابتة لواجهة برمجة التطبيقات الخاصة بـ Twenty. لكل مساحة عمل مخططها الخاص — عند إضافة كائن مخصص (مثل `Invoice`)، يحصل فورًا على نقاط نهاية REST وGraphQL مطابقة لتلك الخاصة بالكائنات المدمجة مثل `Company` أو `Person`. تُولَّد واجهة برمجة التطبيقات من المخطط، لذا تستخدم نقاط النهاية أسماء الكائنات والحقول لديك مباشرة — بدون معرّفات غامضة.

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

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

**واجهة برمجة التطبيقات الأساسية** — `/rest/` و`/graphql/`

عمليات CRUD على السجلات: الأشخاص، الشركات، الفرص، وكائناتك المخصصة. استعلام، تصفية، والتنقل عبر العلاقات.

**واجهة برمجة تطبيقات البيانات الوصفية** — `/rest/metadata/` و`/metadata/`

إدارة المخطط: إنشاء/تعديل/حذف الكائنات والحقول والعلاقات. هذه هي الطريقة لتغيير نموذج بياناتك برمجيًا.

كلاهما متاحان عبر REST وGraphQL. تضيف GraphQL عمليات upsert على دفعات وإمكانية التنقل عبر العلاقات في استعلام واحد. نفس البيانات الأساسية بأي من الطريقتين.

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

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

## المصادقة

```
Authorization: Bearer YOUR_API_KEY
```

أنشئ مفتاح API من **الإعدادات → المطورون → API → + Create key**. انسخه فورًا — يُعرَض مرة واحدة فقط. يمكن تقييد نطاق المفاتيح بدور محدد ضمن **الإعدادات → الأعضاء → الأدوار → علامة التبويب Assignment** للحد مما يمكنها الوصول إليه.

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

للوصول المعتمد على OAuth (تطبيقات خارجية تتصرف نيابةً عن المستخدمين)، راجع [OAuth](/ar/developers/extend/oauth).

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

يدعم كلٌّ من REST وGraphQL التجميع لما يصل إلى 60 سجلًا لكل طلب — إنشاء أو تحديث أو حذف. كما تدعم GraphQL عملية upsert على دفعات (إنشاء-أو-تحديث في استدعاء واحد) باستخدام أسماء جمع مثل `CreateCompanies`.

## تحديد الحقول (REST)

تقبل نقاط نهاية سجلات REST مَعلمة الاستعلام `fields` لإرجاع الحقول التي تحتاجها فقط:

```
GET /rest/people?fields=id,name,emails,company
```

* يتم إرجاع `id` دائمًا.
* تُحدَّد الحقول المركبة (مثل `emails` أو `name`) كاملةً باسم الحقل الخاص بها.
* يُرجع حقل العلاقة متعدد-إلى-واحد عمود الربط الخاص به (مثل `companyId`) مع `depth=0`. لا يتم إرجاع حقول العلاقة واحد-إلى-متعدد إلا مع `depth=1`. باستخدام `depth=1`، لا يتم توسيع سوى حقول العلاقات المدرجة في `fields`.
* تؤدي الحقول غير المعروفة، أو الحقول التي لا يمكن لدورك قراءتها، إلى إرجاع خطأ `400`.

عند حذف `fields` في كائن يحتوي على أكثر من 200 حقل قابل للقراءة، يُرجع كل سجل مجموعة افتراضية من 200 حقل: `id`، وحقول معرّف التسمية والصورة، و`createdAt`، و`updatedAt`، و`deletedAt`، و`position`، ثم الحقول القياسية قبل الحقول المخصصة، مرتبة حسب الاسم. مرر `fields` صراحةً لقراءة أي حقل يتجاوز تلك المجموعة الافتراضية.

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

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

<PageBanner illustration="dev-api" />