تاريخ مراجعة السياسة والوثائق: 5 نوفمبر 2026. تستخدم جميع أمثلة الطرفية Bash، وهي مناسبة لـ macOS وLinux وبيئات التطوير التي تعمل بهذه الصدفة.
بعد شراء Max أو Ultra أو Team، يجب ربط أرصدة API الممنوحة بمؤسسة Claude Console قبل استخدامها في برامجك أو وكلائك.
يمكن إنجاز العملية بهذا الترتيب:
تأكيد الأهلية ← ربط مؤسسة Console ← فحص الرصيد الممنوح ← إنشاء مفتاح API ← إرسال طلب صغير ← مطابقة المؤسسة وسجلات الاستخدام ← إعداد claude -p.
النقطة الأهم هي تطابق حساب الاشتراك ومؤسسة Console ومفتاح API ومسار فوترة الطلب الفعلي. وصول رد من النموذج يثبت نجاح الطلب فقط؛ ولا يزال عليك التحقق من المؤسسة والرصيد اللذين استُخدما.
1. تأكد من المبلغ الذي يمكنك المطالبة به ومن الشخص المخوّل
يمنح برنامج أرصدة API الشهرية الحالي المبالغ التالية:
| الخطة أو المقعد | رصيد API الشهري الممنوح | جهة استلام الرصيد |
|---|---|---|
| Max | 100 دولار | مؤسسة Console واحدة مرتبطة |
| Ultra | 200 دولار | مؤسسة Console واحدة مرتبطة |
| Team Standard | 20 دولارًا للمقعد | رصيد مشترك للفريق |
| Team Premium | 100 دولار للمقعد | رصيد مشترك للفريق |
| الفريق كاملًا في Team | حتى 500 دولار | رصيد موحد في مؤسسة واحدة |
مثلًا، تمنح ثلاثة مقاعد Standard ومقعدان Premium مبلغًا شهريًا اسميًا يساوي:
3 × 20 + 2 × 100 = 260 دولارحتى عشرة مقاعد Premium تظل خاضعة لسقف الفريق كله البالغ 500 دولار شهريًا.
يلزم قبل المطالبة استيفاء شرطين: أن تكون الخطة نشطة وفي وضع سليم، وأن يكون المشترك الجديد قد أمضى سبعة أيام في خطة مؤهلة. الاشتراكات المشتراة عبر iOS أو Android مؤهلة أيضًا، لكن المطالبة تتم عبر الويب. ولا يلزم إضافة بطاقة دفع إلى Claude Platform مسبقًا.
السياسة الرسمية للمنح الشهرية · شرح المطالبة وتطبيق الأرصدة في المنصة
تحقّق كذلك من الصلاحيات على الجانبين:
| الجانب | الهوية أو الدور المطلوب للمطالبة |
|---|---|
| اشتراك Max / Ultra | المشترك نفسه |
| اشتراك Team | Primary Owner أو Owner |
| مؤسسة Console المستلمة | Owner أو Admin أو Billing |
السبعة أيام هنا شرط أهلية للمطالبة بأرصدة API، ولا يمكن استخدامها لاستنتاج موعد اكتمال التحقق التلقائي من Ultra.
2. اربط مؤسسة Console عبر الويب للمطالبة بالرصيد
لمشتركي Max وUltra، افتح:
أما في Team، فيدخل Owner أو Primary Owner إلى:
اتبع الخطوات التالية:
- اعثر على قسم API credits.
- انقر Link organization.
- اختر مؤسسة Claude Console التي ستستلم الرصيد. وإذا لم توجد مؤسسة، فيمكن إنشاؤها باتباع مسار الصفحة.
- راجع اسم المؤسسة والغرض الفعلي من استخدامها.
- اقرأ الشروط ذات الصلة وأكّد الربط.
- افتح صفحة Billing في Console وتحقّق من قيد الرصيد.
اختر المؤسسة الصحيحة بعناية قبل الربط. تسمح القواعد الحالية بربط خطة واحدة بمؤسسة Console واحدة، ولا تستطيع المؤسسة استقبال هذه المنحة إلا من خطة واحدة. وبعد الربط لا يمكنك تغييرها بنفسك؛ بل يلزم التواصل مع الدعم.
لا يحتاج كل عضو في Team إلى المطالبة بصورة منفصلة. يربط مسؤول مخوّل المؤسسة، ثم يشارك في استهلاك الرصيد الأعضاء الذين يستخدمون مفاتيح API ضمنها.
إذا لم يظهر خيار المطالبة، فراجع الخطة ومدة الاشتراك والهوية المسجل بها الدخول والأدوار على الجانبين، ثم تواصل مع الدعم الرسمي.
3. أين تفحص الرصيد، وما الأرقام التي تحتاج إلى مراجعتها؟
بعد المطالبة، افتح:
ابدأ بقسم Promotional credits وسجّل خصوصًا:
- قيمة المنحة الحالية؛
- الرصيد المتاح المعروض حاليًا؛
- تاريخ الانتهاء؛
- مؤسسة Console المختارة حاليًا.
ثم افحص بصورة منفصلة الرصيد المشترى وإعدادات Auto-reload.
يُستهلك الرصيد الشهري الممنوح قبل الرصيد المشترى. وينتهي الجزء غير المستخدم في نهاية دورته دون ترحيل، كما تحصل الخطط السنوية على المنحة شهريًا. انتبه تحديدًا إلى أن الشحن التلقائي يعتمد على الرصيد المشترى؛ لذلك قد تحدث إعادة شحن حتى مع بقاء رصيد ممنوح.
عند مطابقة الحسابات، افصل بين أنواع الأرقام الثلاثة التالية:
| الرقم | السؤال الذي يجيب عنه |
|---|---|
| الرصيد وقيود المنح وتواريخ الانتهاء في Billing | كم بقي، ومن أين أتى، ومتى ينتهي |
| usage في استجابة الطلب | عدد التوكنات التي استخدمها هذا الطلب |
| تقارير Usage / Cost أو تقدير التكلفة في CLI | أين حدث الاستهلاك وما تكلفته التقديرية أو الفعلية |
لا تمثل usage رصيدًا بالدولار. كذلك لا يثبت total_cost_usd الذي تعرضه CLI أن تلك التكلفة خُصمت بالفعل من المنحة. حقول التكلفة في Cost Analytics الحالية محسوبة قبل خصم الأرصدة، وقد تتأخر التقارير في التحديث.
4. أنشئ مفتاح API ضمن مساحة العمل الصحيحة
افتح:
للتدريب الشخصي، يمكنك اتباع هذا المسار:
- تأكد من أن مؤسسة Console الحالية هي التي تستلم المنحة.
- انقر Create key.
- أدخل اسمًا يسهل تمييزه، مثل monthly-credit-demo.
- حدّد تاريخ الانتهاء بحسب حاجتك.
- اختر حسابك من Linked account لإنشاء personal key.
- اختر مساحة عمل API عادية لديك إذن الوصول إليها، لإنشاء مفتاح محصور في مساحة العمل الواحدة.
- احفظ المفتاح الظاهر عند الإنشاء وسجّل المؤسسة ومساحة العمل واسم المفتاح.
لا يظهر المفتاح كاملًا إلا مرة واحدة عند الإنشاء. يكفي personal key للتطوير الفردي؛ ويمكن للخدمات المشتركة أو أنظمة الإنتاج استخدام service account بحسب متطلبات إدارة المؤسسة.
هناك تفصيلان إضافيان للصلاحيات:
- القدرة على المطالبة بالرصيد لا تعني القدرة على إنشاء مفتاح. يركز دور Billing على الفوترة والاستخدام؛ ويتطلب إنشاء المفاتيح صلاحيات المؤسسة ومساحة العمل المناسبة.
- إنشاء مساحة عمل يتطلب مسؤولًا على مستوى المؤسسة. وعلى الأعضاء العاديين اختيار مساحة سبق منحهم حق الوصول إليها. إذا تعطل الزر، فاطلب من المسؤول مراجعة الأدوار والعضوية.
لا تختَر مساحة العمل المخصصة لـ Claude Code لإنشاء مفتاح التدريب يدويًا؛ إذ توضح الوثائق الرسمية أن مفاتيح هذه المساحة تُدار بواسطة مسار تسجيل دخول Claude Code.
تستخدم جميع الأمثلة التالية مفتاحًا اختيرت له مساحة عمل واحدة عند الإنشاء. تفرض API الحالية ترويسة إضافية لتحديد مساحة العمل عند استخدام مفتاح غير محصور فيها. لا تخلط إعداد النوعين.
5. جهّز بيئة طرفية مؤقتة
يُنصح بالتدريب أولًا في طرفية منفصلة، مع إبقاء المفتاح في الجلسة الحالية فقط.
ابدأ Bash:
bash --noprofile --norcثم نفّذ:
set +x
umask 077
unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_BASE_URL
unset CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX
unset CLAUDE_CODE_USE_FOUNDRY CLAUDE_CODE_USE_ANTHROPIC_AWS
unset CLAUDE_CODE_EFFORT_LEVEL
mkdir -p "$HOME/claude-api-credit-demo"
cd "$HOME/claude-api-credit-demo"تجعل هذه الإعدادات المؤقتة التمرين يستهدف API المباشرة من المزوّد بوضوح. لكن Claude Code الذي تديره الشركة قد يظل خاضعًا لبوابة المؤسسة أو سياسات المزوّد. اطلب من المسؤول المراجعة إذا ظهر مسار غير متوقع.
نفّذ السطر التالي منفردًا، والصق المفتاح الذي أنشأته ثم اضغط Enter. لن يظهر ما تدخله على الشاشة:
read -r -s -p 'الصق مفتاح API للمؤسسة المرتبطة ثم اضغط Enter: ' ANTHROPIC_API_KEYبعد إدخال المفتاح، نفّذ:
printf '\n'
export ANTHROPIC_API_KEYلا تضع مفتاحًا حقيقيًا في أمثلة المقال أو مصدر السكربت أو سجل الأوامر، ولا تحتاج إلى طباعته باستخدام echo لتأكيد وجوده.
6. أرسل أول طلب صغير باستخدام curl
يثبّت مثال الاتصال النموذج claude-haiku-5-5، ويحد المخرجات ويعطّل thinking. مجموعة المعلمات هذه خاصة بهذا النموذج؛ وعند تغييره يجب مراجعة المعلمات المدعومة من جديد.
أنشئ ملف الطلب أولًا:
cat > request.json <<'JSON'
{
"model": "claude-haiku-5-5",
"max_tokens": 128,
"thinking": {
"type": "disabled"
},
"output_config": {
"effort": "low"
},
"messages": [
{
"role": "user",
"content": "أجب فقط: تم الاتصال بواجهة API بنجاح"
}
]
}
JSONثم أرسل الطلب:
curl --disable --silent --show-error \
--connect-timeout 10 --max-time 60 \
--dump-header response.headers \
--output response.json \
--write-out 'HTTP %{http_code}\n' \
--config - <<EOF
url = "https://api.anthropic.com/v1/messages"
request = "POST"
header = "Authorization: Bearer ${ANTHROPIC_API_KEY}"
header = "anthropic-version: 2026-10-21"
header = "content-type: application/json"
data-binary = "@request.json"
EOFينشئ الأمر ملفين:
- response.json: متن الاستجابة، بما فيه المحتوى وسبب التوقف واستخدام التوكنات؛
- response.headers: ترويسات الاستجابة للتحقق من معرف الطلب والمؤسسة ومساحة العمل وغيرها.
يصل المفتاح إلى curl عبر الإدخال القياسي، ولا يوضع مباشرة في وسائط الأمر. يأتي --disable أول خيار حتى لا يغيّر ملف .curlrc موجود مسبقًا سلوك هذا الاختبار الصغير.
تستخدم API الرسمية الحالية الإصدار 2026-10-21، وتدعم إرسال المفتاح عبر Authorization: Bearer. ويمكن لمفتاح مساحة العمل الواحدة إغفال ترويسة اختيار مساحة العمل.
افحص متن الاستجابة:
python3 -m json.tool response.jsonراجع النقاط التالية:
- هل حالة HTTP هي 200؟
- هل يحتوي content على محتوى نصي؟
- هل يشير stop_reason إلى انتهاء طبيعي أم إلى max_tokens؟
- كم من توكنات المدخلات والمخرجات والتخزين المؤقت أبلغت عنه usage فعليًا؟
ثم استخرج ترويسات الاستجابة اللازمة للمراجعة:
python3 - <<'PY'
from pathlib import Path
wanted = {
"request-id",
"anthropic-organization-id",
"anthropic-workspace-id",
}
for line in Path("response.headers").read_text(
errors="replace"
).splitlines():
name, sep, value = line.partition(":")
if sep and name.lower() in wanted:
print(name.lower() + ":", value.strip())
PYطابق معرفَي المؤسسة ومساحة العمل المعادَين مع سجلات Console. نجاح الطلب وصحة المؤسسة وتسجيل الاستخدام في مساحة العمل المطلوبة معًا تشكّل سلسلة تحقق مكتملة.
7. استخدم الرصيد نفسه عبر Python SDK
يمكنك استخدام Python SDK الرسمية لدمج API في برنامجك. تشترط الوثائق الحالية Python 3.10 أو أحدث.
أنشئ بيئة افتراضية داخل مجلد التدريب:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade anthropicأنشئ call_api.py:
import json
import os
import anthropic
with anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
base_url="https://api.anthropic.com",
timeout=30.0,
max_retries=0,
) as client:
raw = client.messages.with_raw_response.create(
model="claude-haiku-5-5",
max_tokens=128,
thinking={"type": "disabled"},
output_config={"effort": "low"},
messages=[
{"role": "user", "content": "أجب فقط: تم الاتصال بواجهة API بنجاح"}
],
)
message = raw.parse()
for name in (
"request-id",
"anthropic-organization-id",
"anthropic-workspace-id",
):
print(name + ":", raw.headers.get(name, "(لم تُرجع القيمة)"))
print("model:", message.model)
print("stop_reason:", message.stop_reason)
for block in message.content:
if block.type == "text":
print(block.text)
print(json.dumps(message.usage.model_dump(), ensure_ascii=False))شغّل:
python call_api.pyتحلل raw.parse() الاستجابة التي وصلت بالفعل، ولا ترسل طلبًا ثانيًا إلى النموذج. عُطلت إعادة المحاولة التلقائية لتسهيل مطابقة تنفيذ واحد بطلب واحد في التحقق الأول. ويمكن لنظام الإنتاج لاحقًا تصميم إعادة المحاولة حسب متطلبات العمل.
8. اضبط claude -p لاستخدام هذا الرصيد
تحدد الوثائق الرسمية شرط تغطية مهمًا:
يمكن استخدام المنحة الشهرية عندما تشغّل claude -p أو Agent SDK بنفسك وبمفتاح API من مؤسسة Console المرتبطة.
إذا سجلت الدخول بهوية اشتراك Claude، يظل الاستهلاك ضمن مخصصات الاشتراك. أما التشغيل الذي يبدأ من Claude Code GitHub Action أو إضافة IDE أو تطبيق Claude لسطح المكتب، فلا ينطبق عليه شرط التغطية المذكور، حتى لو استُخدم -p.
لذلك نفّذ هذا القسم في طرفية نظام مستقلة تفتحها بنفسك، مع مواصلة استخدام مفتاح API الذي أعددته أعلاه.
افحص الإصدار أولًا:
claude --versionيستخدم الدليل معرف نموذج Haiku 5.5 الكامل. وتشترط الوثائق الرسمية Claude Code v2.1.293 أو أحدث. إذا لم يكن مثبتًا أو كان أقدم، فاتبع تعليمات التثبيت والتحديث الرسمية المناسبة لطريقة تثبيتك.
يمكنك أولًا تشخيص مصدر المصادقة:
claude auth statusيساعد authMethod في مخرجات JSON الحالية على تحديد مصدر المصادقة، مثل api_key أو claude.ai أو third_party.
لكن api_key لا يدل إلا على التعرف إلى هذا المصدر. ولا يثبت منفردًا صلاحية المفتاح أو انتماءه إلى المؤسسة الصحيحة أو قيد المنحة في الرصيد.
ثم شغّل مهمة بالحد الأدنى:
claude --bare -p 'أجب فقط: تم الاتصال بواجهة API بنجاح' \
--model claude-haiku-5-5 \
--effort low \
--tools '' \
--max-turns 1 \
--max-budget-usd 0.10 \
--output-format json \
--no-session-persistence > claude-result.jsonما الذي تتحكم فيه هذه الخيارات؟
| الخيار | دوره في هذا التمرين |
|---|---|
| --bare | لا يقرأ OAuth أو سلسلة مفاتيح النظام، ويتجاوز الاكتشاف التلقائي لـ hooks وskills والإضافات وMCP وما شابه |
| -p | يعمل دون تفاعل ويخرج بعد إنتاج النتيجة |
| --model | يحدد النموذج بدل استخدام اختيار الجلسة اليومية |
| --effort low | يطلب جهد استدلال أقل |
| --tools '' | يعطّل الأدوات المدمجة للتحقق أولًا من الاستدعاء النصي فقط |
| --max-turns 1 | يحد جولات الوكيل |
| --max-budget-usd 0.10 | يحدد عتبة تقدير التكلفة على جانب العميل |
| --output-format json | يحفظ نتيجة منظمة قابلة للفحص |
| --no-session-persistence | لا يحفظ هذه الجلسة لاستئنافها لاحقًا |
يظل --bare داعمًا للإعدادات المحددة صراحة وبيانات اعتماد المنصات السحابية، ولذلك تبقى فحوص البيئة السابقة مهمة. لم تُمرر هنا إعدادات MCP أو إضافات أو مجلدات أخرى.
كما يعتمد --max-budget-usd على تقدير التكلفة لدى العميل، وليس ضمانًا صارمًا لاستحالة تجاوز الفاتورة للمبلغ. ولا يساوي --max-turns حدًا للتوكنات. اضبط ضوابط الإنفاق في Console قبل توسيع المهمة.
افحص النتيجة:
python3 - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("claude-result.json").read_text())
print("is_error:", data.get("is_error"))
print("result:", data.get("result"))
print("estimated_cost_usd:", data.get("total_cost_usd"))
print("usage:", data.get("usage"))
PYإذا لم يُرجع حقل، فاتركه مجهولًا ولا تملأه تلقائيًا بصفر. وإذا فشل الأمر، فراجع الخطأ القياسي وملف النتيجة أيضًا. غياب مخرجات خطوة التحليل لا يثبت عدم حدوث طلب.
9. تحقّق من صحة مسار الاستهلاك
بعد الاختبار الصغير، راجع بالترتيب:
- ملكية المفتاح صحيحة: أُنشئ في مؤسسة Console التي تستلم المنحة.
- مساحة العمل صحيحة: اختيرت المساحة المطلوبة عند إنشاء المفتاح، وتتطابق معها المعرفات المعادة من API.
- واجهة الاستدعاء صحيحة: API المباشرة، أو claude -p تشغّله بنفسك وفق الشروط الرسمية.
- سجل الاستخدام صحيح: يظهر هذا الاستخدام في Console ضمن مساحة العمل المتوقعة.
- سجل الرصيد صحيح: طابق Promotional credits والرصيد المشترى والمنح المقيدة والانتهاء.
عندما تمتلك المؤسسة رصيدًا ممنوحًا وآخر مشترى، تطبق المنصة قاعدة استخدام الممنوح أولًا. ولا تحتاج إلى إضافة معلمة منفصلة لكل طلب تعني «استخدم المنحة».
قد تتأخر التقارير في التحديث، كما قد تكون تكلفة الطلب الصغير ضئيلة جدًا. إذا لم يظهر فرق واضح في الواجهة فورًا، فلا تكرر التشغيل باستمرار لإجبار الأرقام على التغير.
10. استكشاف المشكلات الشائعة
| العَرَض | ما الذي تفحصه أولًا؟ |
|---|---|
| خيار API credits غير ظاهر | الخطة وأهلية السبعة أيام والهوية المسجل بها الدخول والأدوار على الجانبين |
| يمكن المطالبة بالرصيد لكن Create key غير متاح | دور Console وعضوية مساحة العمل وصلاحيات إنشاء المفتاح |
| HTTP 401 | هل المفتاح صحيح وصالح ومصدّر إلى الصدفة الحالية؟ |
| HTTP 403 | صلاحيات المفتاح ومساحة العمل والنموذج أو المورد |
| HTTP 400 | اقرأ نوع الخطأ المحدد وراجع معلمات الطلب والإصدار ومساحة العمل وقيود الإنفاق ذات الصلة |
| HTTP 402 / billing_error | فوترة المؤسسة والرصيد وحالة الدفع |
| HTTP 404 | معرف النموذج ونقطة النهاية وإتاحة المورد |
| HTTP 429 | ميّز حدود معدل الطلبات/التوكنات عن سقوف الإنفاق ذات الصلة، واقرأ تفاصيل الخطأ والاستجابة |
| stop_reason يساوي max_tokens | بلغت المخرجات سقفها؛ قد يكون الطلب نجح دون اكتمال المحتوى |
| يعمل curl ولا تعمل CLI | إصدار CLI وبيئة مفتاح API ومسار المزوّد/البوابة وسياسة المؤسسة |
| تعمل CLI ولا ينخفض الرصيد الممنوح بوضوح | شروط التغطية وصحة المؤسسة وتأخر التقارير أو دقة العرض |
لا تنسب كل خطأ إلى «عدم كفاية الرصيد». وبالمقابل، لا يعني بقاء الأموال أن سقف إنفاق المؤسسة أو ميزانية مساحة العمل أو حدود المعدل قد رُفعت.
ينبغي لمسؤولي Team تخصيص مساحات عمل وصلاحيات أعضاء مناسبة للمشاريع وضبط تنبيهات الإنفاق. لا تدعم Default Workspace حاليًا سقف إنفاق منفصلًا لمساحة العمل. وعند الحاجة إلى ميزانية مشروع، على المسؤول إنشاء مساحة API عادية مناسبة.
بعد انتهاء التدريب، امسح المفتاح من الجلسة الحالية ثم اخرج من Bash المؤقتة:
unset ANTHROPIC_API_KEY
exitتنتهي بذلك تعديلات البيئة المؤقتة في الصدفة الفرعية، وتبقى بيئة الطرفية الأم الأصلية محفوظة.
يمكنك تنزيل الأمثلة الكاملة أدناه لمراجعتها واستخدامها في مجلد تدريبك. خضعت الشيفرة لفحوص الصياغة ومسار العمل دون اتصال، ولم تُستخدم حسابات القراء لإرسال طلبات حقيقية إلى النماذج.