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 cliente y una factura, luego descarga su PDF. Cada operación es
accesible como <resource>.<method>; los snippets por endpoint de la
referencia de la API muestran la llamada exacta para cada operación.
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()),
);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:
Visión general
SDKs oficiales de TypeScript y PHP para la API de Factuarea — instala @factuarea/sdk o factuarea/factuarea-php y obtén reintentos, idempotencia, paginación por cursor, errores tipados y verificación de webhooks de serie.
PHP
Instala factuarea/factuarea-php con Composer, autentícate y crea tu primera factura. PSR-4, basado en Guzzle, PHP 8.2+.