Download the PHP package thesmarter/zatca without Composer

English | العربية

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
  • 1. Generate Certificate Signing Request (CSR)
  • 2. Request Compliance Certificate
  • 3. Hash Invoice XML
  • 4. Sign Invoice
  • 5. Check Compliance
  • 6. Generate Production Certificate
  • 7. Submit Invoice to ZATCA
• Environment Configuration
• Using the Facade
• Invoice Types
• API Reference
• Build UBL Invoices From Arrays
• Renew a Production Certificate
• Examples
• Testing
• Error Handling
• Best Practices
• ZATCA Integration Workflow
• Resources
• Contributing
• License
• Credits
• Support

Features

• Certificate Management: Generate CSR (Certificate Signing Request) and obtain compliance/production certificates, including production CSID renewal
• UBL Invoice Builder: Build standard/simplified invoices, credit and debit notes (388/383/381) from plain PHP arrays with automatic totals and VAT grouping
• Invoice Processing: Hash and sign XML invoices according to ZATCA specifications (namespace-aware DOM signing)
• QR Code Generation: Create compliant QR codes for both simplified and standard invoices
• Compliance Validation: Check invoice compliance before production submission
• Invoice Submission: Submit invoices to ZATCA via Reporting (simplified) or Clearance (standard) APIs
• Multi-Environment Support: Sandbox, Simulation, and Production environments
• Clean Architecture: Well-structured, maintainable, and testable code

Requirements

• PHP >= 8.1
• Required PHP extensions:
  • ext-openssl
  • ext-dom
  • ext-xsl
  • ext-json
  • ext-bcmath
  • ext-simplexml
• Composer for dependency management

Installation

Install the package via Composer:

Quick Start

1. Generate Certificate Signing Request (CSR)

First, generate a CSR and private key for your organization:

2. Request Compliance Certificate

Obtain a compliance certificate from ZATCA using your CSR and OTP:

3. Hash Invoice XML

Hash your unsigned invoice XML:

4. Sign Invoice

Sign the invoice with your private key and compliance certificate:

5. Check Compliance

Validate your signed invoice against ZATCA's compliance checks:

6. Generate Production Certificate

After successful compliance validation, request a production certificate:

7. Submit Invoice to ZATCA

Submit your signed invoice to ZATCA (Reporting for simplified, Clearance for standard):

Environment Configuration

The package supports three ZATCA environments:

Using the Facade (Alternative Approach)

The Zatca facade provides a cleaner, more convenient API for accessing all services. Instead of manually instantiating services and their dependencies, you can use the facade as a single entry point.

Benefits of Using the Facade

• Simplified API: Single entry point for all ZATCA operations
• Lazy Loading: Services are only instantiated when needed
• Dependency Management: Automatically handles service dependencies
• Cleaner Code: Less boilerplate, more readable

Facade Example: Complete Workflow

Facade API Methods

The Zatca facade provides the following methods:

Comparison: Traditional vs Facade

Traditional Approach:

Facade Approach:

The facade handles all dependency injection automatically, making your code cleaner and easier to maintain.

Invoice Types

When generating CSR, specify the invoice type using a 4-digit code:

• 1100 - Standard & Simplified Invoices
• 0100 - Simplified Invoice Only (B2C)
• 1000 - Standard Invoice Only (B2B)

Each digit acts as a boolean flag: [Standard, Simplified, Future Use, Future Use]

API Reference

Core Services

CertificateSigningRequestBuilder

Generates CSR and private key for ZATCA onboarding.

Methods:

• setCommonName(string $name) - Set common name
• setSerialNumber(string $solutionProvider, string $solutionName, string $serialNumber) - Set device serial number
• setOrganizationIdentifier(string $id) - Set organization tax ID
• setOrganizationalUnitName(string $name) - Set organizational unit
• setOrganizationName(string $name) - Set organization name
• setCountry(string $country) - Set country code (SA)
• setInvoiceType(string $type) - Set invoice type (e.g., '1100')
• setAddress(string $address) - Set business address
• setBusinessCategory(string $category) - Set business category
• generate() - Generate CSR and private key
• getCsr() - Get generated CSR
• getPrivateKey() - Get generated private key
• saveCsr(string $path) - Save CSR to file
• savePrivateKey(string $path) - Save private key to file

ComplianceService

Handles compliance certificate requests and validation.

Methods:

• requestComplianceCertificate(string $b64Csr, string $otp): CSID
• checkCompliance(string $binarySecurityToken, string $secret, string $invoiceHash, string $invoiceUuid, string $signedInvoice): ValidationResponse

InvoiceHashingService

Hashes invoice XML according to ZATCA specifications.

Methods:

• hash(string $unsignedInvoiceXml): InvoiceHashingResult

InvoiceSigningService

Signs invoices with digital signature and generates QR codes.

Methods:

• sign(CSID $csid, string $privateKeyContent, string $canonicalXml, string $invoiceHash): InvoiceSigningResult

