واجهة برمجة الفرق

إدارة الفرق والأعضاء والأدوار والدعوات لبناء النماذج التعاوني.

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

تستخدم جميع هياكل الطلبات والاستجابات أسماء حقول بتنسيق snake_case.

أدوار الفريق

ownerrole

وصول كامل. يمكنه إدارة الأعضاء والفوترة وحذف الفريق.

adminrole

يمكنه إنشاء النماذج وتعديلها وحذفها، وإدارة الأعضاء، وعرض الاستجابات.

editorrole

يمكنه إنشاء النماذج وتعديلها وعرض الاستجابات. لا يمكنه إدارة الأعضاء.

viewerrole

يمكنه عرض النماذج والاستجابات. لا يمكنه الإنشاء أو التعديل.

Endpoints

GET/api/v1/teamsPOST/api/v1/teamsGET/api/v1/teams/:teamIdPUT/api/v1/teams/:teamIdDELETE/api/v1/teams/:teamIdGET/api/v1/teams/:teamId/membersPOST/api/v1/teams/:teamId/membersPUT/api/v1/teams/:teamId/members/:memberIdDELETE/api/v1/teams/:teamId/members/:memberIdGET/api/v1/teams/:teamId/invitationsPOST/api/v1/teams/:teamId/invitationsDELETE/api/v1/teams/:teamId/invitations/:invId

عرض الفرق

GET/api/v1/teams

يُرجع جميع الفرق التي ينتمي إليها المستخدم المُصادَق عليه.

الاستجابة

json

{
  "teams": [
    {
      "id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Marketing",
      "slug": "marketing",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-02-15T11:30:00.000Z",
      "member_count": 5,
      "your_role": "admin"
    },
    {
      "id": "665c3d4e5f6a7b8c9d0e1f20",
      "name": "Product",
      "slug": "product",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-02-01T14:00:00.000Z",
      "updated_at": "2026-02-20T16:45:00.000Z",
      "member_count": 3,
      "your_role": "owner"
    }
  ]
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

إنشاء فريق

POST/api/v1/teams

يُنشئ فريقاً جديداً. يصبح المستخدم المُصادَق عليه مالك الفريق.

جسم الطلب

namestring

اسم الفريق

مثال الطلب

json

{
  "name": "Marketing"
}

الاستجابة

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z"
}

أمثلة الشيفرة البرمجية

bash

curl -X POST "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing" }'

الحصول على فريق

GET/api/v1/teams/:teamId

يسترجع فريقاً واحداً بواسطة المعرّف.

يمكن لأي عضو في الفريق استدعاؤه. ولا تتضمن الاستجابة أبدًا أسرار الفريق (سلسلة الاتصال بقاعدة بيانات موطن البيانات، أو معرّف اتصال SSO، أو معرّفات النطاق الداخلية)، ولا يُعاد sso_domain_verify_token (قيمة DNS التي تثبت نطاق SSO) إلا لمن يستدعيه بدور owner أو admin.

معاملات المسار

teamIdstring

معرّف الفريق

الاستجابة

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-15T11:30:00.000Z",
  "member_count": 5
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

تحديث فريق

PUT/api/v1/teams/:teamId

يُحدّث خصائص الفريق. يتطلب دور owner أو admin.

معاملات المسار

teamIdstring

معرّف الفريق

جسم الطلب

namestring

اسم الفريق الجديد

مثال الطلب

json

{
  "name": "Marketing & Growth"
}

الاستجابة

يُرجع كائن الفريق المُحدَّث.

أمثلة الشيفرة البرمجية

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing & Growth" }'

حذف فريق

DELETE/api/v1/teams/:teamId

يحذف فريقاً بشكل نهائي. يمكن لمالك الفريق فقط حذف الفريق.

يؤدي حذف الفريق إلى إزالة جميع عضويات الفريق والدعوات. لا يتم حذف النماذج التابعة للفريق تلقائياً ولكنها ستصبح غير قابلة للوصول لأعضاء الفريق السابقين.

معاملات المسار

teamIdstring

معرّف الفريق

الاستجابة

json

{
  "success": true
}

أمثلة الشيفرة البرمجية

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

عرض الأعضاء

GET/api/v1/teams/:teamId/members

يُرجع جميع أعضاء الفريق.

معاملات المسار

teamIdstring

معرّف الفريق

الاستجابة

json

{
  "members": [
    {
      "id": "66d1e2f3a4b5c6d7e8f9a0b1",
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "role": "owner",
      "joined_at": "2026-01-10T09:00:00.000Z"
    },
    {
      "id": "66d2e3f4a5b6c7d8e9f0a1b2",
      "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Smith",
      "role": "editor",
      "joined_at": "2026-01-15T14:30:00.000Z"
    }
  ]
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

إضافة عضو

POST/api/v1/teams/:teamId/members

يدعو شخصًا إلى الفريق عبر البريد الإلكتروني، تمامًا مثل إنشاء دعوة: يرسل NueForm الدعوة بالبريد الإلكتروني، وتنتهي صلاحيتها بعد 7 أيام، وينضم الشخص إلى الفريق عند قبولها. لا يضيف مستخدمًا موجودًا مباشرةً. يتطلب دور owner أو admin. يُرجع الدعوة (201)؛ ويستجيب بـ 409 إذا كان العنوان يخص عضوًا بالفعل أو لديه دعوة معلّقة لم تنتهِ صلاحيتها بعد (الدعوة المنتهية الصلاحية لا تمنع إرسال دعوة جديدة)، وبـ 400 إذا لم تتبقَّ مقاعد في خطة مالك الفريق — فالدعوة المعلّقة تشغل مقعدًا حتى تنتهي صلاحيتها.

معاملات المسار

teamIdstring

معرّف الفريق

جسم الطلب

emailstring

عنوان البريد الإلكتروني المراد دعوته (يُخزَّن بأحرف صغيرة)

rolestring

الدور الذي يحصل عليه الشخص عند القبول: "admin" أو "editor" أو "viewer"

مثال الطلب

json

{
  "email": "carol@example.com",
  "role": "editor"
}

الاستجابة

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "token": "2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f",
  "status": "pending",
  "language": "en",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z",
  "invite_url": "/teams/invite/2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f"
}

