🧪 Sandbox Environment

A fully isolated environment mirroring production APIs. Test authentication, invoice submission, webhook delivery, error handling, and retry logic — all without affecting real data or Peppol network traffic.

عقد API متطابق بيانات الاختبار الآمنة محاكاة الفشل لا حدود للسعر إشعارات ويب فورية

🌐

عنوان URL الأساسي

تستخدم جميع استدعاءات واجهة API في بيئة الاختبار نفس عنوان URL الأساسي مع /api/v1/ prefix. Peppol transport is simulated — no real network messages are sent.

🔑

المصادقة

تسجيل الدخول عبر POST /api/v1/client/auth/login باستخدام بيانات الاعتماد التجريبية أدناه. يُعاد رمز Bearer في data.token.

🔄

دورة حياة البيانات

تُعاد تهيئة بيانات بيئة الاختبار كل 24 ساعة. صمّم اختباراتك بحيث تكون قابلة لإعادة التنفيذ دون آثار جانبية. وتُعاد تحميل البيانات الأولية في كل دورة إعادة تهيئة.

📡

مقلد بيبول

تتم معالجة الرسائل عبر محاكاة بيبول النقل — instant success or configurable failure, no real AS4 exchange.

🔐 Test Credentials

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

حساب واجهة برمجة تطبيقات العميل

بريد إلكتروني sandbox-client@solabill.test

كلمة المرور sandbox-pass-2026!

نقطة نهاية تسجيل الدخول POST https://solabill.com/api/v1/client/auth/login

حالة الحساب نشيط

الحساب الموقوف (لاختبار الأخطاء)

بريد إلكتروني suspended-client@solabill.test

كلمة المرور sandbox-pass-2026!

حالة الحساب معلق

مُتوقع المرتجعات 403 with error code account_suspending

💡

These credentials are for sandbox only. Production accounts are provisioned through the admin portal after completing the onboarding process.

⚡ Quick Start

ابدأ العمل في ثلاث خطوات:

الخطوة 1 - المصادقة

BASHcurl -X POST https://solabill.com/api/v1/client/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sandbox-client@solabill.test",
    "password": "sandbox-pass-2026!"
  }'

# Response:
# {
#   "data": {
#     "token": "1|abc123...",
#     "user": { "name": "Sandbox Client", "email": "sandbox-client@solabill.test" },
#     "account": { "company_name": "Sandbox Corp", "status": "active" }
#   }
# }

الخطوة 2 - إنشاء فاتورة

BASHcurl -X POST https://solabill.com/api/v1/client/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-SANDBOX-001",
    "recipient_id": "0192:sandbox-buyer",
    "amount": 5250.00,
    "currency": "AED",
    "issue_date": "2026-02-12",
    "due_date": "2026-03-12"
  }'

# Response includes invoice ID and dispatched Peppol message

الخطوة 3 - التحقق من حالة الرسالة

BASHcurl https://solabill.com/api/v1/client/messages \
  -H "Authorization: Bearer YOUR_TOKEN"

# Returns paginated list of Peppol messages with delivery status

🧪 Test Scenarios

قم بتغطية هذه السيناريوهات قبل الذهاب إلى الإنتاج:

سيناريو	كيفية الاختبار	النتيجة المتوقعة	رمز الحالة
تسجيل دخول ناجح	نشر بيانات اعتماد صالحة	رمز في `data.token`	200
بيانات اعتماد غير صالحة	نشر كلمة مرور خاطئة	خطأ مع `valid_credentials`	401
حساب معلق	تسجيل الدخول بحساب معلق	خطأ مع `account_suspending`	403
Expired / revoked token	استخدم رمز Bearer قديمًا أو تم إبطاله	خطأ مع `unauthenticated`	401
أخطاء التحقق من الصحة	إرسال الفاتورة دون الحقول المطلوبة	تفاصيل الخطأ على مستوى الحقل	422
إنشاء فاتورة	POST بيانات طلب فاتورة صحيحة	تم إنشاء الفاتورة + PeppolMessage	201
إنشاء مذكرة الائتمان	POST بيانات طلب صحيحة لإشعار ائتمان	تم إنشاء مذكرة الائتمان + PeppolMessage	201
تسجيل مشارك	معرف مشارك POST	مشارك مسجل للمستأجر	201
حذف المشارك	حذف المشارك حسب الهوية	تمت إزالة المشارك	200
تغيير كلمة المرور	POST الحالية + كلمة المرور الجديدة	تأكيد تحديث كلمة المرور	200
قائمة مرقّمة	احصل على الفواتير مع `?page=2&per_page=5`	الرد مع `pagination` هدف	200
الحد من المعدل	تجاوز حد الطلب عند تسجيل الدخول	`إعادة المحاولة بعد` مجموعة رأس	429
تسليم إشعارات الويب	أنشئ فاتورة مع تفعيل اشتراك إشعار الويب	تم استلام طلب POST لإشعار الويب على عنوان URL الخاص بك	N/A

