{
  "markdown": "<p align=\"center\">\n  <img src=\"./assets/logo.png\" alt=\"Saudi VAT Pro\" width=\"220\" />\n</p>\n\n# Saudi VAT Pro — ZATCA Phase 2 E-Invoicing\n\n[![License: GPL v2](https://img.shields.io/badge/License-GPLv2-blue.svg)](https://www.gnu.org/licenses/gpl-2.0)\n[![Platform](https://img.shields.io/badge/platform-saudivat.pro-green)](https://saudivat.pro)\n[![ZATCA Phase 2](https://img.shields.io/badge/ZATCA-Phase%202%20Compliant-brightgreen)](https://zatca.gov.sa)\n\n**[saudivat.pro](https://saudivat.pro)** automates ZATCA Phase 2 e-invoicing for Saudi Arabian businesses — WooCommerce stores, Shopify merchants, and custom integrations via REST API.\n\nEvery paid order becomes a ZATCA-compliant invoice. Every refund becomes a credit note. No developers required.\n\n---\n\n## What's in this repo\n\n| Folder | Contents |\n|--------|----------|\n| [`woocommerce-plugin/`](./woocommerce-plugin/) | GPLv2 WooCommerce plugin — automatic ZATCA invoicing for every WooCommerce order |\n| [`zatca-qr-helpers/`](./zatca-qr-helpers/) | Open-source TLV encode/decode library behind the [free ZATCA QR Tool](https://saudivat.pro/zatca-qr/) |\n| [`docs/`](./docs/) | Support guides: ZATCA Phase 2 overview, QR code explained, common errors |\n| [`mcp-server/`](./mcp-server/) | MCP server for Claude, Cursor, Windsurf, and other AI agents |\n\n---\n\n## The Platform\n\n### [→ Sign up free at saudivat.pro](https://saudivat.pro/signup)\n\nSaudi VAT Pro handles the complexity of ZATCA Phase 2 compliance so you don't have to:\n\n- **CSID onboarding** — generate your Cryptographic Stamp Identifier in 5 minutes with the [free CSID wizard](https://saudivat.pro/tools/csid)\n- **B2B clearance** — standard invoices cleared with ZATCA in real time before delivery\n- **B2C reporting** — simplified invoices reported within 24 hours\n- **Credit notes** — refunds automatically generate ZATCA-compliant credit notes\n- **Issue dashboard** — plain-language explanations of every ZATCA rejection, with suggested fixes\n- **Retry & repair** — re-submit failed invoices without touching code\n\n### Supported platforms\n\n| Platform | How |\n|----------|-----|\n| WooCommerce | [Plugin in this repo](./woocommerce-plugin/) — install, enter API key, done |\n| Shopify | Webhook integration — documented at [saudivat.pro/docs](https://saudivat.pro/docs) |\n| Custom / ERP | REST API — see [API documentation](https://saudivat.pro/docs) |\n| AI agents | [Saudi VAT Pro MCP](./mcp-server/) — Claude, Cursor, Windsurf, and generic MCP clients |\n\n---\n\n## AI Agents & Model Context Protocol\n\nThe [Saudi VAT Pro MCP server](./mcp-server/) lets MCP-compatible AI assistants create and manage ZATCA invoices through the Saudi VAT Pro API.\n\n```json\n{\n  \"mcpServers\": {\n    \"saudi-vat-pro\": {\n      \"command\": \"npx\",\n      \"args\": [\"saudi-vat-pro-mcp\"],\n      \"env\": {\n        \"SAUDI_VAT_PRO_API_KEY\": \"svp_live_YOUR_KEY_HERE\"\n      }\n    }\n  }\n}\n```\n\nAvailable 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.\n\nThe server gives agents explicit ZATCA safeguards:\n\n- Standard B2B invoices require buyer name, city, and a valid 15-digit VAT number\n- VAT categories, rates, VATEX exemption reasons, and line discounts are validated before submission\n- Sandbox and production environments are clearly distinguished\n- Credit-note retries require an idempotency key to prevent duplicate refunds\n- Every result exposes its actual lifecycle status instead of assuming clearance or reporting succeeded\n\n**Canonical links**\n\n- Source: [`mcp-server/`](./mcp-server/)\n- Setup and API key: [saudivatpro.com/docs#aiagents](https://saudivatpro.com/docs#aiagents)\n- npm: [`saudi-vat-pro-mcp`](https://www.npmjs.com/package/saudi-vat-pro-mcp)\n- Official MCP Registry: [`io.github.Morouna1/saudi-vat-pro`](https://registry.modelcontextprotocol.io/?q=io.github.Morouna1%2Fsaudi-vat-pro)\n\n---\n\n## Free Tools\n\n### [ZATCA QR Tool](https://saudivat.pro/zatca-qr/)\n\nDecode 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.\n\n- Paste a base64 QR string → see every TLV field decoded\n- Fill invoice fields → get a valid QR code instantly\n- Validation errors shown in plain English\n- Download as PNG or copy base64\n\nThe TLV encode/decode logic is open-sourced in [`zatca-qr-helpers/`](./zatca-qr-helpers/).\n\n### [Free CSID Wizard](https://saudivat.pro/tools/csid)\n\nGet 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.\n\n### [VAT Calculator](https://saudivat.pro/knowledge/vat-calculator)\n\nInstant VAT calculation for Saudi invoices — 15%, 5%, and 0% rates, with support for all four VAT treatment categories (S/Z/E/O).\n\n---\n\n## Pricing\n\n**SAR 999 per 10,000 invoices** — pay only for what you use.\n\n- 60-day free trial, no credit card required\n- Unlimited merchants per account\n- No monthly fees\n\n[→ See full pricing](https://saudivat.pro/pricing)\n\n---\n\n## Knowledge Center\n\nFree guides for Saudi merchants and developers:\n\n- [ZATCA Phase 2 Overview](https://saudivat.pro/knowledge/zatca-phase-2) — what changed, who is affected, the clearance vs reporting flow\n- [QR Code Explained](https://saudivat.pro/knowledge/qr-code-explained) — every TLV tag decoded\n- [Common ZATCA Errors](https://saudivat.pro/knowledge/common-errors) — BR-KSA error codes with fixes\n- [VAT Categories S/Z/E/O](https://saudivat.pro/knowledge/vat-categories) — when to use each code\n- [Standard vs Simplified Invoices](https://saudivat.pro/knowledge/invoice-types) — B2B vs B2C decision guide\n- [Credit Notes & Refunds](https://saudivat.pro/knowledge/credit-notes) — how to issue correctly\n\n[→ Full Knowledge Center](https://saudivat.pro/knowledge)\n\n---\n\n## WooCommerce Plugin\n\nThe [`woocommerce-plugin/`](./woocommerce-plugin/) folder contains the full GPLv2 source of the Saudi VAT Pro WooCommerce integration.\n\n**Quick install:**\n1. Download or clone this repo\n2. Upload the `woocommerce-plugin/` folder to `/wp-content/plugins/saudi-vat-pro-woocommerce/`\n3. Activate the plugin in WordPress → Plugins\n4. Go to WooCommerce → Settings → Saudi VAT Pro and paste your Webhook URL and API Key from the [Saudi VAT Pro dashboard](https://saudivat.pro/dashboard)\n\nRequires WooCommerce 7.0+, PHP 8.0+. Full documentation: [saudivat.pro/docs](https://saudivat.pro/docs)\n\n---\n\n## ZATCA QR Helpers (open source)\n\nThe [`zatca-qr-helpers/`](./zatca-qr-helpers/) folder contains a zero-dependency JavaScript/TypeScript library for encoding and decoding ZATCA TLV QR codes.\n\n```js\nimport { encodeTlvPhaseOne, decodeTlv, validateQr } from './zatca-qr-helpers/index.js';\n\n// Generate a Phase 1 QR code\nconst base64 = encodeTlvPhaseOne({\n  sellerName: 'Riyadh Gadgets Trading Co.',\n  vatNumber:  '310000000000006',\n  timestamp:  '2024-01-15T10:30:00Z',\n  invoiceTotal: '1725.00',\n  vatAmount:    '225.00',\n});\n\n// Decode any QR string\nconst parsed = decodeTlv(base64);\nparsed.fields.forEach(f => console.log(f.tag, f.label, f.rawValue));\n\n// Validate\nconst { valid, errors } = validateQr(base64);\n```\n\nSee [`zatca-qr-helpers/README.md`](./zatca-qr-helpers/README.md) for full API reference.\n\n---\n\n## Support & Issues\n\n- **Bug reports:** [Open an issue](../../issues/new?template=bug_report.md)\n- **Support questions:** [Open a support question](../../issues/new?template=support_question.md)\n- **Documentation:** [saudivat.pro/knowledge](https://saudivat.pro/knowledge)\n- **Platform support:** [saudivat.pro/support](https://saudivat.pro/support)\n\n---\n\n## License\n\n- WooCommerce plugin: [GNU GPL v2.0](./LICENSE)\n- ZATCA QR helpers: [MIT](./zatca-qr-helpers/README.md)\n- Documentation: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)\n\n---\n\n*Built by [Morouna Business Services](https://saudivat.pro) • [saudivat.pro](https://saudivat.pro)*\n",
  "bytes": 8001,
  "sha": "36e45026f151770f85dbe6b7f137f86659b1674a1fab9d6ed9a60eab5a637157",
  "repo_slug": "morouna1/saudivatpro",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_morouna1_saudi_vat_pro_b9ca17cf/readme"
}