أمثلة الشيفرة البرمجية

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

تحديث دور العضو

PUT/api/v1/teams/:teamId/members/:memberId

يُحدّث دور عضو في الفريق. يتطلب دور owner أو admin. لا يمكنك تغيير دور المالك.

معاملات المسار

teamIdstring

معرّف الفريق

memberIdstring

معرّف عضو الفريق

جسم الطلب

rolestring

الدور الجديد: "admin"، "editor"، "viewer"

مثال الطلب

json

{
  "role": "admin"
}

الاستجابة

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "admin",
  "joined_at": "2026-01-15T14:30:00.000Z"
}

أمثلة الشيفرة البرمجية

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

إزالة عضو

DELETE/api/v1/teams/:teamId/members/:memberId

يُزيل عضواً من الفريق. يتطلب دور owner أو admin. لا يمكن إزالة مالك الفريق. تُلغى أيضًا الدعوات المعلّقة من هذا الفريق إلى هذا الشخص، حتى لا يتمكن من الانضمام مجددًا باستخدامها.

معاملات المسار

teamIdstring

معرّف الفريق

memberIdstring

معرّف عضو الفريق

الاستجابة

json

{
  "success": true,
  "message": "Member removed from team"
}

أمثلة الشيفرة البرمجية

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY"

عرض الدعوات

GET/api/v1/teams/:teamId/invitations

يُرجع دعوات الفريق المعلّقة التي لم تنتهِ صلاحيتها، الأحدث أولًا. يمكن لأي عضو في الفريق استدعاؤه، ولا يُضمَّن الحقل token (السر الموجود في رابط الدعوة) إلا لمن يستدعيه بدور owner أو admin.

معاملات المسار

teamIdstring

معرّف الفريق

الاستجابة

json

{
  "invitations": [
    {
      "id": "66e1f2a3b4c5d6e7f8a9b0c1",
      "email": "carol@example.com",
      "role": "editor",
      "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "status": "pending",
      "expires_at": "2026-03-07T12:00:00.000Z",
      "created_at": "2026-02-28T12:00:00.000Z"
    }
  ]
}

أمثلة الشيفرة البرمجية

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"

إنشاء دعوة

POST/api/v1/teams/:teamId/invitations

يُرسل دعوة عبر البريد الإلكتروني للانضمام إلى فريق. تتضمن الدعوة رمزاً فريداً وتنتهي صلاحيتها بعد 7 أيام. يتطلب دور owner أو admin. يستجيب بـ 409 إذا كان العنوان يخص عضوًا بالفعل أو لديه دعوة معلّقة لم تنتهِ صلاحيتها بعد (الدعوة المنتهية الصلاحية لا تمنع إرسال دعوة جديدة)، وبـ 400 إذا لم تتبقَّ مقاعد في خطة مالك الفريق — فالدعوة المعلّقة تشغل مقعدًا حتى تنتهي صلاحيتها.

معاملات المسار

teamIdstring

معرّف الفريق

جسم الطلب

emailstring

عنوان البريد الإلكتروني للدعوة

rolestring

الدور الذي يحصل عليه الشخص عند القبول: "admin" أو "editor" أو "viewer"

مثال الطلب

json

{
  "email": "carol@example.com",
  "role": "editor"
}

الاستجابة

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "token": "2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f",
  "status": "pending",
  "language": "en",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z",
  "invite_url": "/teams/invite/2f7c1d3e-9a4b-4c1d-8e2f-0a1b2c3d4e5f"
}

أمثلة الشيفرة البرمجية

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

إلغاء دعوة

DELETE/api/v1/teams/:teamId/invitations/:invId

يُلغي دعوة معلقة. يتطلب دور owner أو admin. لن يكون رمز الدعوة صالحاً بعد الإلغاء.

معاملات المسار

teamIdstring

معرّف الفريق

invIdstring

معرّف الدعوة

الاستجابة

json

{
  "success": true,
  "message": "Invitation cancelled"
}

أمثلة الشيفرة البرمجية

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations/66e1f2a3b4c5d6e7f8a9b0c1" \
  -H "Authorization: Bearer YOUR_API_KEY"

استجابات الأخطاء

استجابات الأخطاء القياسية التي تُرجعها نقاط نهاية واجهة برمجة الفرق.

رموز الأخطاء

400Bad Request

حقول مطلوبة مفقودة، أو بريد إلكتروني أو دور غير صالح، أو لا توجد مقاعد متبقية في خطة مالك الفريق

401Unauthorized

مفتاح API مفقود أو غير صالح

403Forbidden

لست عضوًا في الفريق، أو دورك غير كافٍ للإجراء المطلوب

404Not Found

الفريق أو العضو أو الدعوة غير موجود

409Conflict

المستخدم عضو بالفعل، دعوة مكررة

500Server Error

خطأ داخلي في الخادم

مثال خطأ

json

{
  "error": {
    "code": "CONFLICT",
    "message": "A pending invitation already exists for this email",
    "status": 409
  }
}

آخر تحديث: 8 أكتوبر 2026