⚖️ Sandbox vs Production

ميزة	بيئة الاختبار	إنتاج
بيبول للنقل	`محاكاة بيبول النقل` — instant, no network	`httpPeppolTransport` — real AS4 over TLS 1.2+
التحقق من صحة الشهادة	تم التخطي - تم قبول شهادات الاختبار	التحقق الكامل من صحة سلسلة Peppol PKI
عمليات بحث SMP	ردود ساخرة	SML الحقيقي → SMP الاكتشاف القائم على DNS
حدود المعدل	استرخاء (عتبات أعلى)	مفروض لكل طبقة: `واجهة برمجة التطبيقات الافتراضية`, `تقديم واجهة برمجة التطبيقات`, `مصادقة واجهة برمجة التطبيقات`
تسليم إشعارات الويب	فوري، لا يوجد إنفاذ للتوقيع	تم توقيع HMAC SHA-256، أعد المحاولة مع التراجع الأسي
ثبات البيانات	يتم إعادة الضبط كل 24 ساعة	دائم مع سياسات النسخ الاحتياطي وDR
التقارير الضريبية	تنجح التقديمات ولكنها لا تصل إلى اتفاقية التجارة الحرة	التقديم المباشر للهيئة الاتحادية للضرائب
تنسيق استجابة واجهة برمجة التطبيقات	متطابق - نفس مغلف JSON	متطابق - نفس مغلف JSON

⚠️

مهم: Never use sandbox credentials in production. Production API tokens are issued through the client onboarding process and managed via the client portal's API Keys page.

📦 Sample Data

يأتي صندوق الحماية محملاً مسبقًا ببيانات الاختبار التالية بعد كل عملية إعادة تعيين:

🧾

25 Invoices

مزيج من الحالات: مسودة، مرسل، تم تسليمه، وفاشل. مبالغ مختلفة بالدرهم الإماراتي والدولار الأمريكي واليورو.

📄

10 Credit Notes

مرتبطة بالفواتير الموجودة. سيناريوهات الائتمان الجزئي والكامل.

👥

8 Participants

معرفات Peppol المسجلة مسبقًا بمعرفات المخططات المختلفة (0192, 0195, 0151).

📬

15 Peppol Messages

الرسائل الصادرة والواردة في حالات مختلفة لدورة الحياة: في قائمة الانتظار، وتم التسليم، والفشل.

📥

5 Inbox Documents

محاكاة مستندات Peppol الواردة من الشبكة.

🔔

2 Webhook Subscriptions

عناوين URL مُعدّة مسبقًا لإشعارات الويب مع سجلات تاريخ التسليم.

🔬 Interactive API Explorer

Try API calls directly from this page. Authorize with the test credentials above, then expand any endpoint to send requests.

🔑

كيفية المصادقة في المستكشف:

أولاً، استخدم POST /client/auth/login نقطة النهاية أدناه للحصول على رمز مميز
انقر فوق الأخضر يأذن 🔒 button at the top of the explorer
يدخل: Bearer YOUR_TOKEN (include the word Bearer)
انقر يأذن then يغلق
ستتضمن جميع الطلبات اللاحقة الرمز المميز الخاص بك تلقائيًا

1. Login → Get Token

→

2. Click Authorize 🔒

→

3. Paste Bearer Token

→

4. Expand Endpoint

→

5. Try It Out

→

6. Execute ▶

✅ Pre-Production Checklist

قبل التبديل من وضع الحماية إلى الإنتاج، تحقق من كل ما يلي:

☐
تدفق المصادقة — Login, token storage, refresh/re-login on 401, logout
☐
إنشاء الفاتورة — Valid payloads accepted (201), invalid payloads rejected (422)
☐
إنشاء مذكرة الائتمان — Linked to invoices, correct amounts and references
☐
إدارة المشاركين — Register, list, and delete participants
☐
تتبع الرسائل — Poll message status and handle all lifecycle states
☐
ترقيم الصفحات — Handle has_more, current_page, last_page بشكل صحيح
☐
معالجة الأخطاء — Parse error envelope (error.code, خطأ.رسالة, تفاصيل الخطأ)
☐
التعامل مع حد المعدل — Respect 429 responses and إعادة المحاولة بعد header
☐
التحقق من إشعار الويب — Validate HMAC signature, reject stale/duplicate events
☐
العجز — No duplicate invoices/credit notes on retries
☐
طلب التتبع — Log معرف طلب X رأس من الردود على تذاكر الدعم
☐
مبادلة عنوان URL الأساسي — Update from sandbox URL to production URL in config (not hardcoded)

🚀

بمجرد التحقق من جميع عناصر قائمة التحقق، اتصل بمدير حسابك أو البريد الإلكتروني support@solabill.ae to request production API credentials.