بناء فواتير PINT AE الإماراتية والتحقق منها باستخدام TypeScript

// src/spec/pint-ae.ts
 
/**
 * ثوابت مشتقة من مواصفة PINT AE.
 * ثبّتها على الإصدار الذي اعتُمد عليه مزوّد الخدمة لديك، وأعد التحقق
 * من https://docs.peppol.eu/poac/ae/ عند كل تحديث للمواصفة.
 * لا تضع هذه القيم مباشرة داخل المُنشئ أبداً.
 */
export const PINT_AE_RELEASE = "2025-Q2" as const;
 
export const CUSTOMIZATION_ID = "urn:peppol:pint:billing-1@ae-1";
export const PROFILE_ID = "urn:peppol:bis:billing";
export const UBL_VERSION_ID = "2.1";
 
export const NS = {
  inv: "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2",
  cn: "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2",
  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",
} as const;
 
/** رموز نوع المستند وفق UN/CEFACT 1001 المستخدمة في الملف الإماراتي. */
export const DOC_TYPE = {
  taxInvoice: "380",
  creditNote: "381",
  debitNote: "383",
  selfBilledInvoice: "389",
} as const;
 
/** رموز الفئات الضريبية UNCL5305 ضمن نطاق الإمارات. */
export const VAT_CATEGORY = {
  standard: "S",       // ٥٪
  zeroRated: "Z",
  exempt: "E",
  reverseCharge: "AE",
  outOfScope: "O",
} as const;
 
export type VatCategoryCode =
  (typeof VAT_CATEGORY)[keyof typeof VAT_CATEGORY];
 
/** الفئات التي تتطلب قانوناً ذكر سبب على المستند. */
export const REASON_REQUIRED: ReadonlySet<VatCategoryCode> = new Set([
  VAT_CATEGORY.zeroRated,
  VAT_CATEGORY.exempt,
  VAT_CATEGORY.reverseCharge,
  VAT_CATEGORY.outOfScope,
]);
 
export const AED = "AED";
/** الدرهم ينقسم إلى ١٠٠ فلس. كل المبالغ داخلياً أعداد صحيحة بالفلس. */
export const MINOR_UNITS = 2;

// src/domain/invoice.ts
 
/** المال دائماً أعداد صحيحة بالوحدة الصغرى (الفلس). لا عدد عشري، ولا نص. */
export type Fils = number & { readonly __brand: "Fils" };
 
export const fils = (n: number): Fils => {
  if (!Number.isInteger(n)) {
    throw new TypeError(`Money must be integer fils, received ${n}`);
  }
  return n as Fils;
};
 
/** الرقم الضريبي الإماراتي: خمسة عشر رقماً بالضبط. */
export type Trn = string & { readonly __brand: "Trn" };
 
export const trn = (raw: string): Trn => {
  const cleaned = raw.replace(/[\s-]/g, "");
  if (!/^\d{15}$/.test(cleaned)) {
    throw new TypeError(`Invalid TRN: expected 15 digits, got "${raw}"`);
  }
  return cleaned as Trn;
};
 
export interface LegalIdentifier {
  /** الرخصة التجارية، الهوية الإماراتية، المستند التجاري، أو جواز السفر. */
  readonly scheme: "TL" | "EID" | "CD" | "PAS";
  readonly value: string;
}
 
export interface Party {
  readonly name: string;
  /** اختياري للمشترين تحت حد التسجيل. */
  readonly trn?: Trn;
  readonly legalId?: LegalIdentifier;
  readonly address: {
    readonly street: string;
    readonly city: string;
    readonly emirate: string;
    readonly countryCode: string; // ISO 3166-1 alpha-2
  };
}
 
interface VatBase {
  readonly rate: number; // نسبة مئوية، مثلاً ٥
}
 
export type VatTreatment =
  | ({ readonly category: "S" } & VatBase)
  | { readonly category: "Z" | "E" | "AE" | "O"; readonly rate: 0; readonly reason: string };
 
