PHP

composer require factuarea/factuarea-php

<?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'));

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();

<?php

require 'vendor/autoload.php';

use Factuarea\Sdk\Custom\FactuareaClient;
use Factuarea\Sdk\Models\Components;
use Factuarea\Sdk\Models\Operations;
use Brick\DateTime\LocalDate;

$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));

// Company axis: every company call carries the company id (`data.scope[].id` of GET /v1/me).
$company = getenv('FACTUAREA_COMPANY_ID');

// 1. Create a customer contact.
$http = new \GuzzleHttp\Client();
$response = $http->post('https://api.factuarea.com/v1/companies/' . $company . '/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).
$created = $factuarea->invoices->publicApiV1InvoicesCreate(
    company: $company,
    body: 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',
            ),
        ],
    ),
);

// A new invoice comes in the 201 body; a 200 replays one that already exists.
$invoice = ($created->twoHundredAndOneApplicationJsonObject ?? $created->twoHundredApplicationJsonObject)->data;

// 3. Download the PDF. A 202 (still being generated) raises APIException:
//    see "Conditional requests, null fields and PDF statuses" below.
$pdf = $factuarea->invoices->publicApiV1InvoicesPdf(
    new Operations\PublicApiV1InvoicesPdfRequest(company: $company, invoice: $invoice->id),
);
file_put_contents('invoice.pdf', $pdf->bytes ?? '');

<?php

require 'vendor/autoload.php';

use Factuarea\Sdk\Custom\FactuareaClient;
use Factuarea\Sdk\Models\Components;
use Factuarea\Sdk\Models\Operations;

$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));

// L'id del compte és `data->account->id` de `publicApiV1AccountShow()` (GET /v1/me).
$account = $factuarea->account->publicApiV1AccountShow()->object->data->account->id;

// 1. Llista els NIF del compte.
$nifs = $factuarea->companies->publicApiV1CompaniesList(
    new Operations\PublicApiV1CompaniesListRequest(account: $account, limit: 50),
);
foreach ($nifs->companyList->data as $nif) {
    echo $nif->id, ' ', $nif->taxId, PHP_EOL;
}

// 2. Traspassa un NIF a un altre compte (traspàs de NIF).
$transfer = $factuarea->account->nifTransfers->publicApiV1AccountNifTransfersCreate(
    new Components\CreateNifTransferV1Request(
        companyId: $companyId,
        recipientAccountId: $recipientAccountId,
    ),
    account: $account,
    idempotencyKey: bin2hex(random_bytes(16)),
);
// El secret viatja només en aquesta resposta: lliura'l al compte receptor.
$secret = $transfer->object->data->secret;

// 3. Aplica una importació massiva de comptes gestionats (multipart/form-data).
$import = $factuarea->managedAccounts->imports->publicApiV1ManagedAccountsImportsCreate(
    new Components\ManagedAccountImportV1Request(
        accountsFile: new Components\AccountsFile(
            fileName: 'accounts.csv',
            content: file_get_contents('accounts.csv'),
        ),
        options: new Components\ManagedAccountImportV1RequestOptions(sendEmail: false),
    ),
    idempotencyKey: bin2hex(random_bytes(16)),
);

// 4. Crea un webhook de compte (exigeix una clau fact_live_).
$endpoint = $factuarea->account->webhooks->publicApiV1AccountWebhooksCreate(
    new Components\CreateAccountWebhookV1Request(
        url: 'https://example.com/webhooks/factuarea',
        enabledEvents: ['account.nif_added', 'invoice.paid'],
        accountRelationship: Components\CreateAccountWebhookV1RequestAccountRelationship::All,
    ),
    account: $account,
);
// El secret `whsec_…` només es retorna ara: guarda'l per verificar els lliuraments.
$webhookSecret = $endpoint->object->data->secret;

<?php

require 'vendor/autoload.php';

use Factuarea\Sdk\Custom\FactuareaClient;
use Factuarea\Sdk\Custom\Request\NoRetry;
use Factuarea\Sdk\Custom\Request\RequestOverrides;
use Factuarea\Sdk\Custom\Response\ResponseMeta;
use Factuarea\Sdk\Models\Errors\APIException;
use Factuarea\Sdk\Models\Operations\PublicApiV1InvoicesPdfRequest;

