البناء على SolaBill API
Integrate ordinary invoice inputs, internal credit-note drafts, exact Orchida outcomes, incoming evidence, and ERP workflow through tenant-scoped client APIs. Regulated production access is not yet available.
خريطة التوثيق
ابدء
Step-by-step onboarding from authentication to draft creation and approved Orchida sandbox submission.
مرجع واجهة برمجة التطبيقات
Endpoint catalog, schemas, request/response examples, and status codes.
إشعارات الويب
بيانات الأحداث، والتحقق من التوقيع، وآلية إعادة المحاولة، وإرشادات المستهلك.
بيئة الاختبار
بيئة آمنة للتكامل لاختبار المسارات السعيدة والمسارات الفاشلة قبل بدء التشغيل.
أدوات تطوير البرامج (SDKs).
عملاء اللغة ومقتطفات البدء السريع لـ PHP وNode.js وPython.
سجل التغيير
ملاحظات الإصدار وتغييرات الإصدار وإرشادات التوافق.
تدفق التكامل
| خطوة | فعل | الإخراج |
|---|---|---|
| 1 | تسجيل الدخول عبر POST /api/v1/client/auth/login | رمز وصول Bearer |
| 2 | Create an invoice or credit-note draft | Internal customer-scoped draft; no regulated delivery claimed |
| 3 | Explicitly submit an invoice through an approved scoped Orchida sandbox connection | Exact provider result retained; credit-note submission remains blocked |
| 4 | Read separate provider-validation, Orchida invoice, authority and receiver states | Current Orchida-returned evidence without an invented exchange-success claim |
| 5 | Handle SolaBill webhooks and reconcile ambiguous outcomes before retry | Auditable application workflow without blind duplicate submission |
Customer API and Orchida Boundary
| Layer | Used by | Responsibility |
|---|---|---|
| SolaBill Client API | Customer ERP and approved client applications | Ordinary invoice inputs, drafts, workflow, customer-visible status and evidence access. |
| Internal Orchida Adapter | SolaBill server only | Maps approved requests to Orchida's contracted API and preserves exact provider responses. Orchida credentials are never exposed to customers. |
| Orchida Regulated Service | Appointed provider service | PINT-AE document generation, regulated validation, exchange and authority reporting, subject to contract, sandbox approval and production authorization. |
مهم: an accepted SolaBill API request is not presented as final delivery. Consumers must read the separate provider, exchange, authority and receiver outcomes returned through the integration.
أساسيات المصادقة
Every request must include an active client token and stay within authorized tenant/client boundaries. Unauthorized or cross-tenant access attempts are denied.
| منطقة | قاعدة | أولوية |
|---|---|---|
| استخدام الرمز المميز | يشمل Authorization: Bearer <token> في كل استدعاء نقطة النهاية المحمية. | شديد الأهمية |
| التحكم في النطاق | لا تقم أبدًا بإعادة استخدام الرموز المميزة عبر حسابات العملاء أو المستأجرين. | شديد الأهمية |
| تناوب | قم بتدوير بيانات الاعتماد بشكل دوري وقم بإلغاء الرموز المميزة المخترقة على الفور. | عالي |
أفضل ممارسات التكامل
- استخدم مفاتيح التكرار الآمن أو معرّفات مستندات أعمال فريدة عند تنفيذ عمليات إعادة المحاولة.
- تحقق من صحة بيانات الطلب في جهة العميل قبل الإرسال لتقليل تكرار استجابات 422.
- تنفيذ التراجع الأسي على الأخطاء العابرة مثل 429 و500 و503.
- احفظ أحداث إشعارات الويب وتعامل مع التكرارات بأمان.
- نفّذ اختبارات الانحدار في بيئة الاختبار قبل اعتماد تغييرات التكامل للإصدار.