export interface InvoiceLine {
  readonly id: string;
  readonly description: string;
  readonly quantity: number;
  readonly unitCode: string; // UN/ECE Rec 20، مثل "EA" أو "HUR"
  readonly unitPrice: Fils;
  readonly lineExtensionAmount: Fils; // صافٍ من الضريبة
  readonly vat: VatTreatment;
}
 
export interface Invoice {
  readonly number: string;
  readonly issueDate: string; // YYYY-MM-DD
  readonly dueDate?: string;
  readonly documentType: "380" | "381" | "383" | "389";
  readonly currency: "AED";
  readonly seller: Party & { readonly trn: Trn }; // الرقم الضريبي للبائع ليس اختيارياً أبداً
  readonly buyer: Party;
  readonly lines: readonly InvoiceLine[];
  /** يُملأ لإشعارات الدائن والمدين فقط. */
  readonly precedingInvoice?: { readonly number: string; readonly issueDate: string };
}

// src/money.ts
import { fils, type Fils } from "./domain/invoice";
 
export const addFils = (...xs: Fils[]): Fils =>
  fils(xs.reduce((a, b) => a + b, 0));
 
/** تقريب نصف-لأعلى على الأعداد الصحيحة. لا ينجو أي عدد عشري من هذه الدالة. */
export const applyRate = (base: Fils, ratePercent: number): Fils => {
  const numerator = base * Math.round(ratePercent * 100); // النسبة بنقاط الأساس
  const scaled = Math.round(numerator / 10_000);
  return fils(scaled);
};
 
/** من الفلس إلى النص العشري الذي يتوقعه UBL: 12345 تصبح "123.45". */
export const toAmountString = (v: Fils): string => {
  const sign = v < 0 ? "-" : "";
  const abs = Math.abs(v);
  return `${sign}${Math.trunc(abs / 100)}.${String(abs % 100).padStart(2, "0")}`;
};

// src/totals.ts
import { addFils, applyRate } from "./money";
import { fils, type Fils, type Invoice } from "./domain/invoice";
 
export interface TaxSubtotal {
  readonly category: string;
  readonly rate: number;
  readonly taxableAmount: Fils;
  readonly taxAmount: Fils;
  readonly reason?: string;
}
 
export interface Totals {
  readonly lineExtensionAmount: Fils;
  readonly taxExclusiveAmount: Fils;
  readonly taxInclusiveAmount: Fils;
  readonly payableAmount: Fils;
  readonly taxAmount: Fils;
  readonly subtotals: readonly TaxSubtotal[];
}
 
export function computeTotals(invoice: Invoice): Totals {
  const groups = new Map<string, { rate: number; base: Fils; reason?: string }>();
 
  for (const line of invoice.lines) {
    const key = `${line.vat.category}:${line.vat.rate}`;
    const existing = groups.get(key);
    const reason = "reason" in line.vat ? line.vat.reason : undefined;
    groups.set(key, {
      rate: line.vat.rate,
      base: addFils(existing?.base ?? fils(0), line.lineExtensionAmount),
      reason: existing?.reason ?? reason,
    });
  }
 
  // تُحسب الضريبة مرة واحدة لكل مجموعة فئة، على القاعدة المجمّعة.
  // لا تحسبها لكل سطر ثم تجمع — تلك هي علّة الفلس الواحد.
  const subtotals: TaxSubtotal[] = [...groups.entries()].map(([key, g]) => ({
    category: key.split(":")[0],
    rate: g.rate,
    taxableAmount: g.base,
    taxAmount: applyRate(g.base, g.rate),
    reason: g.reason,
  }));
 
  const lineExtensionAmount = addFils(...invoice.lines.map((l) => l.lineExtensionAmount));
  const taxAmount = addFils(...subtotals.map((s) => s.taxAmount));
  const taxInclusiveAmount = addFils(lineExtensionAmount, taxAmount);
 
  return {
    lineExtensionAmount,
    taxExclusiveAmount: lineExtensionAmount,
    taxInclusiveAmount,
    payableAmount: taxInclusiveAmount,
    taxAmount,
    subtotals,
  };
}

