أخطاء API ورموز الحالة
ما يعنيه كل رمز حالة HTTP ورمز خطأ من واجهة API في عليا بوكس وكيفية التعامل معه.
كل خطأ في API هو نص JSON بالشكل نفسه، لذا يكفي معالج واحد لتغطيتها جميعاً:
{ "code": "E_VALIDATION", "statusCode": 400, "message": "…", "field": "items", "extra": { … } }
code هو السبب المقروء آلياً، ويشير field إلى المدخل المخالف عند وجوده، ويحمل extra تفاصيل مثل أخطاء PINT AE أو نتائج الدفعات.
رموز الحالة
| الحالة | الرمز | المعنى | ما يجب فعله |
|---|---|---|---|
| 400 | E_VALIDATION | الحمولة غير صالحة أو الفاتورة لا تجتاز فحص PINT AE | صحّح الحقل المذكور في field؛ واقرأ extra.errors لمعرفة مصطلحات الأعمال |
| 401 | UNAUTHORIZED | مفتاح مفقود أو مشوّه أو غير معروف أو مُبطل أو منتهي الصلاحية | راجع مقالة 401 |
| 403 | FORBIDDEN | المفتاح يفتقر إلى النطاق، أو X-Organization-Id ليس عميلاً مُداراً | أنشئ مفتاحاً بالنطاقات الصحيحة |
| 404 | NOT_FOUND | لا توجد فاتورة أو عملية استيراد أو عميل أو ملف بهذا المعرّف | تحقق من المعرّف |
| 409 | CONFLICT | الإجراء غير مسموح به في الحالة الحالية، مثل حذف فاتورة مقبولة أو إعادة استخدام SKU | غيّر الحالة أولاً (الأرشفة بدلاً من الحذف) |
| 413 | PAYLOAD_TOO_LARGE | الملف المرفوع يتجاوز 20 ميغابايت | قسّمه أو اضغطه |
| 422 | E_VALIDATION | فشل التحقق من مستند مستلم عند الاستيراد | يُسجَّل الاستيراد؛ اقرأ extra.validation |
| 429 | RATE_LIMITED | أكثر من 600 طلب في الدقيقة لهذا المفتاح | انتظر عدد الثواني المذكور في Retry-After |
| 503 | SERVICE_UNAVAILABLE | طُلب ملف PDF لعرض فاتورة واردة في بيئة لا توجد فيها خدمة تحويل HTML إلى PDF (ملفات PDF للفواتير والإشعارات الدائنة والمدينة والفواتير المبدئية تعمل دائماً) | اطلب ?format=html أو xml |
| 500 | INTERNAL_SERVER_ERROR | فشل غير متوقع | أعد المحاولة؛ وتواصل مع support@alyabooks.ai مع ذكر X-Request-Id |
الدفعات
عندما تفشل فاتورة واحدة في دفعة، تأخذ الاستجابة حالة أول فشل (عادةً 400) ويسرد extra.results كل عنصر مع index وsuccess والخطأ الخاص به. العناصر التي تحمل success: true أُنشئت؛ فأعد المحاولة للعناصر الأخرى فقط.
معلومات مفيدة
- تحمل كل استجابة
X-Request-Id، وتكرره رسائل الخطأ في الحقلrequestId. وتعرض علامة التبويب Recent requests (الطلبات الأخيرة) في صفحة API access المعرّف نفسه تحت كل طلب مع الحالة والتوقيت. - تُعاد محاولة تسليم webhooks بعد دقيقة و5 دقائق و30 دقيقة وساعتين و12 ساعة على الأقل (ترسل إعادات المحاولة مهمةٌ تعمل كل 5 دقائق)؛ ويعرض مربع حوار عمليات التسليم المحاولات ويتيح لك إعادة المحاولة يدوياً.