README

Official PHP SDK for Facturapi.

Language: English | Español

👁 Latest Version
👁 PHP Version
👁 Total Downloads
👁 License

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