PHP
Instal·la factuarea/factuarea-php amb Composer, autentica't i crea la teva primera factura. PSR-4, basat en Guzzle, PHP 8.2+.
L'SDK oficial de PHP és factuarea/factuarea-php
a Packagist — PSR-4, basat en Guzzle. Codi font:
github.com/factuarea/factuarea-php.
Embolcalla l'API REST v1 amb reintents automàtics, idempotency keys,
auto-paginació per cursor, una jerarquia d'errors tipada i verificació de
webhooks — tot plegat descrit a la introducció a l'SDK.
Instal·lació
composer require factuarea/factuarea-phpRequereix PHP 8.2 o superior amb les extensions json i mbstring (totes
dues incloses a les builds estàndard de PHP).
Autenticació
Passa la teva API key. El prefix de la clau selecciona l'entorn — no hi ha
cap flag a part: una clau fact_test_… sempre s'executa contra el
sandbox aïllat, i una clau fact_live_… contra producció.
<?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() és el punt d'entrada recomanat: configura
l'autenticació Bearer i registra per tu el comportament automàtic d'
Idempotency-Key. Per a configuració avançada (client Guzzle personalitzat,
política de reintents personalitzada, base URL de staging) el builder generat
encara està disponible:
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();Només al servidor. La teva API key és un secret. No distribueixis mai l'SDK amb una clau live en un client públic — fes-la servir des del teu backend.
Inici ràpid
Crea un contacte amb rol de client i una factura, i descarrega’n el PDF amb els mètodes publicats de l’SDK que apareixen a continuació. Per a altres operacions, comprova l’SDK instal·lat o fes servir l’exemple HTTP de la referència de l’API.
La creació del contacte fa servir HTTP amb Guzzle, que el SDK PHP ja requereix. Així funciona sense assumir que la versió PHP instal·lada té mètodes de contactes generats. El SDK de factures conserva clientId: passa l’id del contacte amb rol customer actiu.
<?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 ?? '');Executa-ho tot primer amb una clau fact_test_ — els efectes del sandbox
(VeriFactu → AEAT, FACe, email, webhooks) estan desactivats. Quan el teu flux
funcioni d'extrem a extrem, canvia el prefix a fact_live_. Consulta
Mode de prova i sandbox.
Següents passos
El comportament en runtime — reintents, idempotència, auto-paginació per cursor, la jerarquia d'errors tipada i la verificació de webhooks — és comú a tots dos SDK i està documentat una sola vegada a la introducció a l'SDK:
Cobertura de les versions
La referència de setembre de 2026 és 0.2.0 per a tots dos SDK. Els specs de les seves branques principals contenen 413 entrades i encara els falten 39 endpoints REST. Cal actualitzar el paquet per disposar de nous mètodes generats. La referència de l’API ofereix exemples HTTP complets amb fetch de TypeScript, cURL de PHP i terminal per al contracte documentat; aquests exemples no pressuposen que existeixi cap mètode de l’SDK.