README

通过爬取SAT网站查询CFDI滞纳金状态的工具

🇺🇸 此项目的文档是西班牙语，因为这将是目标受众的自然语言。

关于 phpcfdi/sat-estado-retenciones

墨西哥的税务行政服务（SAT）提供了一些税务验证服务。

对于 常规CFDI（收入、支出、转移和工资）提供了SOAP类型的web服务，可以了解CFDI的状态（有效或已取消）。

对于 *滞纳金和支付信息CFDI（滞纳金CFDI）不提供web服务。SAT仅允许通过一个位于https://prodretencionverificacion.clouda.sat.gob.mx/的互联网页面查询其状态，并且似乎由一个验证码保护。

这个库允许利用SAT工具中错误的验证码实现，无需解决它。此外，它将网页响应转换为对象属性。

安装

使用 composer

composer require phpcfdi/sat-estado-retenciones

使用示例

<?php

use PhpCfdi\SatEstadoRetenciones\Exceptions\HttpClientException;
use PhpCfdi\SatEstadoRetenciones\Exceptions\RetentionNotFoundException;
use PhpCfdi\SatEstadoRetenciones\Service;

$contents = file_get_contents('archivo-de-retenciones.xml');

$service = new Service();
$parameters = $service->makeParametersFromXml($contents);

try {
    $result = $service->query($parameters);
} catch (RetentionNotFoundException $exception) {
    echo "El CFDI de retenciones {$exception->getParameters()->uuid} no fue encontrado.\n";
    return;
} catch (HttpClientException $exception) {
    echo "No se pudo conectar al servicio en la URL {$exception->getUrl()}.\n";
    return;
}

if ($result->statusDocument->isActive()) {
    echo "El CFDI de retenciones {$result->uuid} de {$result->receiverName} se encuentra ACTIVO.\n";
}

功能

这个库提供了一个名为 Service 的输入对象，可以使用它执行两个任务：生成查询参数 Parameters 和使用这些参数查询互联网页面。查询结果是一个 Result 对象。

目前，利用SAT页面没有正确实现验证码的错误，因此可以跳过这个步骤来查询状态。如果未来SAT实现了Web Service或正确实现了验证码，预计这个库将只需要做很少的接口更改。

参数构建

参数对象可以从UUID、发送方的RFC和接收方的RFC（如果存在）构建。同样，如果有XML文本或DOM对象，可以使用方法 Service::makeParametersFromXml(string $xml): Parameters 和 Service::makeParametersFromDocument(DOMDocument $document): Parameters 分别获取参数。

参数 Parameters 和结果 Result 实现了 JsonSerializable 接口，即使用函数 json_encode() 时导出其数据。

查询执行

方法 Service::query(Parameters $parameters): Result

执行CFDI滞纳金状态的查询并返回一个包含在 Result 对象中的结果。如果滞纳金CFDI未找到，将抛出 RetentionNotFoundException 异常。如果查询失败，由于与服务器连接错误，将抛出 HttpClientException 异常。

方法 Service::queryOrNull(Parameters $parameters): ?Result

存在一个名为 queryOrNull 的方法，它与 query 方法相同，但不会生成 RetentionNotFoundException 异常，而是返回 NULL。

结果

执行查询时返回一个包含网页提供的所有属性的 Result 对象。此外，它还包含3个特殊属性，用于解释文档的状态（有效或已取消）、EFOS状态（包含或排除）以及作为浮点数的总数。

scraper 策略

目前，通过爬取SAT页面来获取CFDI滞纳金状态。

爬虫可以被实现 ScraperInterface 接口的对象所替代。

ScraperInterface 的实现位于 Scraper 类中，并且直接依赖于 HTTP 客户端来执行单个 GET 类型的请求。

客户端可以被另一个实现 HttpClientInterface 接口的对象所替换。

HttpClientInterface 的实现位于 PhpStreamContextHttpClient 类中，该类使用 PHP Streams 来执行对 SAT 页面的请求。

如果想要用像 Guzzle 或 Symfony HTTP Client 这样的库来替换这个实现，则需要创建一个实现 HttpClientInterface 的对象。

异常

当执行参数查询时，可能会出现两种异常：当找不到滞留的 CFDI 时抛出 RetentionNotFoundException，当与服务通信出错时抛出 HttpClientException。

这两种异常都是 \RuntimeException 类型，并且实现了 SatEstadoRetencionesException 接口。

支持

您可以通过在 Github 上创建工单来获取支持。

此外，这个库属于 PhpCfdi 社区，因此您可以使用相同的通信渠道来获取社区成员的帮助。

兼容性

这个库将保持与最新版本的 PHP（具有活动支持）的兼容性。

我们还使用 语义版本 2.0.0，因此您可以放心地使用这个库而不用担心破坏您的应用程序。

• 从版本 1.x 到 2.x 的更新指南.

贡献

欢迎贡献。请阅读 CONTRIBUTING 获取更多详细信息，并记得检查待办事项文件 TODO 和 CHANGELOG 文件。

版权和许可

phpcfdi/sat-estado-retenciones 库版权 © PhpCfdi，并按照 MIT 许可协议（MIT）授权使用。有关更多信息，请参阅 LICENSE。