npm install xmlbuilder2
npm install -D vitest tsx

// src/build/invoice-xml.ts
import { create } from "xmlbuilder2";
import {
  CUSTOMIZATION_ID, PROFILE_ID, UBL_VERSION_ID, NS, AED,
} from "../spec/pint-ae";
import type { Fils, Invoice, Party } from "../domain/invoice";
import { computeTotals } from "../totals";
import { toAmountString } from "../money";
 
const amt = (v: Fils) => ({ "@currencyID": AED, "#": toAmountString(v) });
 
function partyNode(p: Party, endpointScheme: string) {
  const node: Record<string, unknown> = {};
 
  if (p.trn) {
    node["cbc:EndpointID"] = { "@schemeID": endpointScheme, "#": p.trn };
  }
 
  node["cac:PostalAddress"] = {
    "cbc:StreetName": p.address.street,
    "cbc:CityName": p.address.city,
    "cbc:CountrySubentity": p.address.emirate,
    "cac:Country": { "cbc:IdentificationCode": p.address.countryCode },
  };
 
  if (p.trn) {
    node["cac:PartyTaxScheme"] = {
      "cbc:CompanyID": p.trn,
      "cac:TaxScheme": { "cbc:ID": "VAT" },
    };
  }
 
  node["cac:PartyLegalEntity"] = {
    "cbc:RegistrationName": p.name,
    ...(p.legalId
      ? { "cbc:CompanyID": { "@schemeAgencyID": p.legalId.scheme, "#": p.legalId.value } }
      : {}),
  };
 
  return node;
}
 
export function buildInvoiceXml(invoice: Invoice, endpointScheme: string): string {
  const t = computeTotals(invoice);
 
  const doc = create({ version: "1.0", encoding: "UTF-8" }).ele("Invoice", {
    xmlns: NS.inv,
    "xmlns:cac": NS.cac,
    "xmlns:cbc": NS.cbc,
    "xmlns:ext": NS.ext,
  });
 
  doc.ele("cbc:UBLVersionID").txt(UBL_VERSION_ID);
  doc.ele("cbc:CustomizationID").txt(CUSTOMIZATION_ID);
  doc.ele("cbc:ProfileID").txt(PROFILE_ID);
  doc.ele("cbc:ID").txt(invoice.number);
  doc.ele("cbc:IssueDate").txt(invoice.issueDate);
  if (invoice.dueDate) doc.ele("cbc:DueDate").txt(invoice.dueDate);
  doc.ele("cbc:InvoiceTypeCode").txt(invoice.documentType);
  doc.ele("cbc:DocumentCurrencyCode").txt(AED);
 
  if (invoice.precedingInvoice) {
    doc.ele("cac:BillingReference").ele("cac:InvoiceDocumentReference").ele({
      "cbc:ID": invoice.precedingInvoice.number,
      "cbc:IssueDate": invoice.precedingInvoice.issueDate,
    });
  }
 
  doc.ele("cac:AccountingSupplierParty").ele({
    "cac:Party": partyNode(invoice.seller, endpointScheme),
  });
  doc.ele("cac:AccountingCustomerParty").ele({
    "cac:Party": partyNode(invoice.buyer, endpointScheme),
  });
 
  const taxTotal = doc.ele("cac:TaxTotal");
  taxTotal.ele("cbc:TaxAmount", { currencyID: AED }).txt(toAmountString(t.taxAmount));
 
  for (const s of t.subtotals) {
    const sub = taxTotal.ele("cac:TaxSubtotal");
    sub.ele("cbc:TaxableAmount", { currencyID: AED }).txt(toAmountString(s.taxableAmount));
    sub.ele("cbc:TaxAmount", { currencyID: AED }).txt(toAmountString(s.taxAmount));
    const cat = sub.ele("cac:TaxCategory");
    cat.ele("cbc:ID").txt(s.category);
    cat.ele("cbc:Percent").txt(s.rate.toFixed(2));
    if (s.reason) cat.ele("cbc:TaxExemptionReason").txt(s.reason);
    cat.ele("cac:TaxScheme").ele("cbc:ID").txt("VAT");
  }
 
  doc.ele("cac:LegalMonetaryTotal").ele({
    "cbc:LineExtensionAmount": amt(t.lineExtensionAmount),
    "cbc:TaxExclusiveAmount": amt(t.taxExclusiveAmount),
    "cbc:TaxInclusiveAmount": amt(t.taxInclusiveAmount),
    "cbc:PayableAmount": amt(t.payableAmount),
  });
 
  for (const line of invoice.lines) {
    const l = doc.ele("cac:InvoiceLine");
    l.ele("cbc:ID").txt(line.id);
    l.ele("cbc:InvoicedQuantity", { unitCode: line.unitCode }).txt(String(line.quantity));
    l.ele("cbc:LineExtensionAmount", { currencyID: AED })
      .txt(toAmountString(line.lineExtensionAmount));
    l.ele("cac:Item").ele({
      "cbc:Name": line.description,
      "cac:ClassifiedTaxCategory": {
        "cbc:ID": line.vat.category,
        "cbc:Percent": line.vat.rate.toFixed(2),
        "cac:TaxScheme": { "cbc:ID": "VAT" },
      },
    });
    l.ele("cac:Price").ele("cbc:PriceAmount", { currencyID: AED })
      .txt(toAmountString(line.unitPrice));
  }
 
  return doc.end({ prettyPrint: true });
}

