easybill/e-invoice-validator

e-invoice-validator

概述

e-invoice-validator是一个小型服务，用于根据factur-x、Peppol BIS、XRechnung和EN***的官方schematron规则验证XML文件。它暴露验证接口，接收待验证XML并返回包含警告或错误的JSON结果，HTTP状态码200表示有效，400表示存在问题，支持UBL和CII格式。

当前支持的验证标准

• EN*** v1.3.13
• XRechnung v3.2
• Peppol BIS 3.0
• factur-x v1.07.2（仅支持EN***和EXTENDED配置文件）

使用方法

该服务以容器化设计为主，建议通过Docker镜像部署，并从主应用向服务发送HTTP请求完成验证。

Docker Compose配置

服务提供健康检查接口/health（用于确认服务就绪）和/swagger（OpenAPI文档入口）：

yaml
e-invoice-validator:
  image: 'docker.xuanyuan.run/easybill/e-invoice-validator:latest'
  ports:
    - '8081:8080'
  environment:
      JAVA_TOOL_OPTIONS: -Xmx512m
  healthcheck:
    test: curl --fail http://localhost:8081/health || exit 0
    interval: 10s
    retries: 6

启动服务

bash
docker compose up --detach --wait --wait-timeout 30

PHP调用示例

PHP
<?php

declare(strict_types=1);

final class EN16931Validator
{
    public function isValid(string $xml): ?bool
    {
        $httpClient = new Client();

        $response = $httpClient->request('POST', 'http://localhost:8081/validation', [
            RequestOptions::HEADERS => [
                'Content-Type' => 'application/json',
            ],
            RequestOptions::BODY => $xml,
            RequestOptions::TIMEOUT => 10,
            RequestOptions::CONNECT_TIMEOUT => 10,
            RequestOptions::HTTP_ERRORS => false,
        ]);

        return 200 === $response->getStatusCode();
    }
}

验证结果示例

• 有效XML响应：

JSON
{
  "meta": {
    "xml_syntax_type": "CII",
    "xml_profile_type": "FACTURX_EXTENDED"
  },
  "errors": [],
  "warnings": [],
  "is_valid": true
}

• 无效XML响应：

JSON
{
  "meta": {
    "xml_syntax_type": "CII",
    "xml_profile_type": "EN16931"
  },
  "errors": [
    {
      "rule_id": "BR-CO-15",
      "rule_location": "/*:CrossIndustryInvoice[namespace-uri()='urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100'][1]",
      "rule_severity": "FATAL",
      "rule_messages": [
        "[BR-CO-15]-Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110)."
      ]
    },
    {
      "rule_id": "BR-CL-04",
      "rule_location": "/*:CrossIndustryInvoice[namespace-uri()='urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100'][1]/*:SupplyChainTradeTransaction[namespace-uri()='urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100'][1]/*:ApplicableHeaderTradeSettlement[namespace-uri()='urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100'][1]/*:InvoiceCurrencyCode[namespace-uri()='urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100'][1]",
      "rule_severity": "FATAL",
      "rule_messages": [
        "[BR-CL-04]-Invoice currency code MUST be coded using ISO code list 4217 alpha-3"
      ]
    }
  ],
  "warnings": [],
  "is_valid": false
}

扩展配置

通过设置BUGSNAG_API_KEY环境变量启用Bugsnag错误报告：

yaml
e-invoice-validator:
  image: 'docker.xuanyuan.run/easybill/e-invoice-validator:latest'
  ports:
    - '8081:8080'
  environment:
      JAVA_TOOL_OPTIONS: -Xmx512m
      BUGSNAG_API_KEY: <你的API密钥>
  healthcheck:
    test: curl --fail http://localhost:8081/health || exit 0
    interval: 10s
    retries: 6

问题与贡献

欢迎提交Pull Request或Issue反馈问题或改进建议。

路线图

待更新