Pre-Built OData Connector + Custom X++ Write-BackPre-Built OData Service + Custom X++ Write-Back

Microsoft Dynamics 365 Finance & Operations (F&O) ZATCA Phase 2 Integration

Keep your existing Dynamics 365 Finance & Operations environment. Connect it to ZATCA FATOORA Phase 2 through Saky ZATCA Connect.

Bridge Microsoft Dynamics 365 Finance & Operations (F&O) with Saudi Arabia’s ZATCA FATOORA Phase 2 platform through Saky ZATCA Connect’s pre-built Azure AD OData v4 connector and REST API middleware, combined with tailored X++ write-back and SSRS print layout integration.

Technical Data Pipeline

How Microsoft Dynamics 365 Finance & Operations 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 F&O (SalesInvoiceHeaders / SalesInvoiceHeadersV2 / Custom X++ Entities)

02. Connector Layer

Payload Extraction

Pre-Built OData v4 Polling (Azure AD OAuth 2.0) or API-Based Push (/api/v1/erp/invoices)

03. Saky ZATCA Middleware

XML & Cryptographic Stamp

Pre-Built UBL 2.1 XML Builder, SHA-256 Chaining (PIH), ECDSA Signing & Schematron Check

04. ERP Write-Back

Cleared XML & QR Return

OData Action (UpdateZatcaStatus / ZatcaIntegrationStatuses) + Custom SSRS QR Layout

Engineering Challenges Solved

Why Dynamics 365 Finance Teams Choose Middleware Over Custom In-ERP Coding

Custom X++ Invoice Tables & Vertical Workflows

Many Saudi enterprises run heavily customized F&O sales order, project accounting, or industry sub-ledgers where standard Electronic Reporting (ER) configurations require extensive rework.

Multi-Entity & Multi-Branch CSID Management

Enterprises operating multiple legal entities or branch EGS units across Riyadh, Jeddah, and Dammam need isolated CSID certificates, sequential invoice counters (ICV), and previous invoice hash (PIH) chains per device/branch.

Clearance Rejection Visibility for Finance Teams

When a B2B invoice fails a ZATCA rule (such as missing buyer national address components or tax category mismatch), finance users need clear, actionable validation messages rather than raw XML fault logs.

Connector Capabilities

Dynamics 365 Finance ZATCA Capabilities

Pre-Built in Saky Middleware

Azure AD OAuth 2.0 & OData v4 Invoice Polling

Authenticates with Microsoft Entra ID (`client_credentials`) and polls `SalesInvoiceHeaders` and `SalesInvoiceHeadersV2` (`cross-company=true`) on an automated 2-minute sync schedule, or accepts real-time REST API pushes.

Implementation Evidence: Implemented in D365Service (d365Service.ts: getAccessToken, testConnection, fetchPendingInvoices) and SyncService (syncService.ts: 2-minute cron scheduler).
Pre-Built in Saky Middleware

Multi-Legal Entity (`dataAreaId`) & Branch EGS Routing

Maps each Dynamics 365 legal entity (`dataAreaId`) or branch identifier to its dedicated ZATCA cryptographic stamp (CSID) and maintains isolated sequential Invoice Counter Values (ICV) and SHA-256 Previous Invoice Hashes (PIH).

Implementation Evidence: Implemented in IntegrationService (integrationService.ts) and D365Service company filter (`dataAreaId eq companyId`).
Pre-Built in Saky Middleware

Pre-Flight VAT (`BR-KSA-81`) & Address (`BR-10`) Validation

Validates mandatory ZATCA Phase 2 buyer master fields (15-digit Saudi VAT number, building number, street, district, city, 5-digit postal code) and normalizes VAT category codes (`S`, `Z`, `E`, `O`) before calling FATOORA APIs.

Implementation Evidence: Implemented in IntegrationService (address & building-number parser lines 283–334, tax category normalizer lines 338–365) and XmlService / SdkService.
Customer-Specific ERP Development

X++ OData Write-Back Entity & SSRS Report QR Rendering

Writes the cleared ZATCA status, UUID, XML hash, and 9-tag Base64 TLV QR code back to F&O via OData (`UpdateZatcaStatus` or `ZatcaIntegrationStatuses`). Customer-specific X++ entity publication and SSRS/ER print layout updates are completed during onboarding.

