README

ZATCA (Fatoora) QR-Code 实现

由 Salla 维护的非官方包，帮助开发人员轻松实现 ZATCA (Fatoora) QR 码，这对于电子发票是必需的。
探索我们的博客 »

报告错误 · 请求功能 · </Salla Developers>

要求

• PHP >= 8.0
• Ambstring 扩展
• ext-dom 扩展

安装

您可以通过 composer 安装此包

$ composer require salla/zatca

(返回顶部)

用法

此库支持第一阶段和第二阶段。

第二阶段包括将纳税人的系统与 ZATCA 集成，以及将电子发票和电子账单传输到 ZATCA。

生成 CSR

您需要通过 ZATCA API 将商家注册，以便代表商家签署发票。

use Salla\ZATCA\GenerateCSR;
use Salla\ZATCA\Models\CSRRequest;

$data = CSRRequest::make()
    ->setUID('string $OrganizationIdentifier')
    ->setSerialNumber('string $solutionName', 'string $version', 'string $serialNumber')
    ->setCommonName('string $commonName')
    ->setCountryName('SA')
    ->setOrganizationName('string $organizationName')
    ->setOrganizationalUnitName('string $organizationalUnitName')
    ->setRegisteredAddress('string $registeredAddress')
    ->setInvoiceType(true, true) //invoice types , the default is true, true
    ->setCurrentZatcaEnv('string $currentEnv') //support all modes ['sandbox','simulation','core']
    ->setBusinessCategory('string $businessCategory');

$CSR = GenerateCSR::fromRequest($data)->initialize()->generate();

// writing the private_key to file
openssl_pkey_export_to_file($CSR->getPrivateKey(), 'output file path name');

//writing the csr_content to file
file_put_contents('output file path name', $CSR->getCsrContent());

在此阶段，您需要通过 API 将 CSR 分享给 ZATCA 以获取当前商家的证书

签署发票 & 生成 QR 码

use Salla\ZATCA\Helpers\Certificate;
use Salla\ZATCA\Models\InvoiceSign;

$xmlInvoice = 'xml invoice text';

$certificate = (new Certificate(
    'certificate plain text (base64 decoded)', // get from ZATCA when you exchange the CSR via APIs
    'private key plain text' // generated at stage one
))->setSecretKey('secret key text'); // get from ZATCA when you exchange the CSR via APIs

$invoice = (new InvoiceSign($xmlInvoice, $certificate))->sign();

// invoice Hash: $invoice->getHash()
// invoice signed as XML: $invoice->getInvoice()
// Invoice QR code as base64: $invoice->getQRCode()

以 Base64 生成 QR 码

最好使用 InvoiceSign 类在相同的过程中签署发票并为其生成 QR 码

<?php

use Salla\ZATCA\GenerateQrCode;
use Salla\ZATCA\Helpers\UXML;
use Salla\ZATCA\Helpers\Certificate;

$xmlInvoice = 'xml invoice text';

$certificate = (new Certificate(
    'certificate plain text (base64 decoded)', // get from ZATCA when you exchange the CSR via APIs
    'private key plain text' // generated at stage one
))->setSecretKey('secret key text'); // get from ZATCA when you exchange the CSR via APIs

$tags = UXML::fromString($xmlInvoice)->toTagsArray($certificate);

$QRCodeAsBase64 = GenerateQrCode::fromArray($tags)->toBase64();

// Invoice Hash: $tags[5]->getValue()
// Digital Signature: $tags[6]->getValue()

//$QRCodeAsBase64 output will be like this
//AQ1TYWxsYSAtIFNhbGxhAg8zMTA0NjE0MzU3MDAwMDMDFDIwMjMtMTItMzFUMjE6MDA6MDBaBAY0MDguNjkFBTUzLjMxBiw1TXZmVmZTWGRSZzgyMWU4Q0E3bE1WcDdNS1J4Q2FBWWZHTm90THlHNUg4PQdgTUVRQ0lEOGthSTF1Z29EcWJkN3NEVmFCVE9yOUswWlVwRkZNY2hON2FsNGgyTEhrQWlCYnZxZktkK0xaN0hEc0FMakxmeTA0dTBMNVRhcjhxenowYjBlb0EzMUtIdz09CFgwVjAQBgcqhkjOPQIBBgUrgQQACgNCAATmBleqoCAfxDveLQVAKCvHSjNxoudWhRNQ8zThTxzBtgjAqZQ7vBJWvu2Ut0MxYa8vq7O4tgusgmcLBDhK/xNCCUcwRQIhAIhuJ6o4ETNSosMEf/OLVbp+TZqi2IGSxsgyC54yZgQAAiB3lwym6zpkPspQrT+luMte/ifw4THG+waV+SmXNSukmQ==

