API-Based Integration + Custom AL ExtensionAPI Middleware + Tailored AL Implementation

Microsoft Dynamics 365 Business Central ZATCA Phase 2 Integration

Keep your Dynamics 365 Business Central ledger. Automate ZATCA Phase 2 clearance and reporting with Saky ZATCA Connect API middleware.

Connect Microsoft Dynamics 365 Business Central (Cloud SaaS or On-Premises) to ZATCA FATOORA Phase 2 by combining Saky ZATCA Connect’s pre-built REST API & cryptographic middleware with customer-specific Business Central AL extension hooks and RDLC/Word report layout updates.

Technical Data Pipeline

How Microsoft Dynamics 365 Business Central Connects to ZATCA FATOORA

End-to-end transaction lifecycle from ERP invoice posting to ZATCA Phase 2 clearance and QR write-back.

01. ERP Source

Invoice Origination

Dynamics 365 Business Central (Posted Sales Invoices & Sales Cr. Memos)

02. Connector Layer

Payload Extraction

API-Based REST JSON Push (POST /api/v1/erp/invoices) via Customer-Specific AL Codeunit

03. Saky ZATCA Middleware

XML & Cryptographic Stamp

Pre-Built Schematron Validation, UBL 2.1 XML, ECDSA Cryptographic Stamp & FATOORA API

04. ERP Write-Back

Cleared XML & QR Return

Synchronous JSON Response / Webhook Callback Stored in BC Fields for RDLC/Word QR Print

Engineering Challenges Solved

Why Business Central Teams Choose Middleware Over Custom In-ERP Coding

Missing ZATCA Phase 2 Fields on Standard BC Customer Cards

Standard Business Central customer and company cards often lack dedicated fields for Saudi National Address components (Building Number, District, Additional Number) and ZATCA tax exemption reason codes.

Preventing Un-Cleared B2B Invoice Distribution

Under ZATCA Phase 2 rules, a Standard Tax Invoice is not legally valid until cleared by ZATCA. Finance teams need an automated workflow that clears the invoice before emailing or printing.

Credit Memo Billing Reference Rules (BR-KSA-56)

ZATCA requires every Sales Credit Memo to reference the original invoice number and include a valid issuance reason in the UBL 2.1 XML payload.

Connector Capabilities

Business Central ZATCA Capabilities

Pre-Built in Saky Middleware

Pre-Built REST JSON Ingestion & HMAC-SHA256 Security

Provides production-ready REST endpoints (`/api/v1/erp/invoices` and `/api/v2/invoices/submit`) with API Key and HMAC-SHA256 request verification, idempotency protection, and synchronous/webhook status responses.

Implementation Evidence: Implemented in routes/api_v1.ts, routes/api_v2.ts, middleware/hmacMiddleware.ts, and verified by verify_v1_api.ts.
Pre-Built in Saky Middleware

Automated UBL 2.1 XML, B2B Clearance & B2C Reporting Engine

Transforms Business Central JSON invoice payloads into canonical UBL 2.1 XML, manages per-branch ICV counters and SHA-256 PIH chains, signs with the branch ECDSA key, and submits to ZATCA Clearance or Reporting APIs.

Implementation Evidence: Implemented in IntegrationService (integrationService.ts), XmlService (xmlService.ts), SdkService (sdkService.ts), and ZatcaService (zatcaService.ts).
API-Based Integration

Pre-Flight Customer VAT & National Address Validation

Validates 15-digit Saudi VAT registration numbers (`BR-KSA-81`), buyer national address fields (`BR-10`), and Credit Memo billing references (`BR-KSA-56`) before transmitting to ZATCA.

Implementation Evidence: Implemented in IntegrationService.processInvoiceRecord (integrationService.ts lines 260–460) with structured validation error responses.
Customer-Specific ERP Development

Customer-Specific AL Extension & RDLC/Word QR Layout

During implementation, our Dynamics engineering team develops and deploys a tailored AL extension for your BC tenant to add Saudi National Address fields, subscribe to `OnAfterPostSalesDoc` events, and render the returned QR code on your RDLC or Word invoice layouts.

