الربط مع منصة فاتورة (المرحلة الثانية) بلغة TypeScript: الشهادة الرقمية والتوقيع والإرسال

mkdir zatca-integration && cd zatca-integration
npm init -y
npm install xml-crypto xmlbuilder2 node-forge axios zod
npm install -D typescript tsx @types/node
npx tsc --init --target es2022 --module nodenext --strict

// src/config.ts
export const ENVIRONMENTS = {
  sandbox: {
    base: "https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal",
    csrTemplate: "TSTZATCACode-Signing",
  },
  simulation: {
    base: "https://gw-fatoora.zatca.gov.sa/e-invoicing/simulation",
    csrTemplate: "PREZATCACode-Signing",
  },
  production: {
    base: "https://gw-fatoora.zatca.gov.sa/e-invoicing/core",
    csrTemplate: "ZATCACode-Signing",
  },
} as const;
 
export type EnvName = keyof typeof ENVIRONMENTS;

openssl ecparam -name secp256k1 -genkey -noout -out private-key.pem

# csr-config.cnf
oid_section = OIDs
 
[OIDs]
certificateTemplateName = 1.3.6.1.4.1.311.20.2
 
[req]
default_bits       = 2048
distinguished_name = req_distinguished_name
prompt             = no
req_extensions     = req_ext
 
[req_distinguished_name]
C  = SA
OU = Riyadh Branch
O  = Noqta Trading Company
CN = EGS-886431145-101
 
[req_ext]
certificateTemplateName = ASN1:PRINTABLESTRING:TSTZATCACode-Signing
subjectAltName          = dirName:alt_names
 
[alt_names]
SN = 1-Noqta|2-POS|3-1a2b3c4d-0000-0000-0000-9f8e7d6c5b4a
UID = 399999999900003
title = 1100
registeredAddress = King Fahd Road, Riyadh 12345
businessCategory = Trading

openssl req -new -sha256 -key private-key.pem -config csr-config.cnf -out csr.pem

// src/onboarding.ts
import axios from "axios";
import { ENVIRONMENTS, type EnvName } from "./config.js";
 
const headers = (extra: Record<string, string> = {}) => ({
  "Accept-Version": "V2",
  "Accept-Language": "en",
  "Content-Type": "application/json",
  ...extra,
});
 
const basic = (token: string, secret: string) =>
  "Basic " + Buffer.from(`${token}:${secret}`).toString("base64");
 
export interface Csid {
  binarySecurityToken: string;
  secret: string;
  requestID: string;
}
 
/** 4أ — مبادلة طلب الشهادة ورمز التحقق بشهادة امتثال. */
export async function requestComplianceCsid(
  env: EnvName,
  csrPem: string,
  otp: string
): Promise<Csid> {
  const csrBase64 = Buffer.from(
    csrPem.replace(/-----(BEGIN|END) CERTIFICATE REQUEST-----/g, "").replace(/\s/g, "")
  ).toString("base64");
 
  const res = await axios.post(
    `${ENVIRONMENTS[env].base}/compliance`,
    { csr: csrBase64 },
    { headers: headers({ OTP: otp }) }
  );
 
  return {
    binarySecurityToken: res.data.binarySecurityToken,
    secret: res.data.secret,
    requestID: String(res.data.requestID),
  };
}
 
/** 4ب — كل فاتورة فحص امتثال تمر من هنا. */
export async function submitComplianceInvoice(
  env: EnvName,
  ccsid: Csid,
  payload: { invoiceHash: string; uuid: string; invoice: string }
) {
  const res = await axios.post(
    `${ENVIRONMENTS[env].base}/compliance/invoices`,
    payload,
    {
      headers: headers({
        Authorization: basic(ccsid.binarySecurityToken, ccsid.secret),
      }),
      validateStatus: () => true,
    }
  );
  return res.data;
}
 
/** 4ج — مبادلة معرّف طلب الامتثال بشهادة الإنتاج. */
export async function requestProductionCsid(
  env: EnvName,
  ccsid: Csid
): Promise<Csid> {
  const res = await axios.post(
    `${ENVIRONMENTS[env].base}/production/csids`,
    { compliance_request_id: ccsid.requestID },
    {
      headers: headers({
        Authorization: basic(ccsid.binarySecurityToken, ccsid.secret),
      }),
    }
  );
  return {
    binarySecurityToken: res.data.binarySecurityToken,
    secret: res.data.secret,
    requestID: String(res.data.requestID),
  };
}

