إذا كنت تبني تطبيق مصروفات أو تكاملاً مع نظام ERP أو مسار عمل للحسابات الدائنة، فأنت تحتاج بيانات الفاتورة بصيغة JSON، وتحتاج أن تعرف متى تكون خاطئة. يعيد API الفاصل الأمرين معاً.
طلب واحد، وJSON منظّم
curl https://alfasil.com/v1/documents \
-H "Authorization: Bearer $ALFASIL_KEY" \
-H "Content-Type: application/pdf" \
--data-binary @invoice.pdfتحصل فوراً على معرّف المستند، ويصلك Webhook موقّع من نوع document.processed عند اكتمال المعالجة (أو استعلم عبر GET /v1/documents/{id}).
ما الذي يميزه
- تحقق مدمج: كل استجابة تتضمن
warningsبرموز ثابتة (TOTAL_MISMATCHوTAX_ID_FORMATوDUPLICATE_INVOICE…) ورسائل بالعربية والإنجليزية. - مبالغ عشرية دقيقة بصيغة نصية، لا أرقام عائمة.
- العربية أولاً: الأرقام الهندية والتاريخ الهجري وعملات الخليج كلها موحّدة.
- مفاتيح Idempotency تجعل إعادة المحاولة آمنة.
- ملفات PDF متعددة الفواتير تُقسَّم إلى مستندات منفصلة.
الأمان
تُحفظ مفاتيح الـAPI بصيغة مشفّرة أحادية الاتجاه، وتُوقَّع كل Webhook بتوقيع HMAC مع طابع زمني، ولا يُكتب محتوى المستندات في سجلات النظام.
التوثيق
راجع توثيق الـAPI لنقاط النهاية، وكود التحقق من الـWebhook بلغتي Node.js وPython، ورموز الأخطاء، والمواصفة الكاملة بصيغة OpenAPI.