---
type: how-to
title: أدِر Caputchin من الـ API
summary: صادِق برمز وصول شخصي وقُد API الإدارة الواحد مباشرةً عبر HTTP، مع مثال مشروح ورابط إلى المرجع الكامل.
---

كل ما تستطيع فعله في لوحة التحكّم، ما عدا الفوترة، تستطيع فعله أيضًا من الكود. يكشف Caputchin **API إدارة واحدًا**، وثلاثة أسطح تجلس فوقه: API عبر HTTP هذا مباشرةً، و[خادم MCP](/docs/automation/mcp) لوكلاء الذكاء الاصطناعي، و[مزوّد Terraform وOpenTofu](/docs/automation/terraform) للبنية التحتية ككود. تختلف عند الحافّة فقط؛ التحقّق والصلاحيات وتسجيل التدقيق نفسها تنطبق أيًّا استخدمت.

الثلاثة جميعها تصادق بالاعتماد نفسه: رمز وصول تسكّه مرة.

## اسكك رمز وصول [#mint-an-access-token]

ترسل الرمز كترويسة `Bearer`. هناك نوعان، مغطّيان كاملًا تحت [رمز الوصول الشخصي](/docs/account-management/personal-access-token) و[رموز الفرق](/docs/troops/tokens):

| الرمز | الامتداد | اسككه |
|---|---|---|
| **رمز الوصول الشخصي** | رئيسي على حسابك كله | [إعدادات الحساب](/docs/account-management/account-settings#account-access-token). مجاني، واحد لكل حساب. |
| **رمز وصول الفريق** | الفرق المرفق بها وحدها، بالصلاحيات الممنوحة | صفحة رموز الفريق. يأخذ [مقعدًا](/docs/troops/seats). |

استخدم رمز وصول شخصيًّا لأتمتة حسابك الكامل؛ واستخدم رمز فريق للوصول المحصور بالامتياز الأدنى (مهمّة CI لا تلمس سوى فريق واحد). كلاهما يعمل في كل ما أدناه. تُعرَض قيمة الرمز **مرة واحدة** عند الإنشاء، فانسخها إلى مخزن أسرار.

## الرابط الأساسي والمصادقة

API الإدارة مجذّر عند:

```
https://api.caputchin.com/v1/management
```

كل طلب يحمل الرمز كترويسة `Bearer`:

```http
Authorization: Bearer cpt_pat_...
```

الطلبات والاستجابات JSON. نداء لا يُسمح لرمزك به يعيد `403`؛ ورمز مجهول أو ملغًى يعيد `401`.

## مثال مشروح: إنشاء مفتاح موقع

لنقل إنك تريد مفتاح موقع جديدًا في فريقك `shop-team`. عدّد فرقك أولًا لإيجاد معرّفه، ثم أنشئ المفتاح فيه.

```bash
# 1. Find the troop id.
curl -s https://api.caputchin.com/v1/management/troops \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN"
# → { "troops": [ { "id": "troop_…", "name": "shop-team", … }, … ] }

# 2. Create a site key in that troop.
curl -s -X POST https://api.caputchin.com/v1/management/sites \
  -H "Authorization: Bearer $CAPUTCHIN_MANAGEMENT_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "name": "shop-frontend", "troop_id": "troop_…" }'
# → { "id": "site_…", "key": "cpt_pub_…", "secret": "cpt_sec_…", … }
```

تحمل الاستجابة `key` العام للمفتاح الجديد و`secret` خاصته. **يُعرَض السرّ مرة واحدة**، هنا، فالتقطه الآن؛ ستـ[تحقّق به على خادمك الخلفي](/docs/integration-guides/verify-on-your-backend). أسقط `troop_id` فيحطّ المفتاح في فريقك Personal.

ذلك هو النمط كله: رمز `Bearer`، وجسم JSON، ونداء واحد لكل عملية. التعداد `GET`، والإنشاء `POST`، والتحديث `PATCH` أو `PUT`، والإزالة `DELETE`، مقابل مسارات الموارد تحت الرابط الأساسي.

## المرجع الكامل

كل نقطة وصول، بمعاملاتها، ومخطّطات طلبها واستجابتها، ولوحة "جرّبها" مدمجة تصادق برمزك، في [مرجع الـ API التفاعلي](/docs/api-reference). إنه مولَّد من مواصفة OpenAPI نفسها التي بُني عليها الـ API، فلا ينحرف أبدًا عن السطح الحيّ. وجّه مولّدات عملائك إلى المواصفة المربوطة هناك.

## انظر أيضًا

- [رمز الوصول الشخصي](/docs/account-management/personal-access-token): الاعتماد الرئيسي وكيف تتتبّع استخدامه.
- [استخدم خادم MCP](/docs/automation/mcp): الـ API نفسه، يقوده وكيل ذكاء اصطناعي.
- [استخدم Terraform أو OpenTofu](/docs/automation/terraform): الـ API نفسه، كبنية تحتية ككود.
- [مرجع الـ API التفاعلي](/docs/api-reference): كل نقطة وصول ومخطّط.