// src/validate/schematron.ts
import { execFile } from "node:child_process";
import { promisify } from "node:util";
import { writeFile, mkdtemp, rm } from "node:fs/promises";
import { join } from "node:path";
import { tmpdir } from "node:os";
 
const run = promisify(execFile);
 
export interface ValidationFinding {
  readonly severity: "fatal" | "warning";
  readonly ruleId: string;
  readonly location: string;
  readonly message: string;
}
 
const JAR = process.env.PEPPOL_VALIDATOR_JAR ?? "./tools/phive-cli.jar";
const RULESET = process.env.PEPPOL_RULESET ?? "eu.peppol.pint.ae:invoice:latest";
 
export async function validateInvoiceXml(xml: string): Promise<ValidationFinding[]> {
  const dir = await mkdtemp(join(tmpdir(), "pint-ae-"));
  const file = join(dir, "invoice.xml");
  try {
    await writeFile(file, xml, "utf8");
    const { stdout } = await run("java", [
      "-jar", JAR,
      "--vesid", RULESET,
      "--mode", "json",
      file,
    ]);
    return parseFindings(stdout);
  } catch (err) {
    // الخروج بقيمة غير صفرية هو طريقة المدقق في الإبلاغ عن نتائج، لا انهيار.
    const stdout = (err as { stdout?: string }).stdout;
    if (stdout) return parseFindings(stdout);
    throw new Error(
      `Validator failed to run. Is Java on PATH and ${JAR} present? ${String(err)}`,
    );
  } finally {
    await rm(dir, { recursive: true, force: true });
  }
}
 
function parseFindings(stdout: string): ValidationFinding[] {
  const report = JSON.parse(stdout) as {
    results?: Array<{ items?: Array<Record<string, string>> }>;
  };
  return (report.results ?? []).flatMap((r) =>
    (r.items ?? []).map((i) => ({
      severity: i.errorLevel === "ERROR" ? ("fatal" as const) : ("warning" as const),
      ruleId: i.errorID ?? "unknown",
      location: i.errorLocation ?? "",
      message: i.errorText ?? "",
    })),
  );
}

// src/__tests__/invoice.spec.ts
import { describe, expect, it } from "vitest";
import { buildInvoiceXml } from "../build/invoice-xml";
import { validateInvoiceXml } from "../validate/schematron";
import { computeTotals } from "../totals";
import { standardInvoice, mixedRateInvoice, reverseChargeInvoice } from "./fixtures";
 
