SolaBill API الشروع في العمل

Integrate ordinary ERP or billing data in a few steps: authenticate, create invoice drafts, explicitly use an approved Orchida sandbox connection, and monitor separate provider outcomes.

واجهة برمجة التطبيقات v1 مصادقة الرمز المميز تم تمكين إعادات محاولة إشعارات الويب

المتطلبات الأساسية

Regulated production access is not currently available. Before testing provider submission, complete the controlled client and Orchida sandbox onboarding gates.

متطلبات	وصف	حالة
بيانات اعتماد مستخدم العميل	Active email/password for API login	مطلوب
Buyer Profile	Ordinary customer routing, address and payment inputs required by the provisional Orchida mapper	مطلوب
Scoped Orchida Sandbox Connection	API-reachable current credential with Orchida company-scope evidence; no shared provider credentials	Required for submission
نقطة نهاية إشعار الويب	نقطة نهاية HTTPS عامة لاستقبال النداءات الراجعة	مُستَحسَن
Sandbox Acceptance	Run and retain approved scenarios; SolaBill input checks are not PINT-AE validation	Required before production

المصادقة

احصل على رمز الوصول وقم بتمريره في Authorization: Bearer <token> header.

curl -X POST "https://solabill.com/api/v1/client/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "client.user@example.com",
    "password": "password",
    "device_name": "erp-connector"
  }'

{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "1|sample-token-value",
    "token_type": "Bearer"
  }
}

Create an invoice draft, then test the approved Orchida sandbox

First create a draft with ordinary business data. Keep رقم الفاتورة unique per client account.

curl -X POST "https://solabill.com/api/v1/client/invoices" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2026-1001",
    "recipient_name": "Acme LLC",
    "recipient_peppol_id": "123456789000003",
    "buyer_endpoint_scheme": "0235",
    "buyer_street": "Sheikh Zayed Road",
    "buyer_city": "Dubai",
    "buyer_subdivision": "DXB",
    "buyer_country": "AE",
    "issue_date": "2026-02-12",
    "issue_time": "09:30",
    "due_date": "2026-03-12",
    "currency": "AED",
    "total_amount": 105.00,
    "payment_means_code": "48",
    "items": [{
      "item_code": "SERVICE-1", "name": "Consulting", "description": "Professional consulting service",
      "unit_code": "C62", "quantity": 1, "base_quantity": 1,
      "net_unit_price": 100, "gross_unit_price": 100, "discount_amount": 0,
      "vat_category": "S", "vat_rate": 5
    }]
  }'

curl -X POST "https://solabill.com/api/v1/client/invoices/{invoiceId}/submit-orchida" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

This second call is unavailable without an active, reachable, company-scope-confirmed Orchida connection in the selected sandbox environment. It must not be presented as production access.

التحقق

يتم التحقق من صحة بيانات الطلب قبل الحفظ. تعيد الحقول غير الصالحة استجابة HTTP 422 مع رسائل على مستوى الحقل.

Responsibility

SolaBill captures and maps business inputs. Orchida creates and validates the regulated document and handles exchange and reporting.

استراتيجية العجز

Repeat the submit call with the unchanged draft safely; SolaBill uses a deterministic payload key and retains the provider result.

Track Orchida status

Read the invoice detail to see provider validation, Orchida invoice, tax-authority and receiver states separately.

curl -X GET "https://solabill.com/api/v1/client/invoices/{invoiceId}" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

حالة	معنى	فعل
submission_state	Orchida request validation result	Fix provider errors if rejected
provider_invoice_state	Canonical view of Orchida's top-level invoice status; not independent proof of network exchange	Wait while pending or submitted and inspect the exact provider_status
tax_authority_state	Tax-authority outcome returned by Orchida	Do not infer from HTTP success
receiver_state	Receiver outcome returned by Orchida	Reconcile separately

تدفق إشعارات الويب

Subscribe to SolaBill customer webhooks for application events. Orchida provider-webhook semantics remain unconfirmed; do not assume every regulated state is event-driven or real-time.

أنشئ اشتراك إشعار ويب من حساب العميل الخاص بك.
تحقق من التواقيع في طلبات النداء الراجع الواردة.
قم بإرجاع HTTP 2xx بسرعة وقم بالمعالجة بشكل غير متزامن في نظامك.
التعامل مع عمليات إعادة المحاولة لعمليات التسليم المكررة بأمان.

الأخطاء وإعادة المحاولة

رمز HTTP	يكتب	إرشادات التعامل
400	اقتراح غير جيد	أصلح بنية بيانات الطلب وأعد المحاولة بعد التصحيح.
401	غير مصرح به	قم بتحديث رمز تسجيل الدخول ثم أعد المحاولة.
403	مُحرَّم	التحقق من أذونات الحساب ونطاق المستأجر.
422	خطأ في التحقق	فحص الأخطاء الميدانية وتصحيح تعيين المصدر.
429	معدل محدود	تطبيق التراجع الأسي والارتعاش.
500/503	Server/transient	أعد المحاولة مع التراجع؛ تنبيه إذا تكررت.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "invoice_number": ["The invoice number field is required."]
  }
}

اذهب إلى قائمة التحقق المباشرة

Validate every ordinary business input assigned to SolaBill by the signed Orchida field matrix; Orchida owns the 51-field/PINT-AE compliance layer.
قم بتأكيد حدود نطاق المستأجر والعميل في كل استدعاء لواجهة برمجة التطبيقات.
Run approved Orchida sandbox tests for happy, rejection, duplicate, timeout, delayed-status, incoming-outage and recovery paths.
Confirm credit-note submission remains blocked until its separate Orchida contract and sandbox flow are approved.
فعّل التنبيهات عند فشل إشعارات الويب، وتأخر قائمة الانتظار، وارتفاع أخطاء API من فئة 5xx.
قم بمراجعة سجل التغيير قبل نشر كل إصدار.

العودة إلى الصفحة الرئيسية للمطورين