README

Official PHP SDK for Facturapi.

Language: English | Español

Installation ⚡

composer require facturapi/facturapi-php

Without Composer (supported workaround):

require_once __DIR__ . '/path/to/facturapi-php/src/Facturapi.php';

Requirements:

• PHP >=8.2

Backward Compatibility With Older PHP Versions

Since version 4.0.0, the SDK requires PHP >= 8.2.

• If your project already runs on PHP 8.2+, no extra changes are needed.
• If your project runs on PHP 8.1 or lower, pin to version 3.7.0 (latest compatible release before PHP 8.2 requirement).

Quick Start 🚀

<?php

require_once __DIR__ . '/vendor/autoload.php';

use Facturapi\Facturapi;

$apiKey = getenv('FACTURAPI_KEY') ?: 'YOUR_API_KEY';
$facturapi = new Facturapi($apiKey);

$customer = $facturapi->Customers->create([
  'email' => 'walterwhite@gmail.com',
  'legal_name' => 'Walter White',
  'tax_id' => 'WIWA761018',
  'address' => [
    'zip' => '06800',
    'street' => 'Av. de los Rosales',
    'exterior' => '123',
    'neighborhood' => 'Tepito',
  ],
]);

Client Configuration ⚙️

Constructor signature:

new Facturapi(string $apiKey, ?array $config = null)

Supported config keys:

• apiVersion (string, default: v2)
• timeout (int|float, default: 360 seconds)
• httpClient (Psr\Http\Client\ClientInterface, advanced)

Example:

use Facturapi\Facturapi;

$facturapi = new Facturapi($apiKey, [
  'apiVersion' => 'v2',
  'timeout' => 420,
]);

Custom HTTP Client (Advanced)

The SDK works out of the box with its internal Guzzle-based client.

If you provide httpClient, pass any PSR-18 compatible client and configure its timeout values in that client:

use Facturapi\Facturapi;
use GuzzleHttp\Client;

$httpClient = new Client([
  'timeout' => 420,
]);

$facturapi = new Facturapi($apiKey, [
  'httpClient' => $httpClient,
]);

Common Usage 🧾

Create a Product

$product = $facturapi->Products->create([
  'product_key' => '4319150114',
  'description' => 'Apple iPhone 8',
  'price' => 345.60,
]);

Create an Invoice

$invoice = $facturapi->Invoices->create([
  'customer' => 'YOUR_CUSTOMER_ID',
  'items' => [[
    'quantity' => 1,
    'product' => 'YOUR_PRODUCT_ID',
  ]],
  'payment_form' => \Facturapi\PaymentForm::EFECTIVO,
  'folio_number' => '581',
  'series' => 'F',
]);

Download Files

$zipBytes = $facturapi->Invoices->downloadZip('INVOICE_ID');
$pdfBytes = $facturapi->Invoices->downloadPdf('INVOICE_ID');
$xmlBytes = $facturapi->Invoices->downloadXml('INVOICE_ID');

downloadPdf() returns raw PDF bytes (binary string), not base64.

file_put_contents('invoice.pdf', $pdfBytes);

Send by Email

$facturapi->Invoices->sendByEmail('INVOICE_ID');

Comercio Exterior Catalogs

$results = $facturapi->ComercioExteriorCatalogs->searchTariffFractions([
  'q' => '0101',
  'page' => 0,
  'limit' => 10,
]);

Organizations: Set Default Series

$result = $facturapi->Organizations->updateDefaultSeries(
  'ORGANIZATION_ID',
  [
    'type' => 'I',
    'series' => 'A',
  ]
);

Error Handling ⚠️

On non-2xx responses, the SDK throws Facturapi\Exceptions\FacturapiException.

The exception includes:

• getMessage(): API error message when present.
• getStatusCode(): HTTP status code.
• getErrorData(): decoded JSON error payload (full API shape).
• getRawBody(): raw response body string.

use Facturapi\Exceptions\FacturapiException;

try {
  $facturapi->Invoices->create($payload);
} catch (FacturapiException $e) {
  $status = $e->getStatusCode();
  $error = $e->getErrorData(); // Full API error shape when body is valid JSON.
  $firstDetail = $error['details'][0] ?? null; // e.g. ['path' => 'items.0.quantity', 'message' => '...', 'code' => '...']
}

Migration Notes (v4) 🔄

• Minimum PHP version is now >=8.2.
• Removed support for the positional apiVersion constructor argument.
• Composer projects: no loader changes needed; keep using vendor/autoload.php.
• Non-Composer projects can keep using the SDK by loading src/Facturapi.php directly.
• Snake_case method aliases are deprecated in v4 and will be removed in v5.
• Facturapi\\Exceptions\\Facturapi_Exception is deprecated in v4 and will be removed in v5.
• Use Facturapi\\Exceptions\\FacturapiException.

Documentation 📚

Full docs: https://docs.facturapi.io

Support 💬

• Issues: open a GitHub issue
• Email: contacto@facturapi.io