QrCodeGeneratorService

Generates ZATCA-compliant QR codes.

Methods:

• generate(CSID $csid, string $invoiceHash, string $canonicalXml, string $signatureValue): string

ProductionCsidGeneratorService

Requests production certificates after compliance validation, and renews them when needed.

Methods:

• requestProductionCertificate(string $binarySecurityToken, string $secret, string $ccsidRequestId): CSID
• renewProductionCertificate(string $binarySecurityToken, string $secret, string $otp, string $b64Csr): CSID

InvoiceSubmissionService

Submits invoices to ZATCA via Reporting or Clearance APIs.

Methods:

• submit(CSID $csid, bool $isSimplified, string $invoiceHash, string $invoiceUuid, string $invoiceXml): SubmissionResponse

InvoiceBuilder

Builds UBL 2.1 invoice XML (unsigned) from plain PHP arrays, with automatic totals and VAT grouping.

Methods:

• InvoiceBuilder::simplified(array $data): string - Build a simplified (B2C) invoice
• InvoiceBuilder::standard(array $data): string - Build a standard (B2B) invoice
• InvoiceBuilder::build(array $data): string - Build any supported type (invoice 388, credit 383, debit 381)

Entities

CSID

Represents a Certificate Signing ID (compliance or production certificate).

Properties:

• string $certificate - Base64 encoded certificate
• string $secret - Certificate secret
• string $requestId - Request ID from ZATCA

Methods:

• static loadFromJson(string $filepath): self
• saveAsJson(string $filepath): void

InvoiceHashingResult

Result of invoice hashing operation.

Properties:

• string $invoiceHash - Base64 encoded SHA-256 hash
• string $uuid - Invoice UUID
• string $b64Invoice - Base64 encoded invoice
• string $b64CanonicalXml - Base64 encoded canonical XML

InvoiceSigningResult

Result of invoice signing operation.

Properties:

• string $signature - Digital signature
• string $b64SignedInvoice - Base64 encoded signed invoice
• string $b64QrCode - Base64 encoded QR code

SubmissionResponse

Response from invoice submission to ZATCA.

Properties:

• ValidationResults $validationResults - Validation messages
• string $status - Submission status (REPORTED/CLEARED)
• bool $isSubmitted - Whether submission was successful

ValidationResponse

Response from compliance validation.

Properties:

• ValidationResults $validationResults - Validation messages
• string|null $reportingStatus - Reporting status
• string|null $clearanceStatus - Clearance status
• string|null $qrSellerStatus - QR seller status
• string|null $qrBuyerStatus - QR buyer status

ValidationResults

Validation messages from ZATCA.

Properties:

• array $infoMessages - Informational messages
• array $warningMessages - Warning messages
• array $errorMessages - Error messages
• string $status - Overall validation status

Build UBL Invoices From Arrays

Supports invoice (388), credit (383) and debit (381) via 'type' => .... The builder emits the unsigned invoice (no UBLExtensions/QR/signature); feed it to the hashing service, then InvoiceSigningService::sign(), which inserts the fragments with namespace-aware DOM handling.

Renew a Production Certificate

Examples

Complete working examples are available in the examples/ directory:

1. 0_using_facade.php - Using the Zatca Facade (Recommended)
2. 1_generate_csr.php - Generate CSR and private key
3. 2_generate_compliance_csid.php - Request compliance certificate
4. 3_hash_invoice_xml.php - Hash invoice XML
5. 4_generate_qr_code_xml.php - Generate QR code
6. 5_sign_invoice_xml.php - Sign invoice
7. 6_check_compliance.php - Validate compliance
8. 7_generate_production_csid.php - Request production certificate
9. 8_build_ubl_invoice.php - Build a UBL invoice from PHP arrays
10. 9_renew_production_csid.php - Renew a production certificate

Testing

Run the test suite:

Or use PHPUnit directly:

Error Handling

The package throws specific exceptions for different error scenarios:

Best Practices

1. Store Certificates Securely: Keep your private keys and certificates in secure storage
2. Use Environment Variables: Store sensitive data like OTPs and secrets in environment variables
3. Validate Before Submission: Always check compliance before submitting to production
4. Handle Errors Gracefully: Implement proper error handling and logging
5. Test in Sandbox: Thoroughly test your integration in the sandbox environment
6. Keep Certificates Updated: Monitor certificate expiration and renew as needed

ZATCA Integration Workflow

Resources

• ZATCA E-Invoicing Portal
• ZATCA Developer Portal
• E-Invoicing Technical Documentation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT License.

Credits

Developed and maintained by Smart Team — eltayeb and CoderX249.

Support

For issues, questions, or contributions, please visit the GitHub repository.

Disclaimer: This is an unofficial package and is not affiliated with or endorsed by ZATCA. Use at your own risk and ensure compliance with all ZATCA regulations.