---
title: "الحساب: دليل API فريقي"
description: "هوية المفتاح الذي يستدعي الواجهة، والبحث الموحّد في مساحة العمل. مسارات الحساب في REST API فريقي: البارامترات، وجسم الطلب، وأمثلة الاستجابة، وحالات الرفض."
url: https://fareeqy.com/api/v1/docs/account
language: ar
---

# الحساب

هوية المفتاح الذي يستدعي الواجهة، والبحث الموحّد في مساحة العمل.

عنوان الخدمة `https://app.fareeqy.com/api/v1`

المحتويات

في هذه الصفحة

-   شكل المورد
-   هوية المفتاح المستخدَم
-   بحث موحّد في مساحة العمل

المسارات

-   [الحساب](https://fareeqy.com/api/v1/docs/account)
-   [الأحداث](https://fareeqy.com/api/v1/docs/events)
-   [المشاريع](https://fareeqy.com/api/v1/docs/projects)
-   [الأعضاء](https://fareeqy.com/api/v1/docs/members)
-   [قوائم المهام](https://fareeqy.com/api/v1/docs/task-lists)
-   [المهام](https://fareeqy.com/api/v1/docs/tasks)
-   [التعليقات](https://fareeqy.com/api/v1/docs/comments)
-   [المجلس](https://fareeqy.com/api/v1/docs/discussions)
-   [الملفات](https://fareeqy.com/api/v1/docs/files)
-   [المجلدات](https://fareeqy.com/api/v1/docs/folders)

المزيد

-   [سجل التغييرات](https://fareeqy.com/api/v1/docs/changelog)

في هذه الصفحة

-   شكل المورد
-   هوية المفتاح المستخدَم
-   بحث موحّد في مساحة العمل

المسارات

-   [الحساب](https://fareeqy.com/api/v1/docs/account)
-   [الأحداث](https://fareeqy.com/api/v1/docs/events)
-   [المشاريع](https://fareeqy.com/api/v1/docs/projects)
-   [الأعضاء](https://fareeqy.com/api/v1/docs/members)
-   [قوائم المهام](https://fareeqy.com/api/v1/docs/task-lists)
-   [المهام](https://fareeqy.com/api/v1/docs/tasks)
-   [التعليقات](https://fareeqy.com/api/v1/docs/comments)
-   [المجلس](https://fareeqy.com/api/v1/docs/discussions)
-   [الملفات](https://fareeqy.com/api/v1/docs/files)
-   [المجلدات](https://fareeqy.com/api/v1/docs/folders)

المزيد

-   [سجل التغييرات](https://fareeqy.com/api/v1/docs/changelog)

## شكل المورد

الحقول التي ترجع داخل `data` في مسارات هذه المجموعة.

`key` object

`company` object

`created_by` object

من أنشأ المفتاح. توقيع، لا الصلاحيات التي يُنفَّذ بها الطلب.

Account نسخ

 `{   "key": {     "name": "مزامنة الفوترة",     "access": "write",     "operations": [       "projects:read",       "tasks:read",       "tasks:write"     ]   },   "company": {     "name": "فريق التقنية"   },   "created_by": {     "name": "سارة العتيبي",     "email": "sara@example.com"   } }`

### هوية المفتاح المستخدَم

GET /me يتطلب `account:read`

يرجع المفتاح نفسه: اسمه، ومستوى وصوله، والعمليات التي يستطيع استدعاءها بالتحديد، ومعه الشركة التي يعمل باسمها. هذا هو الفحص المعياري: هل مفتاحي صالح، وإلى أين يصل؟ وحقل `created_by` اسم من أنشأ المفتاح، لا الهوية التي يُنفَّذ بها الطلب.

#### مثال الطلب

cURL نسخ

 `curl "https://app.fareeqy.com/api/v1/me" \   -H "Authorization: Bearer $FAREEQY_API_KEY"`

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

200 نسخ

 `{   "data": {     "key": {       "name": "مزامنة الفوترة",       "access": "write",       "operations": [         "projects:read",         "tasks:read",         "tasks:write"       ]     },     "company": {       "name": "فريق التقنية"     },     "created_by": {       "name": "سارة العتيبي",       "email": "sara@example.com"     }   } }`

حالات الرفض: 401 403 404 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض

401 `default`

Missing or invalid API key.

default نسخ

 `{   "error": {     "code": "unauthorized",     "message": "مفتاح الـ API غير صالح أو غير مُرسَل."   } }`

403 `forbidden`

Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry.

This key may not perform this operation نسخ

 `{   "error": {     "code": "forbidden",     "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية."   } }`

The company's plan carries no API access نسخ

 `{   "error": {     "code": "plan_upgrade_required",     "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله."   } }`

404 `not_found`

Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach.

A record that is missing or out of reach نسخ

 `{   "error": {     "code": "not_found",     "message": "غير موجود، أو لا تملك صلاحية الوصول إليه."   } }`

A path that matches no endpoint نسخ

 `{   "error": {     "code": "unknown_endpoint",     "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API."   } }`

429 `rate_limit_exceeded`

Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": "<string>"}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string.

Today's daily allowance is spent (application envelope) نسخ

 `{   "error": {     "code": "rate_limit_exceeded",     "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh."   } }`

Over 300 requests in a minute (Rack::Attack body, flat error) نسخ

 `{   "error": "Rate limit exceeded. Please try again later." }`

[الأخطاء](https://fareeqy.com/api/v1/docs#errors)

### بحث موحّد في مساحة العمل

GET /search يتطلب `account:read`

يبحث بالاسم في المشاريع، وقوائم المهام، والمهام، والمجلدات، والملفات، ومواضيع المجلس، مع تطبيع النص العربي، وداخل شركة المفتاح. يرجع لكل نتيجة معرّفها الثابت، وهو ما تحمله إلى الطلب التالي، ومعه المعرّفات الثابتة للآباء والمعرّفات الرقمية التي تستقبلها بقية المسارات. لكل نوع سقف مستقل ( `per_type` )، ويُسمّي `truncated` كل نوع كانت نتائجه أكثر مما أُرجع. ويُسمّي `widened` كل نوع لم يحمل فيه أي سجل كل كلمات البحث، فنتائجه تقريبية: تحقّق منها قبل أن تعمل بها. البحث بقيمة `q` فارغة يرجع نتائج فارغة.

#### بارامترات الاستعلام

`q` string

كلمة البحث. والقيمة الفارغة ترجع نتائج فارغة.

`types` string\[\]

حصر البحث في هذه الأنواع. اتركه ليشمل كل الأنواع، والأسماء غير المعروفة تُتجاهل.

`per_type` integer

أقصى عدد نتائج لكل نوع. الافتراضي 5، والحد الأقصى 25، وما زاد عنه يُقصَر عليه.

الافتراضي: `5`

#### مثال الطلب

cURL نسخ

 `curl "https://app.fareeqy.com/api/v1/search" \   -H "Authorization: Bearer $FAREEQY_API_KEY"`

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

200 نسخ

 `{   "data": {     "query": "تصميم",     "results": [       {         "type": "project",         "id": "prj-8f3kd",         "url": "https://app.fareeqy.com/projects/prj-8f3kd",         "title": "تطوير الموقع",         "project_slug": "prj-8f3kd",         "archived": false       },       {         "type": "task",         "id": "tsk-9wb7t",         "url": "https://app.fareeqy.com/tasks/tsk-9wb7t",         "title": "تصميم الهيدر",         "project_slug": "prj-8f3kd",         "task_list_slug": "lst-4m2qp",         "task_slug": "tsk-9wb7t",         "completed": false       },       {         "type": "folder",         "url": "https://app.fareeqy.com/projects/prj-8f3kd/files?folder_id=42",         "name": "التصاميم",         "project_slug": "prj-8f3kd",         "folder_id": 42       }     ],     "truncated": [       "task"     ],     "widened": []   } }`

حالات الرفض: 401 403 404 429 اعرض أمثلة الرفض أخفِ أمثلة الرفض

401 `default`

Missing or invalid API key.

default نسخ

 `{   "error": {     "code": "unauthorized",     "message": "مفتاح الـ API غير صالح أو غير مُرسَل."   } }`

403 `forbidden`

Two different refusals share this status, and a client must tell them apart by `error.code`. `forbidden` means the key's scope or allowlist does not permit this operation, or Pundit denied the action. `plan_upgrade_required` means the company's plan carries no API access at all, so no key on it can ever succeed and there is nothing to retry.

This key may not perform this operation نسخ

 `{   "error": {     "code": "forbidden",     "message": "هذا الـ API key لا يملك صلاحية تنفيذ هذه العملية."   } }`

The company's plan carries no API access نسخ

 `{   "error": {     "code": "plan_upgrade_required",     "message": "خطة «الاحترافي» لا تشمل الوصول إلى API. رقِّ إلى «المتطور» أو «الإنتاجي» لتفعيله."   } }`

404 `not_found`

Resource not found or not accessible — also returned for EVERY endpoint when the company's `rest_api` feature flag is disabled (the surface is hidden). Lookups drill through the URL hierarchy, so another company's record is a 404 and never a leak. A path that matches no route at all answers 404 with the distinct code `unknown_endpoint` and echoes the path back, so a mistyped or half-built URL is told apart from a record that is missing or out of reach.

A record that is missing or out of reach نسخ

 `{   "error": {     "code": "not_found",     "message": "غير موجود، أو لا تملك صلاحية الوصول إليه."   } }`

A path that matches no endpoint نسخ

 `{   "error": {     "code": "unknown_endpoint",     "message": "لا يوجد endpoint يطابق GET /api/v1/projcts. راجع المسار في توثيق الـ API."   } }`

429 `rate_limit_exceeded`

Either the company's daily API allowance is spent ( `rate_limit_exceeded` ), or the per-key / per-IP burst throttle of 300 requests per minute fired. Both come back after a wait, so `Retry-After` is honest here. **The two bodies are not the same shape.** The daily-quota refusal uses the standard error envelope. The burst throttle is served by Rack::Attack ahead of the application, so its body is a flat `{"error": "<string>"}` with no `code`. A client that reads `error.code` has to tolerate `error` being a plain string.

Today's daily allowance is spent (application envelope) نسخ

 `{   "error": {     "code": "rate_limit_exceeded",     "message": "استهلكت رصيد اليوم من طلبات API في خطة «المتطور» (1000 طلب يوميًا). يتجدد الرصيد عند منتصف الليل بتوقيت Asia/Riyadh."   } }`

Over 300 requests in a minute (Rack::Attack body, flat error) نسخ

 `{   "error": "Rate limit exceeded. Please try again later." }`

[الأخطاء](https://fareeqy.com/api/v1/docs#errors)

[الرجوع إلى نظرة عامة](https://fareeqy.com/api/v1/docs) [التالي الأحداث](https://fareeqy.com/api/v1/docs/events)