TypeScript
Instala @factuarea/sdk para Node.js, autentícate y crea tu primera factura. ESM + CommonJS dual, declaraciones de tipos completas, Node 20+.
El SDK oficial de TypeScript es @factuarea/sdk
en npm — ESM + CommonJS dual con declaraciones de tipos completas. Código fuente:
github.com/factuarea/factuarea-node.
Envuelve la API REST v1 con reintentos automáticos, idempotency keys,
auto-paginación por cursor, una jerarquía de errores tipada y verificación de
webhooks — todo cubierto en la introducción al SDK.
Instalación
npm install @factuarea/sdkRequiere Node 20 o superior. El SDK está construido sobre el estándar Web
fetch, así que también funciona en Deno, Bun y Cloudflare Workers.
Autenticación
Pasa tu API key. El prefijo de la clave selecciona el entorno — no hay un
flag aparte: una clave fact_test_… siempre se ejecuta contra el
sandbox aislado, y una clave fact_live_… contra producción.
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ón 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
});Solo en el servidor. Tu API key es un secreto. Nunca distribuyas el SDK con una clave live a un navegador, app móvil o cualquier cliente público — úsala desde tu backend.
Inicio rápido
Crea un contacto con rol de cliente y una factura, y descarga su PDF con los métodos publicados del SDK que aparecen a continuación. Para otras operaciones, comprueba tu SDK instalado o usa el ejemplo HTTP de la referencia de la 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()),
);Ejecuta todo primero con una clave fact_test_ — los efectos del sandbox
(VeriFactu → AEAT, FACe, email, webhooks) están desactivados. Cuando tu flujo
funcione de extremo a extremo, cambia el prefijo a fact_live_. Consulta
Modo de prueba y sandbox.
Próximos pasos
El comportamiento en tiempo de ejecución — reintentos, idempotencia, auto-paginación por cursor, la jerarquía de errores tipada y la verificación de webhooks — es común a ambos SDK y está documentado una sola vez en la introducción al SDK:
Cobertura de las versiones
La referencia de septiembre de 2026 es 0.2.0 para ambos SDK. Los specs de sus ramas principales contienen 413 entradas y todavía les faltan 39 endpoints REST. Es necesario actualizar el paquete para disponer de nuevos métodos generados. La referencia de la API ofrece ejemplos HTTP completos con fetch de TypeScript, cURL de PHP y terminal para el contrato documentado; estos ejemplos no presuponen que exista un método del SDK.