ZATCA-QR

An implementation of Saudi Arabia ZATCA's E-Invoicing requirements, processes, and standards in PHP.

Read the documentation PDFs or Systems Developers for more details.

Dependencies

If you plan on using the built in EGS module to generate keys, and CSR. The EGS module in the package is dependent on OpenSSL being installed in the system it's running on. It's being used to generate an ECDSA key pair using the secp256k1 curve. also to generate and sign a CSR.

All other parts of the package will work fine without OpenSSL. (meaning it supports react-native and other frameworks)

Supports

All tha main futures required to on-board a new EGS. Create, sign, and report a simplified tax invoice are currently supported.

• EGS (E-Invoice Generation System).
  • Creation/on-boarding (Compliance and Production x.509 CSIDs).
  • Cryptographic stamps generation.
• Simplified Tax Invoice.
  • Creation.
  • Signing.
  • Compliance checking.
  • Reporting.

Installation

1. Download the package from github
2. Run composer update or composer install to install dependencies.
3. Run a local server to view the examples using php -S localhost:8000
4. Open http://localhost:8000/phase-1.php in your browser.
5. Open http://localhost:8000/phase-2.php in your browser.
6. Download the ZATCA QR Reader App from Google Play Store. Zatca QR ReaderApp
7. Scan the QR code generated in the example.

Usage

View full example at phase-1.php and phase-2.php.

// New Invoice and EGS Unit
$egs = new \ZATCA\EGS($egsUnit);

$egs->production = false;

// New Keys & CSR for the EGS
list($privateKey, $csr) = $egs->generateNewKeysAndCSR('solution_name');

// Issue a new compliance cert for the EGS
list($requestId, $binarySecurityToken, $secret) = $egs->issueComplianceCertificate('123345', $csr);

// Sign invoice
list($signedInvoiceString, $invoiceHash, $qr) = $egs->signInvoice($invoice, $egsUnit, $binarySecurityToken, $privateKey);

// Check invoice compliance
echo($egs->checkInvoiceCompliance($signedInvoiceString, $invoiceHash, $binarySecurityToken, $secret));
echo PHP_EOL;

Implementation

• General implementation (More details)
  • KSA Rules & Business
  • UBL 2.1 Spec
  • ISO EN16931
  • UN/CEFACT Code List 1001
  • ISO 3166
  • ISO 4217:2015
  • UN/CEFACT Code List 5305, D.16B
• Security standards ( More details)
  • NCA National Cryptographic Standards (NCS - 1 : 2020)
  • NCDC Digital Signing Policy (Version 1.1: 2020)
  • ETSI EN 319 102-1
  • ETSI EN 319 132-1
  • ETSI EN 319 142-1
  • W3C XML-Signature Syntax and Processing
  • ETSI EN 319 122-1
  • IETF RFC 5035 (2007)
  • RFC 5280
  • ISO 32000-1
  • IETF RFC 5652 (2009)
  • RFP6749
  • NIST SP 56A

Notice of Non-Affiliation and Disclaimer

zatca-qr is influenced by zatca-xml-php that not affiliated, associated, authorized, endorsed by, or in any way officially connected with ZATCA ( Zakat, Tax and Customs Authority), or any of its subsidiaries or its affiliates. The official ZATCA website can be found at https://zatca.gov.sa.

Contribution

All contributions are appreciated.

I'm not planning on supporting Tax Invoices (Not simplified ones). If any one wants to tackle that part.