生成 Base64（第一阶段）

use Salla\ZATCA\GenerateQrCode;
use Salla\ZATCA\Tags\InvoiceDate;
use Salla\ZATCA\Tags\InvoiceTaxAmount;
use Salla\ZATCA\Tags\InvoiceTotalAmount;
use Salla\ZATCA\Tags\Seller;
use Salla\ZATCA\Tags\TaxNumber;

$generatedString = GenerateQrCode::fromArray([
    new Seller('Salla'), // seller name        
    new TaxNumber('1234567891'), // seller tax number
    new InvoiceDate('2021-07-12T14:25:09Z'), // invoice date as Zulu ISO8601 @see https://en.wikipedia.org/wiki/ISO_8601
    new InvoiceTotalAmount('100.00'), // invoice total amount
    new InvoiceTaxAmount('15.00') // invoice tax amount
])->toBase64();

// > Output
// AQVTYWxsYQIKMTIzNDU2Nzg5MQMUMjAyMS0wNy0xMlQxNDoyNTowOVoEBjEwMC4wMAUFMTUuMDA=

生成纯文本

use Salla\ZATCA\GenerateQrCode;
use Salla\ZATCA\Tags\InvoiceDate;
use Salla\ZATCA\Tags\InvoiceTaxAmount;
use Salla\ZATCA\Tags\InvoiceTotalAmount;
use Salla\ZATCA\Tags\Seller;
use Salla\ZATCA\Tags\TaxNumber;

$generatedString = GenerateQrCode::fromArray([
    new Seller('Salla'), // seller name        
    new TaxNumber('1234567891'), // seller tax number
    new InvoiceDate('2021-07-12T14:25:09Z'), // invoice date as Zulu ISO8601 @see https://en.wikipedia.org/wiki/ISO_8601
    new InvoiceTotalAmount('100.00'), // invoice total amount
    new InvoiceTaxAmount('15.00') // invoice tax amount
    // .....
])->toTLV();

// Render A QR Code Image
// data:image/png;base64, .........
$displayQRCodeAsBase64 = GenerateQrCode::fromArray([
    new Seller('Salla'), // seller name        
    new TaxNumber('1234567891'), // seller tax number
    new InvoiceDate('2021-07-12T14:25:09Z'), // invoice date as Zulu ISO8601 @see https://en.wikipedia.org/wiki/ISO_8601
    new InvoiceTotalAmount('100.00'), // invoice total amount
    new InvoiceTaxAmount('15.00') // invoice tax amount
    // .......
])->render();

// now you can inject the output to src of html img tag :)
// <img src="$displayQRCodeAsBase64" alt="QR Code" />

(返回顶部)

读取 QR 码

QR 码的输出对人类👀不可读，并且一些 QR 码读取器可能显示无效的输出，因为此 QR 码将在所有集成步骤完成后由 ZATCA 应用扫描。如果您想查看最终 QR 码图像的输出，可以使用以下网站

https://www.onlinebarcodereader.com/

测试

composer test

(返回顶部)

支持

团队始终在这里帮助您。遇到问题了吗？想报告错误？您可以在 Github 上使用 问题跟踪器 提交一个。如果您还有任何问题，请通过加入 Telegram 上的 Salla 全球开发人员社区或通过 支持电子邮件 联系我们。

贡献

贡献使开源社区成为一个如此令人惊叹的学习、灵感和创造的地方。您所做出的任何贡献都 非常欢迎。

如果您有任何改进建议，请将该仓库 fork 并创建一个 pull request。您也可以简单地创建一个带有“增强”标签的问题。别忘了给项目 star！再次感谢！

1. 分支项目
2. 创建您的功能分支 (git checkout -b feature/AmazingFeature)
3. 提交您的更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

(返回顶部)

安全

如果您发现任何与安全相关的问题，请通过电子邮件security@salla.sa联系，而不是使用问题跟踪器。

鸣谢

• Salla
• 所有贡献者

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

(返回顶部)