describe("PINT AE conformance", () => {
  for (const [name, fixture] of Object.entries({
    standardInvoice, mixedRateInvoice, reverseChargeInvoice,
  })) {
    it(`${name} produces zero fatal findings`, async () => {
      const findings = await validateInvoiceXml(buildInvoiceXml(fixture, "0235"));
      const fatal = findings.filter((f) => f.severity === "fatal");
      expect(fatal, JSON.stringify(fatal, null, 2)).toHaveLength(0);
    }, 30_000);
  }
});
 
describe("monetary reconciliation", () => {
  it("tax total equals the sum of subtotals for awkward thirds", () => {
    // ٣ سطور بقيمة 33.33 درهماً وضريبة ٥٪ — انحراف الفلس الكلاسيكي
    const t = computeTotals(mixedRateInvoice);
    const summed = t.subtotals.reduce((a, s) => a + s.taxAmount, 0);
    expect(t.taxAmount).toBe(summed);
  });
 
  it("inclusive total equals exclusive plus tax", () => {
    const t = computeTotals(standardInvoice);
    expect(t.taxInclusiveAmount).toBe(t.taxExclusiveAmount + t.taxAmount);
  });
});

SELECT
  COUNT(*) FILTER (WHERE trn IS NULL OR trn = '')                    AS missing,
  COUNT(*) FILTER (WHERE trn ~ '^[0-9]{15}$')                        AS well_formed,
  COUNT(*) FILTER (WHERE trn IS NOT NULL AND trn !~ '^[0-9]{15}$')   AS malformed
FROM customers
WHERE status = 'active' AND customer_type = 'business';

const UNIT_CODE_MAP: Record<string, string> = {
  each: "EA", pcs: "EA", unit: "EA", item: "EA",
  hour: "HUR", hr: "HUR", hours: "HUR",
  day: "DAY", month: "MON",
  kg: "KGM", km: "KMT", litre: "LTR", l: "LTR",
};
 
export function toUnitCode(raw: string): string {
  const code = UNIT_CODE_MAP[raw.trim().toLowerCase()];
  if (!code) {
    // افشل بصوت عالٍ وقت البناء. الرجوع الصامت إلى "EA" علّة في سلامة
    // البيانات تظهر بعد شهور في تدقيق ضريبي.
    throw new Error(`Unmapped unit of measure: "${raw}". Add it to UNIT_CODE_MAP.`);
  }
  return code;
}

SELECT COUNT(*) FROM credit_notes WHERE original_invoice_id IS NULL;

SELECT id, total_vat, computed_vat, total_vat - computed_vat AS drift
FROM (
  SELECT i.id, i.total_vat,
         ROUND(SUM(l.net_amount) * 0.05, 2) AS computed_vat
  FROM invoices i JOIN invoice_lines l ON l.invoice_id = i.id
  WHERE i.issue_date >= DATE '2026-01-01'
  GROUP BY i.id, i.total_vat
) x
WHERE ABS(total_vat - computed_vat) > 0.001
ORDER BY ABS(total_vat - computed_vat) DESC
LIMIT 50;

// src/transmit/send.ts
import { createHash } from "node:crypto";
 
export interface SubmissionResult {
  readonly providerRef: string;
  readonly acceptedAt: string;
}
 
export async function submit(
  invoiceNumber: string,
  xml: string,
  deps: { fetch: typeof fetch; baseUrl: string; token: string },
): Promise<SubmissionResult> {
  // مفتاح عدم التكرار مشتق من المستند نفسه: البايتات ذاتها المُعاد إرسالها
  // هي الإرسال ذاته؛ والبايتات المتغيرة مستند آخر يجب أن يرفضه المزوّد
  // تحت رقم فاتورة مستخدم بالفعل.
  const idempotencyKey = createHash("sha256")
    .update(`${invoiceNumber}:${xml}`)
    .digest("hex");
 
  const res = await deps.fetch(`${deps.baseUrl}/documents`, {
    method: "POST",
    headers: {
      "Content-Type": "application/xml",
      Authorization: `Bearer ${deps.token}`,
      "Idempotency-Key": idempotencyKey,
    },
    body: xml,
  });
 
  if (res.status === 409) {
    // أُرسل مسبقاً. استخرج المرجع القائم بدل الفشل.
    const existing = await res.json();
    return { providerRef: existing.documentId, acceptedAt: existing.receivedAt };
  }
 
  if (!res.ok) {
    throw new TransmissionError(res.status, await res.text());
  }
 
  const body = await res.json();
  return { providerRef: body.documentId, acceptedAt: body.receivedAt };
}
 
