README

波兰财政部JPK WebService网关。

使用方法

prepareDocumentToSend方法

准备带有电子签名的元数据文件。该文件基于主JPK文件创建。文件经过ZIP压缩，生成包含单个JPK文档的ZIP文件。如果接收到的ZIP文件大小超过60MB，则将其二进制分割成大小为60MB的适当数量的部分，最后部分大小不超过60MB。然后，生成的部分使用随机生成的AES密钥加密。此密钥使用财政部提供的公钥加密，并保存到元数据文件中，其中包含有关原始JPK文件的信息以及有关加密部分的信息。

构造函数参数

• $dir - 存储生成的文件的目录。在调用库之前，该目录必须存在并具有读写权限。

输入数据

• $file - XML JPK文件的存放位置。

输出数据（数组）

• 包含待签名字符串和磁盘上文件位置的数组
• 包含ZIP文件和加密部分的位置的数组
• 未加密的AES密钥
• 加密向量的base64加密

<?php

use SJRoyd\MF\EDokumenty\JPK;

$dir = 'some/dierctory'; // directory must exists
$jpkFileLocation = 'file/location'; // location of XML JPK file

$jpk = new JPK($dir);
$initData = $jpk->prepareDocumentToSend($jpkFileLocation);
/* [
    'init' => [
        'xml' => '', // XML metadata string for signing
        'file' => '', // XML metadata file location
    ],
    'jpk' => [
        'zip' => '', // ZIP compressed JPK XML file location
        'chunks' => [], // AES encrypted JPK XML ZIP file chunks
    ],
    'aesKey' => '', // AES key for encrypted ZIP chunks
    'vectorKey' => '' // base64 vector key for AES encryptor
] */

sendDocument方法

该方法用于通过财政部网关发送已签名文档和加密文件，并接收文档处理状态。

构造函数参数

• $dir - 存储之前生成的AES加密文件的目录。

输入数据

• $file - 签名元数据XML文件的位置。
• $validateQualSig - 布尔值，如果为true（在测试环境中），系统将验证发送的文件是否使用有效的波兰或欧洲合格签名或可信配置文件进行签名。

输出（Response\Status实例）方法

• getCode() - 状态代码
• getDescription() - 描述
• getMessage() - 返回 "($code) $description";
• getDetails() - 事件详情
• getTimestamp() - 时间戳
• getUpo() - 可选，官方收据证书（UPO）

代码列表

• 100 - 文件传输会话开始。
• 101 - 接收了X个Y个声明的文件。
• 102 - 请重新发送UPO请求。
• 110 - 会话已过期，未上传指定数量的文件。
• 120 - 会话正确结束。数据已正确保存。文档正在验证。
• 200 - 文档处理成功完成，下载UPO。
• 300 - 无效的参考号。
• 301 - 正在处理的文档，检查下一个文档验证的结果。
• 302 - 预处理文档，检查下一个文档验证的结果。
• 303 - 文档正在验证，检查下一个文档验证的结果。
• 401 - 负面验证 - 文档不符合XSD架构。
• 403 - 签名错误的文档。
• 404 - 无效证书的文档。
• 405 - 已吊销证书的文档。
• 406 - 支持的提供程序不支持的证书文档。
• 407 - 您已发送重复的文档。原始的参考号为XXXXXXX。
• 408 - 文档包含阻止其处理的错误。
• 409 - 文档包含错误数量和/或类型不正确的元素。
• 410 - 上传的文件不是有效的ZIP存档。
• 411 - 合并文档时出错（文档分割错误）。
• 412 - 文档加密错误。
• 413 - 文档校验和与声明的值不匹配。
• 414 - 文档部分（文件……）的校验和不匹配声明的值。
• 415 - 传输的文档类型不受系统支持。

可能的错误（PHP异常实例）

• InitUpload\Error_400

  错误代码

  • 100 - 无效的XML；指定的文档不是XML文档
  • 110 - 未签名的文档；根据规范提供的文档未签名
  • 111 - 签名格式不是XAdES-BES
  • 112 - 签名错误。无法验证；验证签名时发生意外错误
  • 113 - 使用不受支持的外部格式（分离）的签名；支持的签名格式是封装和封装
  • 114 - 读取已签名的对象有问题
  • 120 - 签名验证失败；签名无法正确验证
  • 130 - 签名中的引用已负面验证。数据可能已被修改
  • 135 - 使用非合格签名的文档；在生产环境中检查合格签名的真实性
  • 140 - 上传的文件不符合XSD模式；无法根据InitUpload.xsd模式验证文档
  • 150 - 不受支持的表单代码：“特定系统代码”；表单代码不受支持
  • 160 - “特定HashValue”值未用Base64编码；声明为传输的文件必须用Base64编码

  • 170 - 发送了已处理的文档的副本。原始参考号：XXXXXXX；根据声明的JPK文档的SHA-256哈希值检查副本

• InitUpload\Error_500

• FinishUpload\Error_400
• FinishUpload\Error_500
• Status\Error_400
• Status\Error_500

错误处理方法

• getCode() - 错误代码
• getMessage() - 错误消息
• getRequestId() - 错误请求的唯一ID
• getErrors() - 可选，文本错误列表
• hasErrors() - 检查错误列表中是否存在任何项目
• getFullMessage() 返回 "($code) $message"

<?php

use SJRoyd\MF\EDokumenty\JPK;
use SJRoyd\MF\EDokumenty\Storage\Response\InitUpload;
use SJRoyd\MF\EDokumenty\Storage\Response\FinishUpload;
use SJRoyd\MF\EDokumenty\Storage\Response\Status;

$dir = 'some/directory'; // a directory with AES encrypted files 
$signedFileLocation = 'file/location'; // a location of signed metadata file

$jpk = new JPK($dir);
try {
    $status = $jpk->sendDocument($signedFileLocation);
    $referenceNumber = $jpk->getReferenceNumber();
} catch (InitUpload\Error_400 $e) {
    echo $e->getFullMessage();
} catch (InitUpload\Error_500 $e) {
    // ...
} catch (FinishUpload\Error_400 $e) {
    // ...
} catch (FinishUpload\Error_500 $e) {
    // ...
} catch (Status\Error_400 $e) {
    // ...
} catch (Status\Error_500 $e) {
    // ...
} catch (\Exception $e){
    echo $e->getMessage();
}

getReferenceNumber方法

在sendDocument()方法之后直接调用的方法。它允许您获取您发送的文档的参考号。

checkStatus方法

该方法返回已发送文档的官方确认收据（UPO）。

输入数据

• $referenceNumber - 参考号。

输出（Response\Status实例）方法：如上所述。

<?php

use SJRoyd\MF\EDokumenty\JPK;
use SJRoyd\MF\EDokumenty\Storage\Response;

$referenceNumber = '04beb97601e10f210000004546830'; // reference number obtained using the getReferenceNumber() method

$jpk = new JPK();
try {
    $status = $jpk->checkStatus($referenceNumber);
    print_r($status);
} catch (Status\Error_400 $e) {
    echo $e->getFullMessage();
} catch (Status\Error_500 $e) {
    // ...
} catch (\Exception $e){
    echo $e->getMessage();
}