دليل ربط API زاتكا (المرحلة الثانية) للمطوّرين

المرحلة الثانية من الفوترة الإلكترونية (مرحلة الربط والتكامل) تتطلب من المنشآت ربط أنظمة الفوترة مع منصة فاتورة التابعة لهيئة الزكاة والضريبة والجمارك (زاتكا). يشمل ذلك التوقيع الإلكتروني، وبناء ملفات XML بمعيار UBL 2.1، والإرسال عبر API.

هذا الدليل يشرح كل خطوة بالتفصيل مع أمثلة كود. إذا كنت تريد تخطي التعقيد، Jibrid يتولى كل هذا من خلال API واحد.

١. آلية العمل

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

1. بناء ملف XML بمعيار UBL 2.1 مع جميع الحقول المطلوبة
2. توقيع الملف إلكترونياً باستخدام المفتاح الخاص وشهادة الإنتاج
3. إرسال الفاتورة لمنصة فاتورة (اعتماد للفواتير الضريبية B2B، إبلاغ للمبسطة B2C)

٢. إنشاء شهادة CSR

قبل التسجيل في منصة فاتورة، تحتاج إنشاء طلب توقيع شهادة (CSR) باستخدام خوارزمية ECDSA على منحنى secp256k1.

# إنشاء المفتاح الخاص
openssl ecparam -name secp256k1 -genkey -noout -out private-key.pem

# إنشاء CSR مع الحقول المطلوبة من زاتكا
openssl req -new -sha256 -key private-key.pem \
  -out taxpayer.csr \
  -subj "/C=SA/OU=رقم_الضريبي/O=اسم_الشركة/CN=اسم_الجهاز"

٣. التسجيل والحصول على CSID

بعد إنشاء CSR، ترسله لـ API زاتكا للحصول على شهادة المطابقة (CCSID)، ثم تجري اختبارات المطابقة، وأخيراً تطلب شهادة الإنتاج (PCSID).

// الخطوة ١: الحصول على شهادة المطابقة
const response = await fetch(
  'https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/compliance',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'OTP': '123456', // من بوابة فاتورة
      'Accept-Version': 'V2',
    },
    body: JSON.stringify({ csr: base64CSR }),
  }
);

const { binarySecurityToken, secret } = await response.json();

٤. بناء ملف XML (UBL 2.1)

زاتكا تتطلب الفواتير بصيغة UBL 2.1 XML. الملف يجب أن يحتوي على:

٥. التوقيع الإلكتروني

كل فاتورة يجب توقيعها باستخدام شهادة الإنتاج. العملية تشمل:

1. تطبيع XML باستخدام C14N (Canonical XML)
2. تجزئة الملف بخوارزمية SHA-256
3. توقيع التجزئة بالمفتاح الخاص (ECDSA)
4. تضمين التوقيع كامتداد UBL (بمعيار XAdES-BES)

import { createSign, createHash } from 'crypto';

// ١. تطبيع XML
const canonicalized = canonicalize(invoiceXml);

// ٢. تجزئة SHA-256
const hash = createHash('sha256')
  .update(canonicalized)
  .digest('base64');

// ٣. التوقيع بـ ECDSA
const sign = createSign('SHA256');
sign.update(canonicalized);
const signature = sign.sign(privateKey, 'base64');

٦. رمز QR

الفواتير المبسطة (B2C) تتطلب رمز QR يحتوي على بيانات مشفرة بنظام TLV تشمل: اسم البائع، الرقم الضريبي، التاريخ، المبلغ، الضريبة، التجزئة، والتوقيع.

function encodeTLV(tag: number, value: string | Buffer): Buffer {
  const tagBuf = Buffer.from([tag]);
  const valBuf = typeof value === 'string'
    ? Buffer.from(value, 'utf-8') : value;
  const lenBuf = Buffer.from([valBuf.length]);
  return Buffer.concat([tagBuf, lenBuf, valBuf]);
}

const qrPayload = Buffer.concat([
  encodeTLV(1, sellerName),
  encodeTLV(2, vatNumber),
  encodeTLV(3, timestamp),
  encodeTLV(4, totalWithVat),
  encodeTLV(5, vatAmount),
]);

٧. الإرسال لمنصة فاتورة

بعد التوقيع، ترسل الفاتورة لـ API فاتورة:

// فواتير B2C: نقطة الإبلاغ
const response = await fetch(
  'https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal/invoices/reporting/single',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Basic ${credentials}`,
      'Accept-Version': 'V2',
    },
    body: JSON.stringify({
      invoiceHash: hash,
      uuid: invoiceUuid,
      invoice: base64SignedXml,
    }),
  }
);

٨. الطريقة الأسهل: Jibrid

كل ما سبق — من إنشاء الشهادات إلى بناء XML والتوقيع وإنشاء QR والإرسال — يتم من خلال API واحد في Jibrid:

curl -X POST https://api.jibrid.com/v1/zatca/invoices \
  -H "Authorization: Bearer jbr_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_type": "simplified",
    "customer": { "name": "أحمد", "vat_number": "300000000000003" },
    "items": [
      { "name": "استشارات", "quantity": 1, "unit_price": 1000, "tax_rate": 15 }
    ]
  }'

Jibrid يبني XML، يوقّع إلكترونياً، ينشئ رمز QR، ويرسل لزاتكا — ويرجع لك النتيجة كـ JSON نظيف.