export class TransmissionError extends Error {
  constructor(readonly status: number, readonly body: string) {
    super(`Corner 2 rejected submission: HTTP ${status}`);
    this.name = "TransmissionError";
  }
}

// src/lifecycle/state.ts
export type DocumentState =
  | "draft"           // بُني ولم يُثبت صحته بعد
  | "validated"       // يجتاز Schematron محلياً
  | "submitted"       // قبله مزوّدنا عند الركن الثاني
  | "delivered"       // MLR: وصل إلى نقطة وصول المشتري
  | "accepted"        // IR: قبله المشتري
  | "rejected"        // IR: رفضه المشتري — يحتاج إشعار دائن
  | "failed";         // تعذّر إرساله
 
const TRANSITIONS: Record<DocumentState, readonly DocumentState[]> = {
  draft: ["validated", "failed"],
  validated: ["submitted", "failed"],
  submitted: ["delivered", "failed"],
  delivered: ["accepted", "rejected"],
  accepted: [],
  rejected: [],
  failed: ["validated"], // أصلح ثم أعد المحاولة
};
 
export function canTransition(from: DocumentState, to: DocumentState): boolean {
  return TRANSITIONS[from].includes(to);
}
 
export class IllegalTransition extends Error {
  constructor(from: DocumentState, to: DocumentState) {
    super(`Illegal document transition: ${from} to ${to}`);
    this.name = "IllegalTransition";
  }
}

CREATE TABLE einvoice_document (
  id                BIGSERIAL PRIMARY KEY,
  invoice_number    TEXT NOT NULL UNIQUE,
  state             TEXT NOT NULL,
  -- البايتات المُرسَلة حرفياً. إعادة بناء XML لاحقاً لن تعيد إنتاجها
  -- بمجرد أن يتغير إصدار المواصفة أو تحويلك.
  xml_payload       BYTEA NOT NULL,
  xml_sha256        TEXT NOT NULL,
  spec_release      TEXT NOT NULL,
  provider_ref      TEXT,
  submitted_at      TIMESTAMPTZ,
  delivered_at      TIMESTAMPTZ,
  responded_at      TIMESTAMPTZ,
  rejection_reason  TEXT,
  created_at        TIMESTAMPTZ NOT NULL DEFAULT now()
);
 
CREATE TABLE einvoice_event (
  id            BIGSERIAL PRIMARY KEY,
  document_id   BIGINT NOT NULL REFERENCES einvoice_document(id),
  from_state    TEXT NOT NULL,
  to_state      TEXT NOT NULL,
  payload       JSONB,
  occurred_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);
 
CREATE INDEX ON einvoice_document (state) WHERE state IN ('submitted', 'delivered');

import fc from "fast-check";
 
it("totals always reconcile regardless of line composition", () => {
  fc.assert(
    fc.property(
      fc.array(fc.integer({ min: 1, max: 5_000_00 }), { minLength: 1, maxLength: 60 }),
      (amounts) => {
        const inv = invoiceWithLineAmounts(amounts);
        const t = computeTotals(inv);
        const summed = t.subtotals.reduce((a, s) => a + s.taxAmount, 0);
        return t.taxAmount === summed
          && t.taxInclusiveAmount === t.taxExclusiveAmount + t.taxAmount;
      },
    ),
    { numRuns: 500 },
  );
});