包简介

An SDK to easily work with the Factuapi API

README 文档

README

A PHP SDK for interacting with the Factuapi API. This SDK allows you to easily create, manage, and process invoices through the Factuapi platform, including support for Spanish invoicing requirements like equivalence surcharge and VIES VAT numbers.

Installation

composer require factuapi/factuapi-php-sdk

Usage

To authenticate, you'll need an API token. You can create one in the API tokens screen at Factuapi.

use Factuapi\PhpSdk\Factuapi;

$factuapi = new Factuapi('your-api-token');

Create invoice

You can create invoices using the invoices()->create() method. The method requires an Invoice object with all the necessary information.

use Factuapi\PhpSdk\Dto\Invoices\Invoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceId;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceItem;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceTotals;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceType;
use Factuapi\PhpSdk\Dto\Invoices\TaxType;
use Factuapi\PhpSdk\Dto\Invoices\RegimeKeyIVA;
use Factuapi\PhpSdk\Dto\Issuer;
use Factuapi\PhpSdk\Dto\Recipients\SpanishRecipient;

$factuapi
  ->invoices()
  ->create(
    invoice: new Invoice(
      invoiceId: new InvoiceId(
        seriesCode: "2025",
        number: "101",
      ),
      issueDate: new DateTime("2025-11-14"),
      invoiceType: InvoiceType::Invoice,
      issuer: new Issuer(
        taxNumber: "B12345678",
        name: "Example Company SL",
        address: "C/ Example Street 123",
        postCode: "08001",
        city: "Barcelona",
        province: "Barcelona"
      ),
      recipient: new SpanishRecipient(
        taxNumber: "B87654321",
        name: "Client Company SL",
        address: "Av. Client 456",
        postCode: "08002",
        city: "Barcelona",
        province: "Barcelona"
      ),
      items: [
        new InvoiceItem(
          description: "Professional services",
          basePrice: 100,
          taxType: TaxType::IVA,
          regimeKey: RegimeKeyIVA::General,
          taxRate: 21,
          taxPrice: 21,
          amount: 121
        )
      ],
      totals: new InvoiceTotals(basePrice: 100, taxPrice: 21, amount: 121),
      itemDescription: "Invoice for services"
    ),
    process: ["verifactu"]
  );

Equivalence surcharge

For invoices that require equivalence surcharge (recargo de equivalencia), you can specify the equivalenceSurchargeType and equivalenceSurchargePrice in the invoice items:

use Factuapi\PhpSdk\Dto\Invoices\Invoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceId;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceType;
use Factuapi\PhpSdk\Dto\Invoices\TaxType;
use Factuapi\PhpSdk\Dto\Invoices\RegimeKeyIVA;

$factuapi
  ->invoices()
  ->create(
    invoice: new Invoice(
      invoiceId: new InvoiceId(
        seriesCode: "2025",
        number: "110",
      )
      issueDate: new DateTime("2025-11-14"),
      invoiceType: InvoiceType::Invoice,
      issuer: new Issuer(
        taxNumber: "B12345678",
        name: "Example Company SL",
        address: "C/ Example Street 123",
        postCode: "08001",
        city: "Barcelona",
        province: "Barcelona"
      ),
      recipient: new SpanishRecipient(
        taxNumber: "B87654321",
        name: "Client Company SL",
        address: "Av. Client 456",
        postCode: "08002",
        city: "Barcelona",
        province: "Barcelona"
      ),
      items: [
        new InvoiceItem(
          description: "Office supplies",
          basePrice: 150.00,
          taxType: TaxType::IVA,
          regimeKey: RegimeKeyIVA::General,
          taxRate: 21,
          taxPrice: 31.50,
          // Equivalence surcharge fields
          equivalenceSurchargeType: 5.2,
          equivalenceSurchargePrice: 7.80,
          amount: 189.30
        )
      ],
      totals: new InvoiceTotals(
        basePrice: 150.00,
        taxPrice: 39.30, // Regular tax + equivalence surcharge
        amount: 189.30
      ),
      itemDescription: "Invoice with equivalence surcharge"
    ),
    process: ["verifactu"]
  );

