كيف تدمج المرحلة الثانية لزاتكا في Node.js (دليل كامل)

ماذا تتطلب المرحلة الثانية لزاتكا

تتطلب المرحلة الثانية (فاتورة) من نظامك:

1. تسجيل وحدة EGS — توليد مفاتيح ECDSA، بناء CSR بمعرّفات زاتكا، فحص امتثال بثلاث فواتير، والحصول على CSID إنتاج.
2. إصدار الفواتير — بناء UBL 2.1 XML وفق الملف السعودي، صيانة سلسلة PIH، التوقيع بالمفتاح الخاص، والإرسال لزاتكا للإخلاء (B2B) أو الإبلاغ خلال 24 ساعة (B2C).
3. رمز QR — توليد QR بترميز TLV (9 وسوم، ثنائي، base64، حد أقصى 700 حرف) لكل فاتورة.

بناؤه بنفسك يستغرق أسابيع. بوسيط مثل إسناد يمكنك الإطلاق في فترة قصيرة.

الخيار 1: ابنِه بنفسك

ستحتاج إلى تنفيذ:

• توليد مفاتيح ECDSA (secp256k1) مع OIDs زاتكا في CSR
• توليد UBL 2.1 XML بكل نطاقات الأسماء السعودية وترتيب الحقول الصحيح
• هاش SHA-256 قانوني وصيانة سلسلة PIH
• ترميز QR بـ TLV (9 وسوم، صيغة صارمة)
• منطق إعادة المحاولة وطابور لانقطاع زاتكا
• مراقبة انتهاء الشهادات وتدفق التجديد

الخيار 2: استخدم واجهة إسناد

مع إسناد ترسل JSON وتستلم فاتورة مُخلاة مع UUID ورمز QR:

const response = await fetch('https://api.esnadapi.com/v1/invoices/simplified', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer zatca_live_xxxxxxxxxxxx',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    egs_unit_id: 'egs_abc123',
    invoice_number: 'INV-2026-001',
    invoice_date: '2026-01-15',
    seller: { name: 'Your Company', vat_number: '310122393500003' },
    line_items: [{ description: 'Item', quantity: 1, unit_price: 100, vat_category: 'S' }],
    currency: 'SAR'
  })
});
const data = await response.json();
// data.uuid, data.qr_code, data.status

الاختبار في sandbox

كل حساب إسناد يحصل على بيئة تجربة. استخدم مفاتيح تبدأ بـ zatca_test_ للوصول إلى محاكاة زاتكا. لا تحتاج بيانات فاتورة لإنشاء وحدات EGS في sandbox.

أخطاء شائعة

• OTP غير صالح — رموز فاتورة تنتهي خلال ~5 دقائق. أنشئها والصقها بسرعة.
• عدم تطابق PIH — لا تتخطَّ فواتير أو تعيد ترتيبها؛ السلسلة يجب أن تكون متتابعة.
• QR طويل جداً — للفواتير المبسّطة حد 700 حرف؛ نحن نتولى الاختصار.

---

تجاوز التعقيد. استخدم واجهة إسناد. ابدأ مجاناً — 14 يوماً ←