// ضريبية: فاتورة 388، إشعار مدين 383، إشعار دائن 381
// مبسطة: فاتورة 388، إشعار مدين 383، إشعار دائن 381
const COMPLIANCE_MATRIX = [
  { typeName: "0100000", typeCode: "388" },
  { typeName: "0100000", typeCode: "383" },
  { typeName: "0100000", typeCode: "381" },
  { typeName: "0200000", typeCode: "388" },
  { typeName: "0200000", typeCode: "383" },
  { typeName: "0200000", typeCode: "381" },
] as const;

<cbc:ProfileID>reporting:1.0</cbc:ProfileID>
<cbc:ID>INV-2026-000412</cbc:ID>
<cbc:UUID>9f2c8e1a-4b7d-4f3a-9c21-77b1a0e5d3f8</cbc:UUID>
<cbc:IssueDate>2026-08-10</cbc:IssueDate>
<cbc:IssueTime>14:32:07</cbc:IssueTime>
<cbc:InvoiceTypeCode name="0100000">388</cbc:InvoiceTypeCode>
<cbc:DocumentCurrencyCode>SAR</cbc:DocumentCurrencyCode>
<cbc:TaxCurrencyCode>SAR</cbc:TaxCurrencyCode>
 
<cac:AdditionalDocumentReference>
  <cbc:ID>ICV</cbc:ID>
  <cbc:UUID>412</cbc:UUID>
</cac:AdditionalDocumentReference>
<cac:AdditionalDocumentReference>
  <cbc:ID>PIH</cbc:ID>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="text/plain">
      NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==
    </cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>

// src/invoice.ts
import { create } from "xmlbuilder2";
import { z } from "zod";
 
export const InvoiceInput = z.object({
  id: z.string().min(1),
  uuid: z.string().uuid(),
  issuedAt: z.date(),
  typeName: z.enum(["0100000", "0200000"]),
  typeCode: z.enum(["388", "383", "381"]),
  icv: z.number().int().positive(),
  pih: z.string().min(1),
  seller: z.object({ name: z.string(), vat: z.string().length(15), crn: z.string() }),
  buyer: z.object({ name: z.string(), vat: z.string().optional() }).optional(),
  lines: z.array(
    z.object({
      name: z.string(),
      quantity: z.number().positive(),
      unitPrice: z.number().nonnegative(),
      vatRate: z.number().min(0).max(1),
    })
  ).min(1),
});
 
export type InvoiceInput = z.infer<typeof InvoiceInput>;
 
/** التوقيت السعودي المحلي، مُنسَّقًا في حقلين منفصلين. */
function riyadhParts(d: Date) {
  const fmt = new Intl.DateTimeFormat("en-CA", {
    timeZone: "Asia/Riyadh",
    year: "numeric", month: "2-digit", day: "2-digit",
    hour: "2-digit", minute: "2-digit", second: "2-digit",
    hourCycle: "h23",
  }).formatToParts(d);
  const p = Object.fromEntries(fmt.map((x) => [x.type, x.value]));
  return {
    date: `${p.year}-${p.month}-${p.day}`,
    time: `${p.hour}:${p.minute}:${p.second}`,
  };
}
 
export function buildInvoiceXml(input: InvoiceInput): string {
  const data = InvoiceInput.parse(input);
  const { date, time } = riyadhParts(data.issuedAt);
 
  const lineTotal = data.lines.reduce((s, l) => s + l.quantity * l.unitPrice, 0);
  const vatTotal = data.lines.reduce(
    (s, l) => s + l.quantity * l.unitPrice * l.vatRate, 0
  );
 
  const doc = create({ version: "1.0", encoding: "UTF-8" })
    .ele("Invoice", {
      xmlns: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
      "xmlns:cac":
        "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
      "xmlns:cbc":
        "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
      "xmlns:ext":
        "urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2",
    });
 
  // يُنشأ UBLExtensions فارغًا هنا؛ الموقّع يملؤه في الخطوة 7.
  doc.ele("ext:UBLExtensions").up();
 
  doc.ele("cbc:ProfileID").txt("reporting:1.0").up();
  doc.ele("cbc:ID").txt(data.id).up();
  doc.ele("cbc:UUID").txt(data.uuid).up();
  doc.ele("cbc:IssueDate").txt(date).up();
  doc.ele("cbc:IssueTime").txt(time).up();
  doc.ele("cbc:InvoiceTypeCode", { name: data.typeName }).txt(data.typeCode).up();
  doc.ele("cbc:DocumentCurrencyCode").txt("SAR").up();
  doc.ele("cbc:TaxCurrencyCode").txt("SAR").up();
 
  // ... AccountingSupplierParty و AccountingCustomerParty و TaxTotal
  // و LegalMonetaryTotal و InvoiceLine تتبع النمط نفسه.
 
  return doc.end({ prettyPrint: false });
}

