سجل تغييرات الواجهة البرمجية

نوفمبر 2026

• فاتورة تصل مدفوعة: الحقل الاختياري payment في POST /invoices يسجل الدفعة مع إصدار الفاتورة، لمن يستلم الدفع عبر بوابته قبل الفاتورة. يحتاج صلاحية payments:write. التفاصيل.
• نقطتا نهاية جديدتان: GET /invoices/{id}/payments وPOST /invoices/{id}/payments.
• رمزا خطأ جديدان: invoice_not_payable (409) وpayment_exceeds_balance (422).
• تغيير إضافي: لا يتأثر أي ربط قائم إذا لم يتغير.

أكتوبر 2026

• نشر توثيق المطورين على /developers بالعربية والإنجليزية، ومستند OpenAPI 3.1 على /developers/openapi.json.
• نقاط نهاية جديدة: ملف المنشأة وجاهزيتها، والعملاء، وعرض الفواتير وحالتها وفحصها وإصدارها وتنزيل PDF و XML، والإشعارات الدائنة والمدينة.
• صلاحيات جديدة: companies:read وcustomers:read وcustomers:write وinvoices:draft وinvoices:download وwebhooks:manage. وتستمر المفاتيح التي تحمل invoices:write في العمل.
• ترويسة Idempotency-Key لكل عمليات الكتابة.
• Webhooks موقّعة وGET /events.
• منشآت اختبار بمفاتيح اختبار (wbk_test_…) ونتائج محاكاة للهيئة.
• ربط التطبيقات عبر OAuth 2.1، وWonder Fatoora MCP لوكلاء الذكاء الاصطناعي.
• أدوات MCP للمنتجات والخدمات (search_products وget_product وcreate_product وupdate_product) ولدفعات العملاء (record_payment وlist_invoice_payments)، مع الصلاحيات الجديدة products:read وproducts:write وpayments:write.
• حدود طلبات لكل منشأة حسب الباقة، مع حصص مستقلة للإصدار والتنزيل.
• مفتاح API المنتهي يجيب بـ 401 token_expired مع details.expired_at وdetails.renew_url، وبقية حالات الرفض كما هي. ويُرسل بريد تذكير قبل انتهاء مفتاح التشغيل بـ14 يومًا ثم بـ3 أيام.

سبتمبر 2026

• المفاتيح تحمل صلاحيات: invoices:read وinvoices:write وinvoices:issue. الإصدار يحتاج invoices:issue.
• المفاتيح تنتهي (30 أو 90 أو 180 أو 365 يومًا) ويمكن تجديدها.
• حدود طلبات لكل مفتاح: 60 طلبًا في الدقيقة و5,000 في اليوم، مع الرد 429 rate_limited وRetry-After.
• الفواتير تتضمن كائن zatca: المسار والحالة والتحذيرات والمعرّف الفريد وإمكانية التسليم ورسائل الهيئة.
• المسودات تحمل مرجع DRAFT-… وnumber_is_final: false، والرقم النظامي يُمنح عند الإصدار.
• البنود تقبل vat_exemption_code وvat_exemption_reason للعمليات الخاضعة للنسبة الصفرية والمعفاة.
• external_reference يجعل إنشاء الفواتير آمنًا عند إعادة المحاولة.

يوليو 2026

• فواتير بعملتي USD وAED مع exchange_rate إلى الريال.

يونيو 2026

• الواجهة البرمجية v1: GET /ping وPOST /invoices وGET /invoices/{id}.

القادم

حزم SDK الرسمية جاهزة ومختبرة، ولم تُنشر بعد.