البدء مع الواجهة البرمجية

عقد OpenAPI المرجعي يُقدّمه الخادم على /v1/openapi.yaml، وواجهة Swagger على /v1/docs.

البيئات

المرحلة	الرابط الأساسي	OpenAPI	Swagger UI
محلي	http://localhost:3000/v1	http://localhost:3000/v1/openapi.yaml	http://localhost:3000/v1/docs
الإنتاج	https://api.roundworld.sy/v1	https://api.roundworld.sy/v1/openapi.yaml	https://api.roundworld.sy/v1/docs

البوابة: https://roundworld.sy · الإدارة: https://admin.roundworld.sy · الوثائق: https://docs.roundworld.sy

تدفق المصادقة

يقبل جسم تسجيل الدخول identifier أو email (الجوال يرسل identifier).

LOGIN=$(curl -sS https://api.roundworld.sy/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"identifier":"owner@example.com","password":"Passw0rd!"}')

ACCESS_TOKEN=$(printf '%s' "$LOGIN" | jq -r .access_token)

أرسل الرمز مع الطلبات المحمية:

curl -sS https://api.roundworld.sy/v1/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

رموز الوصول JWT قصيرة العمر. استخدم رموز التحديث للجلسات الطويلة. مسارات النطاق التجاري تتطلب عضوية نشطة؛ تُطبَّق الصلاحيات في الوسيط كـ <module>.<action>.

حزم SDK

تُولَّد حزم TypeScript وDart وPHP من مواصفة OpenAPI.

pnpm sdk:generate

أمثلة التثبيت بعد النشر:

pnpm add @tadbeer/sdk
dart pub add tadbeer_sdk
composer require tadbeer/sdk

المسودة مقابل الترحيل

نقاط CRUD تنشئ وتحرّر المسودات. انتقالات الحالة (إصدار فاتورة، ترحيل دفعة، إرسال تحويل، إلغاء) تستخدم إجراءات ترحيل مخصصة. الصفوف المُرحَّلة لا تُحذف — الإلغاءات تُدرج قيوداً وحركات مخزون عكسية.

شكل الخطأ

تُعاد الأخطاء ككائن JSON يحتوي على سلسلة error ورمز HTTP المناسب.

{ "error": "permission denied" }