// src/hash.ts
import { createHash } from "node:crypto";
import { DOMParser, XMLSerializer } from "@xmldom/xmldom";
import * as xpath from "xpath";
import { SignedXml } from "xml-crypto";
 
const NS = {
  cac: "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2",
  cbc: "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2",
  ext: "urn:oasis:names:specification:ubl:schema:xsd:CommonExtensionComponents-2",
};
 
export function canonicalizeForHash(xml: string): string {
  const doc = new DOMParser().parseFromString(xml, "text/xml");
  const select = xpath.useNamespaces(NS);
 
  const toRemove = [
    ...select("//ext:UBLExtensions", doc),
    ...select("//cac:Signature", doc),
    ...select(
      "//cac:AdditionalDocumentReference[cbc:ID='QR']",
      doc
    ),
  ] as Node[];
 
  for (const node of toRemove) node.parentNode?.removeChild(node);
 
  const canon = new (SignedXml as any).CanonicalizationAlgorithms[
    "http://www.w3.org/2006/12/xml-c14n11"
  ]();
  return canon.process(doc.documentElement, {});
}
 
/** ترميز base64 لبصمة SHA-256 — هذا ما تسميه الواجهة invoiceHash. */
export function invoiceHash(xml: string): string {
  return createHash("sha256")
    .update(canonicalizeForHash(xml), "utf8")
    .digest("base64");
}

// src/sign.ts
import { createSign, createHash, createPrivateKey } from "node:crypto";
 
export interface SigningMaterial {
  privateKeyPem: string;
  certificatePem: string;    // مفكوك من binarySecurityToken
  certificateSerial: string; // عشري، لا ست عشري
  issuerName: string;        // كما هو في الشهادة تمامًا
}
 
export function signedPropertiesDigest(
  m: SigningMaterial,
  signingTimeIso: string
): { xml: string; digest: string } {
  const certDigest = createHash("sha256")
    .update(m.certificatePem.replace(/-----[^-]+-----|\s/g, ""))
    .digest("base64");
 
  const xml =
    `<xades:SignedProperties Id="xadesSignedProperties">` +
    `<xades:SignedSignatureProperties>` +
    `<xades:SigningTime>${signingTimeIso}</xades:SigningTime>` +
    `<xades:SigningCertificate><xades:Cert>` +
    `<xades:CertDigest>` +
    `<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>` +
    `<ds:DigestValue>${certDigest}</ds:DigestValue>` +
    `</xades:CertDigest>` +
    `<xades:IssuerSerial>` +
    `<ds:X509IssuerName>${m.issuerName}</ds:X509IssuerName>` +
    `<ds:X509SerialNumber>${m.certificateSerial}</ds:X509SerialNumber>` +
    `</xades:IssuerSerial>` +
    `</xades:Cert></xades:SigningCertificate>` +
    `</xades:SignedSignatureProperties>` +
    `</xades:SignedProperties>`;
 
  const digest = createHash("sha256").update(xml, "utf8").digest("base64");
  return { xml, digest };
}
 
/** ECDSA-SHA256 على كتلة SignedInfo بعد توحيد صيغتها. */
export function signSignedInfo(canonicalSignedInfo: string, keyPem: string): string {
  const signer = createSign("SHA256");
  signer.update(canonicalSignedInfo, "utf8");
  signer.end();
  return signer.sign(createPrivateKey(keyPem)).toString("base64");
}

// src/qr.ts
function tlv(tag: number, value: Buffer): Buffer {
  if (value.length > 255) throw new Error(`TLV tag ${tag} exceeds 255 bytes`);
  return Buffer.concat([Buffer.from([tag, value.length]), value]);
}
 
export interface QrInput {
  sellerName: string;
  vatNumber: string;
  timestampIso: string;     // UTC بصيغة ISO 8601 وينتهي بحرف Z
  totalWithVat: string;     // منزلتان عشريتان، كما تُطبع
  vatTotal: string;
  invoiceHashBase64: string;
  signatureBase64: string;
  publicKeyDer: Buffer;
  zatcaStampSignature?: Buffer; // للفواتير المبسطة فقط
}
 