Implementation Evidence: Delivered as customer-specific AL codeunit/table/report extension tailored to each client’s Business Central version and custom invoice layouts (not marketed as a pre-packaged AppSource plug-and-play app).
Supported Invoice & Note Types

Supported Document Workflows

  • Posted Sales Invoices (Standard B2B 0100000 & Simplified B2C 0200000)
  • Posted Sales Credit Memos (381 — Linked to Original Invoice Reference)
  • Sales Debit Notes & Price Adjustments (383)
  • Prepayment Invoices & Prepayment Credit Memos (386)
  • Service Module Invoices & Contract Billing (via Custom AL Mapping)
  • Multi-Currency Export & Zero-Rated Tax Invoices
Transparent Engineering Scope

Business Central Capability Classification: Pre-Built vs. API-Based vs. Custom Scope

We clearly distinguish what is pre-built inside Saky ZATCA Connect, what operates via standard APIs, and what requires customer-specific configuration in your ERP. SAP and Oracle are supported via API middleware only and are not marketed as native pre-built connectors.

1. Pre-Built in Saky Middleware

Production-Ready Out of the Box

  • Saky ZATCA Connect REST API endpoints (POST /api/v1/erp/invoices, POST /api/v2/invoices/submit, GET /api/v1/erp/invoices/:id)
  • HMAC-SHA256 payload authentication, replay-protection nonces, and idempotency keys
  • Pre-flight Saudi VAT number (BR-KSA-81), buyer address (BR-10), and tax category (S/Z/E/O) validation
  • UBL 2.1 XML construction, sequential ICV & SHA-256 PIH chaining, ECDSA cryptographic stamping, and 9-tag Base64 TLV QR generation
  • CSID onboarding dashboard (CSR generation, FATOORA OTP exchange, compliance check runner, and Production CSID rotation)
2. API-Based Integration

Standardized REST / OData Contract

  • HTTPS JSON payload transmission from Business Central (via AL HttpClient or OData v4 webhook bridge) to Saky ZATCA Connect
  • Synchronous HTTP response and asynchronous HMAC-signed webhook callback (IntegrationService.reflectStatusToERP) returning ZATCA status, UUID, XML hash, and Base64 QR code
3. Customer-Specific ERP Scope

Tailored During Client Onboarding

  • Customer-specific Business Central AL table & page extensions for Saudi National Address fields and ZATCA status tracking
  • Customer-specific AL codeunit event subscribers (OnAfterPostSalesDoc / OnAfterPostSalesCrMemo) mapped to your VAT Posting Setup and dimensions
  • Custom RDLC or Word Sales Invoice and Credit Memo report layout updates to print the returned Phase 2 QR code
Onboarding Roadmap

4-Step Business Central Integration Process

01

Business Central Environment & VAT Setup Audit

Assess your Business Central version (SaaS or On-Premises), VAT Posting Setup, customer address fields, and custom invoice report layouts.

02

Tailored AL Extension & API Middleware Connection

Develop and deploy the AL table/codeunit extension in your Business Central sandbox and connect it to Saky ZATCA Connect REST APIs.

03

CSID Onboarding & Compliance Simulation

Generate branch CSRs, complete FATOORA compliance checks, and verify credit memo and tax invoice scenarios.

04

RDLC/Word Print Verification & Production Cutover

Verify QR code rendering on your invoice layouts, enable production CSID credentials, and train finance users on status monitoring.

Integration FAQ

Business Central ZATCA Phase 2 Questions

We believe in transparent engineering communication: Saky ZATCA Connect provides the pre-built ZATCA Phase 2 middleware engine and REST APIs (`/api/v1/erp/invoices`, `/api/v2/invoices/submit`), while the Business Central side is delivered as a tailored AL extension and report layout update adapted to your specific BC tenant, VAT Posting Setup, and custom fields.
KSA Enterprise Integration Assessment

Request a Business Central ZATCA Phase 2 Demo

Share your existing ERP environment and monthly invoice volume. Our integration engineers will walk you through the middleware architecture, UBL 2.1 XML transformation, and CSID onboarding flow.