README

CARTA del DOCENTE

一个非官方包，用于轻松地将Carta del Docente集成到PHP项目中。

如果您使用Laravel框架，我还创建了一个专门包datomatic/laravel-carta-del-docente。

要求

PHP >= 8.0
ext-soap

安装

您可以通过composer安装此包

composer require datomatic/carta-del-docente

配置

为了使用此包，需要阅读官方文档，该文档解释了Carta del Docente的所有流程。

对于测试部分，一切准备就绪，无需生成任何证书（我已经为您准备好了）；只需通过电子邮件向docenti@sogei.it请求测试券即可。

对于生产部分，则需要根据指南生成证书。

使用方法

首先，需要使用证书相关数据和密码初始化客户端。

对于测试环境，证书和密码已经包含在包中（对所有用户相同）。

//Test
$testClient = new Datomatic\CartaDelDocente\CartaDelDocenteClient();

对于生产环境，需要提供证书的路径（最好不要将其公开）和相应的密码。

//Produzione
$client = new Datomatic\CartaDelDocente\CartaDelDocenteClient('../path/certificate.pem', 'passwordCertificato');

一旦客户端初始化完成，就可以使用所需的一些功能了。

检查

要执行券的检查，只需调用check函数，传入操作类型（1、2、3）和券码。

$result = $client->check(1, 'voucher');

如果操作成功，函数返回CartaDelDocenteResponse对象，如果出错，则返回RequestException异常。

CartaDelDocenteResponse对象包含以下属性

$result->name // CF o nominativo del beneficiario
$result->vatId // partita IVA esercente
$result->scope // l'ambito del voucher (cinema, teatro, libreria,...)
$result->good // il tipo di bene (libri, spettacoli,...)
$result->amount // importo totale del buono

确认

要执行券的确认，只需调用confirm函数，传入操作类型（1）、券码和确认金额。

$result = $client->confirm(1, 'Codice Voucher', 52.50);

商人激活

此操作只需在开始时执行一次，并且仅在生产环境中可用，因为测试环境中不需要。

$client->merchantActivation();

函数返回CartaDelDocenteResponse对象或出错时的RequestException异常。如果一切顺利，将返回以下对象

Datomatic\CartaDelDocente\CartaDelDocenteResponse {
  +name: "Attivazione effettuata"
  +vatId: "12345678901" // p.IVA esercente attivato
  +scope: "-"
  +good: "-"
  +amount: 0
}

如何生成有效的证书

要正确生成证书，需要在Linux / Mac OS或Windows的WSL终端上执行一些操作。

注意：如果您收到无效命令错误，可能需要手动输入整个命令而不是粘贴。

首先，我们需要创建用于在cartadeldocente网站上使用的证书请求。

openssl req -newkey rsa:2048 -keyout key.der -out req.der -outform DER

按下发送后，首先需要输入两次密码（PEM pass），然后填写以下字段

国家名称（2位代码）[AU]：// 国家名称，例如：IT
州或省名称（全名）[Some-State]：// 省份，例如：Vicenza
本地名称（例如，城市）[]: // 例如：Valdagno
组织名称（例如，公司）[Internet Widgits Pty Ltd]: // 例如：Acme srl
组织单位名称（例如，部门）[]: // 例如：Shop
通用名称（例如服务器FQDN或您的名称）[]: // 例如：Mario Rossi
电子邮件地址 []: // 电子邮件地址
挑战密码 []: // 一个新密码，为了方便我们将它与已输入的密码相同

获取到req.der文件后，我们可以将其上传到cartadeldocente网站上的证书请求表单中，然后几秒钟/分钟后我们可以下载文件PIVA.cer，我们将将其放入包含上述创建的其它文件的同一文件夹中。

获取到.der文件后，我们将将其转换为.pem格式（为了方便，我称这些文件为XXXXX，但你们将有增值税号）。

openssl x509 -inform DER -in XXXXX.cer -out XXXXX.pem

然后我们将其与第一步骤中生成的密钥组合，转换为一个.p12文件

openssl pkcs12 -export -inkey key.der -in XXXXX.pem  -out XXXXX.p12

最后，我们将.p12证书转换为最终用于生产的result.pem证书

openssl pkcs12 -in 02017240249.p12 -out result.pem -clcerts

因此，要使用该包进行生产，需要设置result.pem文件的路径。

测试

composer test

变更日志

请参阅变更日志以获取有关最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

请查看我们的安全策略以了解如何报告安全漏洞。

鸣谢

许可

MIT许可（MIT）。请参阅许可文件以获取更多信息。

datomatic / carta-del-docente

维护者

详细信息