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 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.
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 customer contact.
const { data: contact } = await factuarea.contacts.create({
name: "Cliente Demo SL",
kind: "company",
roles: ["customer"],
tax_id: "B12345674",
});
// 2. Create an invoice (the API computes the totals).
const { data: invoice } = await factuarea.invoices.create({
client_id: contact.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:
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.