الاستعلام والسجل

استرجاع فاتورة واحدة

GET /v1/invoices/{id}

{id} يقبل معرّف فواترا (inv_…) أو رقم الفاتورة في نظامك — ما يعني أنك لا تحتاج لتخزين معرّفنا إن لم ترغب.

curl https://fawtara.codexal.co/api/v1/invoices/INV-1001 \
  -H "Authorization: Bearer fwt_live_xxx"

سرد الفواتير

GET /v1/invoices

المعامل	النوع	الافتراضي	الوصف
`page`	integer	1	رقم الصفحة.
`limit`	integer	25	عدد العناصر، بحد أعلى 100.
`mode`	enum	وضع المفتاح	`live` أو `test`.
`status`	enum	—	`pending`, `accepted`, `rejected`, `error`.
`from` / `to`	date	—	نطاق `issue_date` بصيغة `YYYY-MM-DD`.
`invoice_number`	string	—	مطابقة تامّة لرقم الفاتورة.

curl "https://fawtara.codexal.co/api/v1/invoices?status=rejected&from=2026-10-01&limit=50" \
  -H "Authorization: Bearer fwt_live_xxx"

{
  "data": [ { "id": "inv_…", "status": "rejected", "...": "..." } ],
  "pagination": { "page": 1, "limit": 50, "total": 3, "total_pages": 1 }
}

إعادة الإرسال

POST /v1/invoices/{id}/retry

يُعيد إرسال نفس مستند UBL المخزّن إلى البوابة — دون إنشاء فاتورة جديدة ودون استهلاك حصّة إضافية. مفيد عند انقطاع مؤقّت في البوابة.

إعادة الإرسال لا تصحّح البيانات: المستند هو نفسه. إن كان الرفض سببه خطأ في البيانات (رقم ضريبي خاطئ مثلًا)، أنشئ فاتورة جديدة برقم جديد بعد التصحيح. الحد الأعلى 10 محاولات لكل فاتورة.

curl -X POST https://fawtara.codexal.co/api/v1/invoices/inv_5c8d1e9a2b7f3046/retry \
  -H "Authorization: Bearer fwt_live_xxx"

الحساب والاستهلاك

GET /v1/account

يُعيد بيانات المنشأة، الخطة، وحالة الجهوزية للإرسال الحقيقي:

{
  "data": {
    "object": "account",
    "id": "acc_3b91f0c2a7d4e856",
    "name": "شركة النور للتجارة",
    "tin": "40214600",
    "taxpayer_type": "sales",
    "plan": { "code": "growth", "name": "النمو", "invoice_quota": 1000, "rate_limit_per_min": 120 },
    "subscription_status": "active",
    "live_ready": true,
    "missing_setup": []
  }
}

GET /v1/usage

راقب هذه النقطة لتُنبّه مستخدميك قبل نفاد الحصة:

{
  "data": {
    "object": "usage",
    "period": "2026-10",
    "live": { "invoices": 412, "quota": 1000, "remaining": 588, "requests": 1203 },
    "test": { "invoices": 88, "quota": null, "requests": 310 },
    "rate_limit_per_min": 120,
    "resets_at": "2026-11-01"
  }
}

سجل التدقيق في اللوحة

إلى جانب الـ API، تُظهر لوحة التحكم لكل فاتورة: جسم الطلب الأصلي، مستند UBL المُرسل، وردّ البوابة الخام، مع تصدير CSV لكل السجل — وهو ما تحتاجه عند أي مراجعة ضريبية. مدّة الحفظ تتبع خطتك (90 يومًا في المجانية، سنة في النمو، خمس سنوات في الاحتراف).

→ الإشعارات الدائنة (المرتجعات) UBL ورمز QR ←