PHP
Install factuarea/factuarea-php with Composer, authenticate, and create your first invoice. PSR-4, Guzzle-based, PHP 8.2+.
The official PHP SDK is factuarea/factuarea-php
on Packagist — PSR-4, Guzzle-based. Source:
github.com/factuarea/factuarea-php.
It wraps the v1 REST API with automatic retries, idempotency keys, cursor
auto-pagination, a typed error hierarchy and webhook verification — covered in
the SDK overview.
Install
composer require factuarea/factuarea-phpRequires PHP 8.2 or newer with the json and mbstring extensions (both
bundled with standard PHP builds).
Authenticate
Pass your API key. The key prefix selects the environment — there is no
separate flag: a fact_test_… key always runs against the isolated
sandbox, a fact_live_… key against production.
<?php
require 'vendor/autoload.php';
use Factuarea\Sdk\Custom\FactuareaClient;
// The key prefix selects the environment:
// fact_test_… → sandbox fact_live_… → production
$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));FactuareaClient::create() is the recommended entry point: it wires Bearer
authentication and registers the automatic Idempotency-Key behaviour for you.
For advanced configuration (custom Guzzle client, custom retry policy, staging
base URL) the generated builder is still available:
use Factuarea\Sdk\Factuarea;
use Factuarea\Sdk\Models\Components\Security;
$factuarea = Factuarea::builder()
->setSecurity(new Security(bearerAuth: getenv('FACTUAREA_API_KEY')))
->setServerURL('https://api.factuarea.com/v1')
->build();Server-side only. Your API key is a secret. Never ship the SDK with a live key to a public client — use it from your backend.
Quickstart
Create a customer contact and an invoice, then download its PDF using the released SDK methods below. For other operations, check your installed SDK or use the HTTP snippet in the API Reference.
The contact creation below uses HTTP with Guzzle, already required by the PHP SDK. It works without assuming that your installed PHP release has generated contact methods. The invoice SDK keeps clientId; pass the canonical contact id with an active customer role.
<?php
require 'vendor/autoload.php';
use Factuarea\Sdk\Custom\FactuareaClient;
use Factuarea\Sdk\Models\Components;
use Brick\DateTime\LocalDate;
$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));
// 1. Create a customer contact.
$http = new \GuzzleHttp\Client();
$response = $http->post('https://api.factuarea.com/v1/contacts', [
'headers' => [
'Authorization' => 'Bearer ' . getenv('FACTUAREA_API_KEY'),
'Idempotency-Key' => bin2hex(random_bytes(16)),
],
'json' => [
'name' => 'Cliente Demo SL',
'kind' => 'company',
'roles' => ['customer'],
'tax_id' => 'B12345674',
],
]);
$contact = json_decode((string) $response->getBody(), true, 512, JSON_THROW_ON_ERROR)['data'];
// 2. Create an invoice (the API computes the totals).
$invoice = $factuarea->invoices->publicApiV1InvoicesCreate(
new Components\CreateInvoiceRequest(
clientId: $contact['id'],
seriesId: '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e',
issuedOn: LocalDate::parse('2026-06-05'),
dueOn: LocalDate::parse('2026-07-05'),
lines: [
new Components\CreateInvoiceRequestLine(
description: 'Consultoría — junio 2026',
quantity: 10,
unitPrice: 100,
taxRateId: '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f',
),
],
),
);
// 3. Download the PDF.
$pdf = $factuarea->invoices->publicApiV1InvoicesPdf($invoice->object->data->id);
file_put_contents('invoice.pdf', $pdf->bytes ?? '');Run everything with a fact_test_ key first — sandbox effects (VeriFactu →
AEAT, FACe, email, webhooks) are switched off. When your flow works end-to-end, swap
the prefix to fact_live_. See Test mode & sandbox.
Next steps
The runtime behaviour — retries, idempotency, cursor auto-pagination, the typed error hierarchy and webhook verification — is shared across both SDKs and documented once in the SDK overview:
Release coverage
The September 2026 baseline is 0.2.0 for both SDKs. Their main-branch specs contain 413 entries, with 39 REST endpoints still absent. A package upgrade is needed before newly generated SDK methods become available. The API Reference provides complete TypeScript fetch, PHP cURL and shell HTTP examples for the documented contract; these examples do not assume an SDK method exists.