Implementation Evidence: Middleware OData write-back caller is pre-built in D365Service.updateInvoiceStatus (d365Service.ts lines 173–232); X++ target action/entity and SSRS report design are deployed in the client F&O environment.
Supported Invoice & Note Types

Supported Document Workflows

  • Sales Order Tax Invoices (SalesInvoiceHeaders / SalesInvoiceHeadersV2 — Pre-Built OData)
  • Standard B2B Invoices & Simplified B2C Invoices (0100000 / 0200000)
  • Sales Credit Notes (381) & Debit Notes (383) via REST API / OData Mapping
  • Free Text Invoices & Project Invoices (Requires Custom OData Entity / API Mapping)
  • Advance Payment / Prepayment Tax Invoices (386 — via API Payload Mapping)
  • Multi-Entity (`dataAreaId`) & Multi-Branch EGS Configurations
Transparent Engineering Scope

Dynamics 365 Finance 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

  • Microsoft Entra ID (Azure AD) OAuth 2.0 client_credentials token management & caching (D365Service.getAccessToken)
  • OData v4 connection verification (/data/Companies & /data/$metadata) and automated 2-minute polling of SalesInvoiceHeaders & SalesInvoiceHeadersV2
  • Pre-flight Saudi VAT number (BR-KSA-81), national address (BR-10), and tax category (S/Z/E/O) validation
  • UBL 2.1 XML generation, sequential ICV counter, SHA-256 PIH hash chaining, ECDSA secp256k1 signing, and 9-tag TLV QR encoding
  • ZATCA FATOORA Clearance & Reporting API submission + OData write-back caller (UpdateZatcaStatus & ZatcaIntegrationStatuses)
2. API-Based Integration

Standardized REST / OData Contract

  • Optional real-time push from D365 F&O Business Events / X++ HTTP client to POST /api/v1/erp/invoices or POST /api/v2/invoices/submit
  • HMAC-SHA256 payload signature verification (X-Signature, X-Timestamp, X-Nonce) and idempotency key protection
3. Customer-Specific ERP Scope

Tailored During Client Onboarding

  • Publishing the UpdateZatcaStatus X++ OData action or ZatcaIntegrationStatuses custom data entity in the customer’s D365 F&O environment
  • Mapping custom X++ invoice tables (such as customized ProjInvoiceJour or vertical sub-ledgers) if non-standard OData entities are used
  • Adding the returned Base64 TLV QR code and ZATCA UUID fields to the customer’s SSRS or Electronic Reporting (ER) invoice PDF layouts
Onboarding Roadmap

4-Step Dynamics 365 Finance Integration Process

01

F&O Data Model & Tax Code Mapping

Review your Dynamics 365 Finance legal entities, sales tax codes, customer address fields, and OData entities against ZATCA UBL 2.1 mandatory tags.

02

Azure AD Connector & X++ Write-Back Setup

Configure the pre-built Saky D365 OData connector in UAT and deploy the UpdateZatcaStatus / ZatcaIntegrationStatuses write-back entity in F&O.

03

ZATCA Sandbox & Compliance CSID Checks

Generate CSRs, onboard compliance CSIDs via FATOORA OTP, and execute standard, simplified, credit, and debit test scenarios.

04

SSRS Print Verification & Production Cutover

Switch to production CSIDs, verify SSRS PDF QR rendering, and monitor live clearance/reporting queues with your finance team.

Integration FAQ

Dynamics 365 Finance ZATCA Phase 2 Questions

Saky ZATCA Connect includes a pre-built D365 F&O OData v4 connector (Azure AD OAuth 2.0 authentication, automated polling of SalesInvoiceHeaders and SalesInvoiceHeadersV2, UBL 2.1 XML generation, ECDSA signing, ZATCA API submission, and OData status write-back). Customer-specific implementation is required inside your F&O environment to expose the UpdateZatcaStatus / ZatcaIntegrationStatuses write-back entity, map any custom X++ sub-ledger fields, and place the returned QR code onto your SSRS invoice print layout.
KSA Enterprise Integration Assessment

Request a Dynamics 365 Finance 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.