TypeScript
Instal·la @factuarea/sdk per a Node.js, autentica't i crea la teva primera factura. ESM + CommonJS dual, declaracions de tipus completes, Node 20+.
L'SDK oficial de TypeScript és @factuarea/sdk
a npm — ESM + CommonJS dual amb declaracions de tipus completes. Codi font:
github.com/factuarea/factuarea-node.
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 cobert a la introducció a l'SDK.
Instal·lació
npm install @factuarea/sdkRequereix Node 20 o superior. L'SDK està construït sobre l'estàndard Web
fetch, així que també funciona a Deno, Bun i Cloudflare Workers.
Autenticació
Passa la teva API key. El prefix de la clau selecciona l'entorn — no hi ha
un flag a part: una clau fact_test_… sempre s'executa contra el
sandbox aïllat, i una clau fact_live_… contra producció.
import { Factuarea } from "@factuarea/sdk";
const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });
factuarea.environment; // "test" or "live", derived from the key prefixConfiguració opcional:
new Factuarea({
apiKey: "fact_live_…", // required
baseUrl: "https://api.factuarea.com/v1", // override for staging
timeout: 60_000, // per-request ms (default 60s)
maxRetries: 2, // attempts after the first try
factuareaVersion: "2026-06-04", // pinned API version header
defaultHeaders: {}, // extra headers on every request
});Només al servidor. La teva API key és un secret. No distribueixis mai l'SDK amb una clau live a un navegador, app mòbil o qualsevol client públic — fes-la servir des del teu backend.
Inici ràpid
Crea un client i una factura, després descarrega'n el PDF. Cada operació és
accessible com a <resource>.<method>; els snippets per endpoint de la
referència de l'API mostren la crida exacta per a cada operació.
import { Factuarea } from "@factuarea/sdk";
const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });
// Responses are the API's `{ data: … }` envelope — read the resource off `.data`.
// 1. Create a client.
const { data: client } = await factuarea.clients.create({
name: "Cliente Demo SL",
tax_id: "B98765432",
});
// 2. Create an invoice (the API computes the totals).
const { data: invoice } = await factuarea.invoices.create({
client_id: client.id,
series_id: "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e",
issued_on: "2026-06-05",
due_on: "2026-07-05",
lines: [
{
description: "Consultoría — junio 2026",
quantity: 10,
unit_price: 100,
tax_rate_id: "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f",
},
],
});
// 3. Download the PDF (a BinaryResponse, not JSON).
const pdf = await factuarea.invoices.pdf(invoice.id);
await import("node:fs/promises").then((fs) =>
fs.writeFile("invoice.pdf", pdf.toBuffer()),
);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.
Pròxims passos
El comportament en temps d'execució — 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:
Visió general
SDKs oficials de TypeScript i PHP per a l'API de Factuarea — instal·la @factuarea/sdk o factuarea/factuarea-php i obtén reintents, idempotència, paginació per cursor, errors tipats i verificació de webhooks de sèrie.
PHP
Instal·la factuarea/factuarea-php amb Composer, autentica't i crea la teva primera factura. PSR-4, basat en Guzzle, PHP 8.2+.