IVA exempt invoice

For invoices that are exempt from IVA (Spanish VAT), you need to specify an exemption reason using the ExemptionReason enum. Set the taxRate to 0, include the appropriate exemptionReason value, and ensure taxPrice is also 0. The available exemption reasons correspond to specific articles in Spanish tax law (Article 20, 21, 22, 23/24, 25, or Other).

use Factuapi\PhpSdk\Dto\Invoices\Invoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceId;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceLine;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceType;
use Factuapi\PhpSdk\Dto\Invoices\ExemptionReason;
use Factuapi\PhpSdk\Dto\Invoices\TaxType;
use Factuapi\PhpSdk\Dto\Invoices\RegimeKeyIVA;

$factuapi
  ->invoices()
  ->create(
    invoice: new Invoice(
      invoiceId: new InvoiceId(
        seriesCode: "2025",
        number: "110",
      )
      issueDate: new DateTime("2025-11-14"),
      invoiceType: InvoiceType::Invoice,
      issuer: new Issuer(
        taxNumber: "B12345678",
        name: "Example Company SL",
        address: "C/ Example Street 123",
        postCode: "08001",
        city: "Barcelona",
        province: "Barcelona"
      ),
      recipient: new SpanishRecipient(
        taxNumber: "B87654321",
        name: "Client Company SL",
        address: "Av. Client 456",
        postCode: "08002",
        city: "Barcelona",
        province: "Barcelona"
      ),
      items: [
        new InvoiceItem(
          description: "Item description",
          basePrice: 100,
          taxType: TaxType::IVA,
          regimeKey: RegimeKeyIVA::General,
          taxRate: 0,
          exemptionReason: ExemptionReason::Article20,
          taxPrice: 0,
          amount: 100
        )
      ],
      totals: new InvoiceTotals(
        basePrice: 100,
        taxPrice: 0,
        amount: 100
      ),
      itemDescription: "Invoice description"
    ),
    process: ["verifactu"]
  );

VIES VAT number

For intra-community invoices with VIES VAT numbers, use the OtherRecipient class with the appropriate country code and ID type:

use Factuapi\PhpSdk\Dto\Recipients\OtherRecipient;
use Factuapi\PhpSdk\Dto\Recipients\OtherIdType;
use Factuapi\PhpSdk\Dto\Invoices\Invoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceId;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceType;
use Factuapi\PhpSdk\Dto\Invoices\TaxType;
use Factuapi\PhpSdk\Dto\Invoices\RegimeKeyIVA;

$factuapi
  ->invoices()
  ->create(
    invoice: new Invoice(
      invoiceId: new InvoiceId(
        seriesCode: "2025",
        number: "116",
      ),
      issueDate: new DateTime("2025-11-21"),
      invoiceType: InvoiceType::Invoice,
      issuer: new Issuer(
        taxNumber: "B12345678",
        name: "Example Company SL",
        address: "C/ Example Street 123",
        postCode: "08001",
        city: "Barcelona",
        province: "Barcelona"
      ),
      recipient: new OtherRecipient(
        countryCode: "DE",
        idType: OtherIdType::NifIva,
        idNumber: "DE123456789",
        name: "German Client GmbH",
        address: "Hauptstrasse 1",
        postCode: "10115",
        city: "Berlin",
        province: "Berlin"
      ),
      items: [
        new InvoiceItem(
          description: "Consulting services",
          basePrice: 100,
          taxType: TaxType::IVA,
          regimeKey: RegimeKeyIVA::General,
          taxRate: 21,
          taxPrice: 21,
          amount: 121
        )
      ],
      totals: new InvoiceTotals(basePrice: 100, taxPrice: 21, amount: 121),
      itemDescription: "International invoice"
    ),
    process: ["verifactu"]
  );