$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));
$company = getenv('FACTUAREA_COMPANY_ID'); // `data.scope[].id` of GET /v1/me

// 1. Download the invoice PDF, or get a 304 when the copy you hold is current.
try {
    $pdf = RequestOverrides::run(
        fn () => $factuarea->invoices->publicApiV1InvoicesPdf(
            new PublicApiV1InvoicesPdfRequest(company: $company, invoice: $invoiceId),
        ),
        headers: ['If-None-Match' => $cachedEtag],
    );
    if ($pdf->statusCode === 200) {
        file_put_contents('invoice.pdf', $pdf->bytes ?? '');
        $cachedEtag = ResponseMeta::fromResponse($pdf->rawResponse)->etag;
    }
    // 304: no bytes, keep your copy.
} catch (APIException $e) {
    $meta = ResponseMeta::fromException($e);
    if ($meta->statusCode !== 202) {
        throw $e;
    }
    // 202: the PDF is still being generated. Ask again after $meta->retryAfter seconds.
}

// 2. Submit to FACe once: no automatic retry on 429 or 5xx.
$factuarea->invoices->faceSubmissions->publicApiV1InvoicesFaceSubmissionsSubmit(
    company: $company,
    invoice: $invoiceId,
    idempotencyKey: $submissionKey, // reuse it if you ever repeat this submission
    options: NoRetry::options(),
);

<?php

require 'vendor/autoload.php';

use Factuarea\Sdk\Custom\FactuareaClient;
use Factuarea\Sdk\Custom\Request\RawRequest;
use Factuarea\Sdk\Custom\Response\ResponseMeta;

$factuarea = FactuareaClient::create(getenv('FACTUAREA_API_KEY'));
$company = getenv('FACTUAREA_COMPANY_ID');

// 1. List the library, one page per call. A list returns `items` and `meta`.
$list = ResponseMeta::fromResponse(RawRequest::send(
    $factuarea,
    'GET',
    '/companies/{company}/pdf-templates',
    ['query' => ['page' => 1, 'per_page' => 20]],
    ['company' => $company],
));
foreach ($list->json()['items'] ?? [] as $template) {
    echo $template['id'], ' ', $template['name'], PHP_EOL;
}

// 2. Read one template and keep its ETag.
$read = ResponseMeta::fromResponse(RawRequest::send(
    $factuarea,
    'GET',
    '/companies/{company}/pdf-templates/{template}',
    [],
    ['company' => $company, 'template' => $templateId],
));

// 3. Rename it with the literal ETag as If-Match. `null` clears the description.
$update = ResponseMeta::fromResponse(RawRequest::send(
    $factuarea,
    'PATCH',
    '/companies/{company}/pdf-templates/{template}',
    [
        'headers' => ['If-Match' => $read->etag],
        'json' => ['name' => 'Factura corporativa', 'description' => null],
    ],
    ['company' => $company, 'template' => $templateId],
));
if ($update->statusCode !== 200) {
    // 412: the ETag is stale. 428: no precondition. Read it again and retry.
    throw new RuntimeException('HTTP '.$update->statusCode.': '.$update->body);
}

// 4. Download an exact PDF artifact: it answers 503 with Retry-After until it is ready.
for ($attempt = 0; $attempt < 12; $attempt++) {
    $response = RawRequest::send(
        $factuarea,
        'GET',
        '/companies/{company}/pdf-artifacts/{artifact}/download',
        ['headers' => ['Accept' => 'application/pdf']],
        ['company' => $company, 'artifact' => $artifactId],
    );
    if ($response->getStatusCode() === 200) {
        file_put_contents('invoice.pdf', (string) $response->getBody());
        break;
    }
    if ($response->getStatusCode() !== 503) {
        throw new RuntimeException('HTTP '.$response->getStatusCode());
    }
    sleep(max(1, ResponseMeta::fromResponse($response)->retryAfter ?? 1));
}