المصادقة ومفاتيح الـ API

صادِق كل طلب إلى ‎/v1‎ بمفتاح API سري يُرسل كرمز Bearer.

تستخدم واجهة تيرا باي مفاتيح API سرية. أرسل المفتاح في ترويسة Authorization مع كل طلب:

curl https://api.teyra.co/v1/payments \
  -H "Authorization: Bearer sk_test_4f9a..."

تفشل الطلبات التي لا تحمل مفتاحًا صالحًا بالخطأ 401 unauthorized. يجب أن تستخدم جميع الطلبات HTTPS.

أنواع المفاتيح

البادئة	الوضع	الاستخدام
`sk_test_`	الاختبار	للتطوير وبيئات التجربة. ينشئ مدفوعات تجريبية لا تنقل أي أموال. تحمل الكائنات القيمة `"livemode": false`.
`sk_live_`	الحي (Live)	للإنتاج والمدفوعات الحقيقية. تحمل الكائنات القيمة `"livemode": true`. يتطلب حسابًا معتمدًا.

المفتاح هو ما يحدد الوضع، والعنوان الأساسي (https://api.teyra.co) واحد للوضعين. بيانات الاختبار منفصلة تمامًا عن البيانات الحية، فلا يستطيع مفتاح الاختبار قراءة عملية دفع حية والعكس صحيح. راجع وضع الاختبار والوضع الحي.

إنشاء المفاتيح وإدارتها

تُدار المفاتيح من لوحة التحكم في المطورون ← مفاتيح API. يستطيع إدارة المفاتيح المستخدمون بدور المالك أو المسؤول أو المطوّر.

اضغط إنشاء مفتاح، وسمِّه (مثلًا production-web)، واختر اختبار أو حي. يُطلب منك إدخال كلمة المرور عند إنشاء مفتاح حي.
انسخ المفتاح السري فورًا. تحتفظ تيرا باي ببصمة المفتاح فقط وتعرضه كاملًا مرة واحدة. بعد ذلك تعرض اللوحة بادئته فقط، مثل sk_test_4f9a، وآخر وقت استُخدم فيه.
ضع المفتاح في مخزن الأسرار أو متغيرات البيئة على خادمك.

لتدوير مفتاح: أنشئ مفتاحًا جديدًا وانشره، وتأكد أن الطلبات تستخدمه (راجع آخر استخدام)، ثم ألغِ المفتاح القديم. يتوقف المفتاح الملغى عن العمل فورًا.

حافظ على أمان المفاتيح

المفاتيح السرية للخوادم فقط

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

استخدم مفتاحًا منفصلًا لكل نظام (الموقع، نظام ERP، الإضافة) حتى تستطيع إلغاء أحدها دون التأثير على الباقي.
أبقِ المفاتيح الحية بعيدًا عن أجهزة التطوير وسجلات أنظمة CI.
إذا تسرّب مفتاح، ألغِه فورًا من لوحة التحكم وأنشئ مفتاحًا جديدًا.

حدود معدل الطلبات

يستطيع كل مفتاح سري إرسال ما يصل إلى 1,200 طلب في الدقيقة إلى /v1. وتحمل كل استجابة الحالة الحالية للحد:

الترويسة	المعنى
`x-ratelimit-limit`	عدد الطلبات المسموح بها في الدقيقة.
`x-ratelimit-remaining`	الطلبات المتبقية في الدقيقة الحالية.
`x-ratelimit-reset`	الثواني المتبقية حتى تبدأ دقيقة جديدة.

عند تجاوز الحد تفشل الطلبات بالخطأ 429 rate_limited مع الترويسة Retry-After والقيمة details.retry_after_seconds. انتظر المدة المذكورة ثم أعِد المحاولة بمفتاح Idempotency-Key نفسه. إذا احتجت إلى حد أعلى، راسل support@teyra.co.

الأخطاء

الحالة	الرمز	المعنى
401	`unauthorized`	ترويسة `Authorization` مفقودة أو غير صحيحة، أو المفتاح ملغى أو غير معروف.
403	`forbidden`	المفتاح صالح لكنه لا يملك صلاحية تنفيذ هذا الطلب.
403	`merchant_not_active`	استُخدم مفتاح حي قبل اعتماد حسابك وتفعيله، أو الحساب موقوف. استخدم مفتاح اختبار حتى يُعتمد الحساب.
429	`rate_limited`	طلبات كثيرة بهذا المفتاح. راجع حدود معدل الطلبات.

راجع الأخطاء للقائمة الكاملة.