export function buildQr(q: QrInput): string {
  const parts = [
    tlv(1, Buffer.from(q.sellerName, "utf8")),
    tlv(2, Buffer.from(q.vatNumber, "utf8")),
    tlv(3, Buffer.from(q.timestampIso, "utf8")),
    tlv(4, Buffer.from(q.totalWithVat, "utf8")),
    tlv(5, Buffer.from(q.vatTotal, "utf8")),
    tlv(6, Buffer.from(q.invoiceHashBase64, "utf8")),
    tlv(7, Buffer.from(q.signatureBase64, "base64")),
    tlv(8, q.publicKeyDer),
  ];
  if (q.zatcaStampSignature) parts.push(tlv(9, q.zatcaStampSignature));
  return Buffer.concat(parts).toString("base64");
}

// src/submit.ts
import axios from "axios";
import { ENVIRONMENTS, type EnvName } from "./config.js";
 
export type SubmitResult = {
  ok: boolean;
  status: "PASS" | "WARNING" | "ERROR" | "UNKNOWN";
  clearedInvoiceXml?: string;
  warnings: string[];
  errors: string[];
};
 
export async function submitInvoice(
  env: EnvName,
  pcsid: { binarySecurityToken: string; secret: string },
  payload: { invoiceHash: string; uuid: string; invoice: string },
  mode: "clearance" | "reporting"
): Promise<SubmitResult> {
  const path =
    mode === "clearance" ? "/invoices/clearance/single" : "/invoices/reporting/single";
 
  const res = await axios.post(`${ENVIRONMENTS[env].base}${path}`, payload, {
    headers: {
      "Accept-Version": "V2",
      "Accept-Language": "en",
      "Content-Type": "application/json",
      "Clearance-Status": mode === "clearance" ? "1" : "0",
      Authorization:
        "Basic " +
        Buffer.from(`${pcsid.binarySecurityToken}:${pcsid.secret}`).toString("base64"),
    },
    validateStatus: () => true,
    timeout: 30_000,
  });
 
  const v = res.data?.validationResults ?? {};
  const warnings = (v.warningMessages ?? []).map((m: any) => `${m.code}: ${m.message}`);
  const errors = (v.errorMessages ?? []).map((m: any) => `${m.code}: ${m.message}`);
 
  return {
    ok: res.status === 200 && errors.length === 0,
    status: v.status ?? "UNKNOWN",
    clearedInvoiceXml: res.data?.clearedInvoice
      ? Buffer.from(res.data.clearedInvoice, "base64").toString("utf8")
      : undefined,
    warnings,
    errors,
  };
}

// src/state.ts — مخطط مبدئي؛ اسنده إلى مخزن يدعم المعاملات
export interface EgsState {
  egsUuid: string;
  lastIcv: number;
  lastInvoiceHash: string; // يصبح PIH التالي
}
 
export async function nextDocument(
  db: Db,
  egsUuid: string,
  build: (icv: number, pih: string) => Promise<{ hash: string; xml: string }>
) {
  return db.transaction(async (tx) => {
    const state = await tx.selectForUpdate("egs_state", { egsUuid });
    const icv = state.lastIcv + 1;
    const { hash, xml } = await build(icv, state.lastInvoiceHash);
    await tx.update("egs_state", { egsUuid }, { lastIcv: icv, lastInvoiceHash: hash });
    return { icv, hash, xml };
  });
}

// tests/hash.test.ts
import { describe, it, expect } from "vitest";
import { invoiceHash } from "../src/hash.js";
import { readFileSync } from "node:fs";
 
describe("invoice hash", () => {
  it("يطابق مخرجات SDK زاتكا للفاتورة المرجعية", () => {
    const xml = readFileSync("fixtures/standard-invoice.xml", "utf8");
    // القيمة التي أنتجتها أداة تحقق زاتكا للملف نفسه.
    expect(invoiceHash(xml)).toBe(readFileSync("fixtures/standard-invoice.hash", "utf8").trim());
  });
 
  it("لا يتأثر بوجود مرجع رمز QR", () => {
    const withQr = readFileSync("fixtures/standard-invoice-with-qr.xml", "utf8");
    const withoutQr = readFileSync("fixtures/standard-invoice.xml", "utf8");
    expect(invoiceHash(withQr)).toBe(invoiceHash(withoutQr));
  });
});