Create credit note

To create a credit note (rectificativa), use the invoices()->create() method with invoiceType: "CreditNote" and include the creditNote and relatedInvoices properties:

use Factuapi\PhpSdk\Dto\CreditNotes\CreditNote;
use Factuapi\PhpSdk\Dto\Invoices\Invoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceId;
use Factuapi\PhpSdk\Dto\Invoices\RelatedInvoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceType;
use Factuapi\PhpSdk\Dto\Invoices\TaxType;
use Factuapi\PhpSdk\Dto\Invoices\RegimeKeyIVA;
use \Factuapi\PhpSdk\Dto\CreditNotes\CreditNoteType;
use \Factuapi\PhpSdk\Dto\CreditNotes\CreditNoteCategory;

$factuapi
  ->invoices()
  ->create(
    invoice: new Invoice(
      invoiceId: new InvoiceId(
        seriesCode: "REC2025",
        number: "1",      
      ),
      issueDate: new DateTime("2025-11-14"),
      invoiceType: InvoiceType::CreditNote,
      issuer: new Issuer(
        taxNumber: "B12345678",
        name: "Example Company SL",
        address: "C/ Example Street 123",
        postCode: "08001",
        city: "Barcelona",
        province: "Barcelona"
      ),
      recipient: new SpanishRecipient(
        taxNumber: "B87654321",
        name: "Client Company SL",
        address: "Av. Client 456",
        postCode: "08002",
        city: "Barcelona",
        province: "Barcelona"
      ),
      items: [
        new InvoiceItem(
          description: "Correction for invoice 2025-101",
          basePrice: -10,
          taxType: TaxType::IVA,
          regimeKey: RegimeKeyIVA::General,
          taxRate: 21,
          taxPrice: -2.1,
          amount: -12.1
        )
      ],
      totals: new InvoiceTotals(basePrice: -10, taxPrice: -2.1, amount: -12.1),
      itemDescription: "Credit note",
      creditNote: new CreditNote(
        type: CreditNoteType::ByDifferences,
        category: CreditNoteCategory::AdjustmentForDiscountsOrReturns,
        basePrice: 100,
        taxPrice: 21
      ),
      relatedInvoices: [
        new RelatedInvoice(
          invoiceId: new InvoiceId(
            seriesCode: "2025",
            number: "101",            
          ),
          issueDate: new DateTime("2025-11-14"),
          issuerTaxNumber: "B12345678"
        )
      ]
    ),
    process: ["verifactu"]
  );

Correct invoice

To correct an invoice without fiscal impact (e.g., changing recipient details but not totals), use the invoices()->correct() method:

use Factuapi\PhpSdk\Dto\Invoices\InvoiceType;
use Factuapi\PhpSdk\Dto\Invoices\Invoice;
use Factuapi\PhpSdk\Dto\Invoices\InvoiceId;
use Factuapi\PhpSdk\Dto\Invoices\TaxType;
use Factuapi\PhpSdk\Dto\Invoices\RegimeKeyIVA;

$factuapi
  ->invoices()
  ->correct(
    previousInvoiceId: new InvoiceId(
      seriesCode: "2025",
      number: "105",
    ),
    invoice: new Invoice(
      invoiceId: new InvoiceId(
        seriesCode: "2025",
        number: "105",
      ),
      issueDate: new DateTime("2025-11-14"),
      invoiceType: InvoiceType::Invoice,
      issuer: new Issuer(
        taxNumber: "B12345678",
        name: "Example Company SL",
        address: "C/ Example Street 123",
        postCode: "08001",
        city: "Barcelona",
        province: "Barcelona"
      ),
      recipient: new SpanishRecipient(
        taxNumber: "B98765432",
        name: "Updated Client SL",
        address: "C/ New Address 789",
        postCode: "08003",
        city: "Barcelona",
        province: "Barcelona"
      ),
      items: [
        new InvoiceItem(
          description: "Professional services",
          basePrice: 100,
          taxType: TaxType::IVA,
          regimeKey: RegimeKeyIVA::General,
          taxRate: 21,
          taxPrice: 21,
          amount: 121
        )
      ],
      totals: new InvoiceTotals(basePrice: 100, taxPrice: 21, amount: 121),
      itemDescription: "Invoice"
    ),
    process: ["verifactu"]
  );

