Download the PHP package hamada-emam-tech/einvoice-zatca without Composer

On this page you can find all versions of the php package hamada-emam-tech/einvoice-zatca. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package einvoice-zatca

hamada-emam-tech/einvoice-zatca

ZATCA (Fatoora) for hamada-emam-tech/einvoice: Saudi e-invoicing, phase 2. It writes the UBL 2.1 XML, stamps it (ECDSA on secp256k1, XAdES, QR code), onboards your EGS unit, then clears or reports each invoice.

Installing it is enough: the core finds the zatca authority by itself. Any PSR-18 client works. Guzzle, Symfony HttpClient and php-http/discovery are picked up automatically, or pass http_client, request_factory and stream_factory.

Tested live against ZATCA's developer portal: onboarding, the compliance check of all six document types (simplified and standard invoice, credit note, debit note) with no warnings, the production CSID, then one invoice reported and one cleared. See what was verified before you go to production.

1. Onboard the EGS unit (once per unit)

An EGS unit is one thing that issues invoices: a POS, a branch, an ERP instance. Each one gets its own key and certificate (CSID).

The CSR is built in PHP and signed through the key source: no openssl.cnf, no temp files.

Then sign one test document of every type you declared with the compliance certificate, and send them to the compliance check:

2. Configure

3. Issue invoices

submit() picks the endpoint for you:

Document Endpoint What you get back
Simplified (B2C): buyer without a VAT number POST /invoices/reporting/single reportingStatus REPORTED
Standard (B2B): buyer with a VAT number POST /invoices/clearance/single clearanceStatus CLEARED, and the cleared XML in $result->accepted[0]->content
Compliance mode ('compliance' => true) POST /compliance/invoices the validation result only

For a standard invoice, share the cleared XML with the buyer: ZATCA adds its own stamp and QR to it.

ZATCA answers every call at once, so there is no status() call. Keep the SubmissionResult. A rejected document is data: $result->rejected[0]->errors holds ZATCA's codes and messages. Warnings on an accepted document are in $result->accepted[0]->warnings.

extra.zatca keys

Key Default Meaning
icv required Invoice counter of the EGS unit, a positive integer
previous_hash the hash of "0" (first invoice) Hash of the unit's previous invoice (PIH)
simplified true when the buyer has no VAT number Simplified (B2C) or standard (B2B)
supply_date the issue date Delivery date, standard invoices only
payment_means 10 (cash) UN/ECE 4461 code: 30 credit transfer, 42 bank account, 48 card, 1 not defined
reason required on credit and debit notes Why the note was issued

Credit and debit notes are InvoiceType::CreditNote and InvoiceType::DebitNote, with referencedInvoice set to the original invoice number.

Tax categories: S (standard), Z (zero rated), E (exempt) and O (out of scope). Every category except S needs an exemption code (VATEX-SA-...) and reason on the line's tax: Tax::percent('E', '0', $net, $reason, 'VATEX-SA-29').

The ICV and PIH chain is yours

Each EGS unit numbers its invoices (ICV) and links each invoice to the hash of the one before it (PIH). This package cannot know your previous invoice. Store $signed->hash per unit and pass it as the next previous_hash, in order, from one place at a time (a queue or a lock per unit). The developer portal does not check this chain, so a broken chain will not show up in sandbox tests.

What was verified, and what was not

Verified live on the developer portal (https://gw-fatoora.zatca.gov.sa/e-invoicing/developer-portal):

Points to confirm on simulation before production:

Not handled in this version: currencies other than SAR, document-level allowances and charges, prepayments, the special transaction flags (third party, nominal, export, summary, self-billed), and CSID renewal. Open an issue if you need one of them.

Sources

License

MIT


All versions of einvoice-zatca with dependencies

PHP Build Version
Package Version
Requires php Version ^8.2
ext-dom Version *
ext-json Version *
ext-openssl Version *
ext-xmlwriter Version *
hamada-emam-tech/einvoice Version ^0.1
psr/http-client Version ^1.0
psr/http-factory Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package hamada-emam-tech/einvoice-zatca contains the following files

Loading the files please wait ...