io.github.Morouna1/saudi-vat-pro

Saudi VAT Pro — ZATCA Phase 2 E-Invoicing

saudivat.pro automates ZATCA Phase 2 e-invoicing for Saudi Arabian businesses — WooCommerce stores, Shopify merchants, and custom integrations via REST API.

Every paid order becomes a ZATCA-compliant invoice. Every refund becomes a credit note. No developers required.

What's in this repo

The Platform

→ Sign up free at saudivat.pro

Saudi VAT Pro handles the complexity of ZATCA Phase 2 compliance so you don't have to:

• CSID onboarding — generate your Cryptographic Stamp Identifier in 5 minutes with the free CSID wizard
• B2B clearance — standard invoices cleared with ZATCA in real time before delivery
• B2C reporting — simplified invoices reported within 24 hours
• Credit notes — refunds automatically generate ZATCA-compliant credit notes
• Issue dashboard — plain-language explanations of every ZATCA rejection, with suggested fixes
• Retry & repair — re-submit failed invoices without touching code

Supported platforms

AI Agents & Model Context Protocol

The Saudi VAT Pro MCP server lets MCP-compatible AI assistants create and manage ZATCA invoices through the Saudi VAT Pro API.

{
  "mcpServers": {
    "saudi-vat-pro": {
      "command": "npx",
      "args": ["saudi-vat-pro-mcp"],
      "env": {
        "SAUDI_VAT_PRO_API_KEY": "svp_live_YOUR_KEY_HERE"
      }
    }
  }
}

Available tools cover invoice listing and details, standard and simplified invoice creation, idempotent credit notes, failed-invoice retries and explanations, merchant details, dashboard summaries, and ZATCA certificate readiness.

The server gives agents explicit ZATCA safeguards:

• Standard B2B invoices require buyer name, city, and a valid 15-digit VAT number
• VAT categories, rates, VATEX exemption reasons, and line discounts are validated before submission
• Sandbox and production environments are clearly distinguished
• Credit-note retries require an idempotency key to prevent duplicate refunds
• Every result exposes its actual lifecycle status instead of assuming clearance or reporting succeeded

Canonical links

• Source: mcp-server/
• Setup and API key: saudivatpro.com/docs#aiagents
• npm: saudi-vat-pro-mcp
• Official MCP Registry: io.github.Morouna1/saudi-vat-pro

Free Tools

ZATCA QR Tool

Decode and inspect any ZATCA Phase 1 or Phase 2 QR code, or generate a valid Phase 1 QR from invoice fields. No sign-up required.

• Paste a base64 QR string → see every TLV field decoded
• Fill invoice fields → get a valid QR code instantly
• Validation errors shown in plain English
• Download as PNG or copy base64

The TLV encode/decode logic is open-sourced in zatca-qr-helpers/.

Free CSID Wizard

Get your ZATCA Cryptographic Stamp Identifier (CSID) in 5 minutes — no account required. Step-by-step: enter your VAT number, generate a CSR, get your OTP from the Fatoora portal, download your certificate.

VAT Calculator

Instant VAT calculation for Saudi invoices — 15%, 5%, and 0% rates, with support for all four VAT treatment categories (S/Z/E/O).

Pricing

SAR 999 per 10,000 invoices — pay only for what you use.

• 60-day free trial, no credit card required
• Unlimited merchants per account
• No monthly fees

→ See full pricing

Knowledge Center

Free guides for Saudi merchants and developers:

• ZATCA Phase 2 Overview — what changed, who is affected, the clearance vs reporting flow
• QR Code Explained — every TLV tag decoded
• Common ZATCA Errors — BR-KSA error codes with fixes
• VAT Categories S/Z/E/O — when to use each code
• Standard vs Simplified Invoices — B2B vs B2C decision guide
• Credit Notes & Refunds — how to issue correctly

→ Full Knowledge Center

WooCommerce Plugin

The woocommerce-plugin/ folder contains the full GPLv2 source of the Saudi VAT Pro WooCommerce integration.

Quick install:

1. Download or clone this repo
2. Upload the woocommerce-plugin/ folder to /wp-content/plugins/saudi-vat-pro-woocommerce/
3. Activate the plugin in WordPress → Plugins
4. Go to WooCommerce → Settings → Saudi VAT Pro and paste your Webhook URL and API Key from the Saudi VAT Pro dashboard

Requires WooCommerce 7.0+, PHP 8.0+. Full documentation: saudivat.pro/docs

ZATCA QR Helpers (open source)

The zatca-qr-helpers/ folder contains a zero-dependency JavaScript/TypeScript library for encoding and decoding ZATCA TLV QR codes.

import { encodeTlvPhaseOne, decodeTlv, validateQr } from './zatca-qr-helpers/index.js';

// Generate a Phase 1 QR code
const base64 = encodeTlvPhaseOne({
  sellerName: 'Riyadh Gadgets Trading Co.',
  vatNumber:  '310000000000006',
  timestamp:  '2024-01-15T10:30:00Z',
  invoiceTotal: '1725.00',
  vatAmount:    '225.00',
});

// Decode any QR string
const parsed = decodeTlv(base64);
parsed.fields.forEach(f => console.log(f.tag, f.label, f.rawValue));

// Validate
const { valid, errors } = validateQr(base64);

See zatca-qr-helpers/README.md for full API reference.

Support & Issues

• Bug reports: Open an issue
• Support questions: Open a support question
• Documentation: saudivat.pro/knowledge
• Platform support: saudivat.pro/support

License

• WooCommerce plugin: GNU GPL v2.0
• ZATCA QR helpers: MIT
• Documentation: CC BY 4.0

Built by Morouna Business Services • saudivat.pro