For corrections with fiscal impact (changing amounts), you should create a credit note (rectificativa) instead.

Cancel invoice

Only use invoice cancellation when the invoice was generated by error (e.g., during testing or for a service that was not ultimately contracted). Never use cancellation to modify an invoice - in those cases, you should create a credit note (rectificativa) or correction instead.

To cancel an invoice, use the invoices()->cancel() method with the invoice number:

$factuapi
    ->invoices()
    ->cancel(
        invoiceId: new InvoiceId(
          seriesCode: "2025",
          number: "103",
        ),
        process: ["verifactu"]
    );

This will mark the invoice as cancelled in the system.

Verifactu Integration

Verifactu is a service that facilitates compliance with Spanish tax authority (AEAT) anti-fraud requirements. By integrating with Verifactu, your invoices are automatically verified and secured with cryptographic hashes, ensuring regulatory compliance with anti-fraud measures and providing official verification.

Enabling Verifactu Processing

To submit an invoice to the Verifactu service, add "verifactu" to the process array parameter when creating, correcting, or canceling an invoice:

$factuapi
  ->invoices()
  ->create(
    invoice: new Invoice(),
    process: ["verifactu"]
  );

Understanding the Response

When an invoice is processed through Verifactu, the response will include verification data with the following components:

[
    "processes" => [
        "type" => "verifactu",
        "status" => "pending",
        "info" => [
            "hash" => "8C6C8FB8DA[...]",                      // Unique invoice hash for verification
            "previous_invoice_hash" => "702A8AD6A[...]",      // Hash of the previous invoice in the series
            "generated_at" => "2025-11-21T16:23:53.301000Z",  // Timestamp of verification request
            "qr_url" => "https://[...]",                      // Public verification URL
            "qr_base64" => "iVBORw[...]",                     // Base64-encoded QR code image to include on invoices
        ],
        "messages" => [],                                      // Any messages from the Verifactu response
    ]
]

Processing Status

The initial status will always be "pending" as Verifactu processes submissions in batches. Your invoice will typically be processed within one minute of submission. You can check the final status by retrieving the invoice details later.

QR Code Implementation

The response includes two options for implementing the required verification QR code on your invoices:

qr_base64: A ready-to-use base64-encoded QR code image that can be directly embedded in digital or printed invoices
qr_url: The verification URL that can be used to generate your own QR code if you prefer to use a custom QR code generator

Including this QR code on your invoices is mandatory for compliance in Spain.

License

The MIT License (MIT). Please see License File for more information.

factuapi/factuapi-php-sdk 适用场景与选型建议

factuapi/factuapi-php-sdk 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 319 次下载、GitHub Stars 达 1，最近一次更新时间为 2025 年 11 月 25 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「api」「facturae」「verifactu」「factuapi」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 factuapi/factuapi-php-sdk 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 factuapi/factuapi-php-sdk 我们能提供哪些服务？

定制开发 / 二次开发

基于 factuapi/factuapi-php-sdk 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 factuapi/factuapi-php-sdk 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

josemmo/facturae-php 285

Librería para la generación, firma y envío de facturas electrónicas

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

aichadigital/lara-verifactu 0

Laravel package for AEAT Verifactu compliance with agnostic architecture

squareetlabs/laravel-verifactu 22

Paquete Laravel para gestión y registro de facturación electrónica VeriFactu. Compatible con Laravel 10 a 12.x

fidelo-software/verifactu 0

Verifactu API Client

nerio93/facturae-php 0