Download the PHP package factuarea/factuarea-php without Composer

Factuarea PHP SDK

Official PHP SDK for the Factuarea public API — invoicing, quotes, proformas, delivery notes, products, clients, suppliers, taxes, VeriFactu and webhooks for Spanish businesses.

Type-safe, PSR-4, built on Guzzle, with automatic retries, automatic idempotency, cursor auto-pagination, typed errors and a webhook signature verifier.

Status: pre-GA (0.x). The method surface follows the stable SDK method naming contract and is protected by SemVer, but 0.x signals the API may still evolve before GA.

Installation

Not yet on Packagist — coming soon. Until the package is published you can install it directly from GitHub.

Once published:

Until then, install from the repository by adding it to your composer.json:

then run composer update.

Requirements: PHP 8.2 or higher, with the json and mbstring extensions (both bundled with standard PHP builds).

Quickstart

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:

Server-side only. A secret API key must never ship in a browser or mobile app. Load it from an environment variable or secret manager.

Sandbox (test mode)

Every API key belongs to one of two environments, decided by its prefix — there is no environment flag in the SDK:

A fact_test_ key operates on an isolated sandbox company with the same functional surface as production. Always integrate against a fact_test_ key first, then switch the prefix to fact_live_ to go live.

Runtime features

Automatic retries

Transient failures (429 and 5xx) are retried with exponential backoff, honouring the server's Retry-After header. Client errors (4xx other than 429) are never retried. Retries reuse the same request — including its Idempotency-Key — so a retried mutation is idempotent end to end.

Automatic idempotency

Every mutating request (POST, PUT, PATCH, DELETE) gets a generated Idempotency-Key (UUID v4) unless you supply one explicitly:

Replaying a request with the same key returns the original result and the response carries Idempotent-Replayed: true.

Cursor auto-pagination

List endpoints return the cursor envelope { data, has_more, next_cursor }. The PageIterator helper streams every item across all pages without manual cursor handling:

Typed errors

Documented API errors (401, 403, 409, 422, 429, 5xx) are thrown as a typed ErrorThrowable exposing the full error envelope — including the request_id you can quote to support. The API key is never included in any exception message.

Webhook signature verification

Factuarea signs every webhook delivery with HMAC-SHA256 in the Factuarea-Signature header (t=<unix>,v1=<hex>). Verify deliveries with a constant-time check and replay protection:

The verifier accepts deliveries during a secret-rotation grace window (the header may carry both the new and previous v1 signatures) and rejects payloads whose timestamp is outside the tolerance (default 5 minutes, configurable).

API reference

The full, generated reference for all resources and operations lives in docs/sdks/. Method names follow the deterministic operationId → method mapping (e.g. public-api.v1.invoices.mark_paid → $factuarea->invoices->publicApiV1InvoicesMarkPaid(...)).

Versioning

The SDK pins the Factuarea-Version it was generated against (currently 2026-06-04) and sends it on every request, so the API behaves consistently until you upgrade. SemVer applies to the SDK's public surface: new operations are a minor bump, renames/removals or a behaviour-changing Factuarea-Version bump are breaking, fixes are a patch. The SDK stays on 0.x until the API's GA, which ships 1.0.0 — so while it is pre-GA a breaking change lands in a minor, and the changelog names the replacement of every operation withdrawn.

See docs/VERSIONING.md for the full Factuarea-Version ↔ SDK-version mapping and CHANGELOG.md for release history.

The pinned spec is kept in sync with the published one automatically — see docs/SPEC_SYNC.md. The Spec sync badge above is when that check last ran, not when the repo was last committed to: a check that finds nothing to sync leaves no commit. Click it for the date of the latest run.

Support

Full runtime-support matrix and the deprecation / breaking-change policy live in SUPPORT.md.

Development

This SDK is generated with Speakeasy from the pinned OpenAPI document in spec/openapi.json. Generated code lives in src/ (managed by Speakeasy); hand-written runtime helpers live in src/Custom/ and are never overwritten by regeneration. See docs/REGENERATION.md for how to regenerate (and the documented fallback to openapi-generator).

License

MIT © Factuarea. Contact: [email protected]

Summary

Factuarea Public API: Public REST API for invoicing in Spain — manage invoices, quotes, proformas, delivery notes, products, clients and webhooks.

Authentication

The API authenticates with a secret API key, sent on every request as:

or, alternatively, in the X-API-Key header. The key is issued from the Factuarea portal and must NEVER be exposed in public clients (browser, mobile apps).

Environments: live and test

Each API key belongs to one of two environments, unambiguously identifiable by its prefix:

The prefix is the source of truth for the environment: a fact_test_ key always operates in test mode and a fact_live_ key always in live. There is no request parameter that changes the environment — it is determined by the key.

Data isolation (sandbox)

fact_test_ keys operate on a dedicated sandbox company (a technical "twin company" of the account holder, automatically provisioned the first time test mode is used, which inherits the plan of your real company for faithful feature-gating). Thanks to per-company data isolation:

• Resources created with a fact_test_ key are not visible from a fact_live_ key, and vice versa.
• Test fiscal numbering uses the sandbox's own series and never consumes or alters the sequential numbering of your production series.

The functional surface is identical in both environments: the same endpoints and operations are available in test as in live.

External effects neutralized in test

When you operate with a fact_test_ key (sandbox environment), outbound effects are disabled so you can test your integration without real consequences:

• VeriFactu: the Alta record is created locally, but not transmitted to AEAT.
• Email: document emails are not delivered to real recipients.
• Webhooks: events are not delivered to your external HTTP endpoints.

In live, all these effects fire normally.

Recommendation: always integrate and test first with a fact_test_ key. Once your flow works, switch to the fact_live_ prefix to operate in production.

Table of Contents

• Factuarea PHP SDK
  • Installation
  • Quickstart
  • Sandbox (test mode)
  • Runtime features
  • API reference
  • Versioning
  • Support
  • Development
  • License
  • Authentication
  • Environments: live and test
  • SDK Installation
  • SDK Example Usage
  • Authentication
  • Available Resources and Operations
  • Pagination
  • Retries
  • Error Handling
  • Server Selection

SDK Installation

[!TIP] To finish publishing your SDK you must run your first generation action.

The SDK relies on Composer to manage its dependencies.

To install the SDK first add the below to your composer.json file:

Then run the following command:

SDK Example Usage

Example

Authentication

Per-Client Security Schemes

This SDK supports the following security schemes globally:

You can set the security parameters through the setSecurity function on the SDKBuilder when initializing the SDK. The selected scheme will be used by default to authenticate with the API for all operations that support it. For example:

Available Resources and Operations

Pagination

Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned object will be a Generator instead of an individual response.

Working with generators is as simple as iterating over the responses in a foreach loop, and you can see an example below:

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide an Options object built with a RetryConfig object to the call:

If you'd like to override the default retry strategy for all operations that support retries, you can pass a RetryConfig object to the SDKBuilder->setRetryConfig function when initializing the SDK:

Error Handling

Handling errors in this SDK should largely match your expectations. All operations return a response object or throw an exception.

By default an API error will raise a Errors\APIException exception, which has the following properties:

When custom error responses are specified for an operation, the SDK may also throw their associated exception. You can refer to respective Errors tables in SDK docs for more details on possible exception types for each operation. For example, the publicApiV1ProformasAccept method throws the following exceptions:

Example

Server Selection

Override Server URL Per-Client

The default server can be overridden globally using the setServerUrl(string $serverUrl) builder method when initializing the SDK client instance. For example: