توثيق الـ API

اربط أنظمتك ببوابة نبتة: اقرأ المنتجات والمدفوعات، أنشئ طلبات دفع، واقرأ الأرصدة.

الرابط الأساسي

https://api.nbta.sbarah.com/v1

المصادقة

كل طلب يحتاج مفتاح API للمنظمة يُرسَل كـ Bearer token. أنشئ مفتاحاً من لوحة التحكم ضمن الإعدادات ثم المطوّرون. احتفظ به سراً مثل كلمة المرور، نحن نخزّن نسخة مُجزّأة فقط.

بداية سريعة

curl https://api.nbta.sbarah.com/v1/account \
  -H "Authorization: Bearer nbta_sk_live_xxx"

الوجهات

الطريقة	المسار	الصلاحية	الوصف
GET	/v1/account	account:read	معلومات الحساب، وطريقة بسيطة لاختبار المفتاح.
GET	/v1/products	products:read	عرض منتجاتك.
GET	/v1/products/{id}	products:read	جلب منتج واحد عبر المعرّف.
POST	/v1/checkouts	payments:write	إنشاء طلب دفع مستضاف لمنتج والحصول على رابط للمشتري.
GET	/v1/payments	payments:read	عرض مدفوعاتك، الأحدث أولاً.
GET	/v1/payments/{invoiceId}	payments:read	جلب دفعة واحدة عبر رقم الفاتورة.
GET	/v1/balances	balances:read	إجماليات التسوية على السلسلة لمنظمتك.

مثال: إنشاء طلب دفع

curl -X POST https://api.nbta.sbarah.com/v1/checkouts \
  -H "Authorization: Bearer nbta_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024" \
  -d '{ "product_id": "f2098c0c-...", "chain": "bsc" }'

{
  "invoice_id": "inv_...",
  "status": "pending",
  "checkout_url": "https://pay.nbta.sbarah.com/checkout/inv_..."
}

الويب هوك

حدّد رابط ويب هوك من لوحة التحكم ضمن الإعدادات ثم المطوّرون. عند تأكيد أي دفعة نرسل إشعار JSON عبر POST إليه.

POST <your endpoint>
X-Nbtaget-Signature: <hmac>
X-Nbtaget-Timestamp: <unix seconds>

{
  "payment_id": "...",
  "invoice_id": "...",
  "amount_usdt": 2,
  "status": "confirmed",
  "tx_hash_final": "0x...",
  "confirmed_at": "2026-05-30T..."
}

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

الأخطاء

تستخدم الأخطاء صيغة RFC 7807 مع جسم JSON. الحالات الشائعة: 401 (لا مفتاح أو مفتاح خاطئ)، 403 (صلاحية ناقصة)، 404 (غير موجود)، 422 (جسم غير صالح)، 429 (تجاوز الحد).

{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Key lacks the payments:write scope.",
  "request_id": "req_..."
}

مواصفة OpenAPI

المواصفة الكاملة القابلة للقراءة آلياً متاحة للاستيراد في Postman أو Insomnia أو مولّد كود.

تنزيل openapi.json