TypeScript

Install @factuarea/sdk for Node.js, authenticate, and create your first invoice. Dual ESM + CommonJS, full type declarations, Node 20+.

The official TypeScript SDK is @factuarea/sdk on npm — dual ESM + CommonJS with full type declarations. Source: github.com/factuarea/factuarea-node. It wraps the v1 REST API with automatic retries, idempotency keys, cursor auto-pagination, a typed error hierarchy and webhook verification — covered in the SDK overview.

Install

npm install @factuarea/sdk

Requires Node 20 or newer. The SDK is built on the Web fetch standard, so it also runs on Deno, Bun and Cloudflare Workers.

Authenticate

Pass your API key. The key prefix selects the environment — there is no separate flag: a fact_test_… key always runs against the isolated sandbox, a fact_live_… key against production.

import { Factuarea } from "@factuarea/sdk";

const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });

factuarea.environment; // "test" or "live", derived from the key prefix

Optional configuration:

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
});

Server-side only. Your API key is a secret. Never ship the SDK with a live key to a browser, mobile app or any public client — use it from your backend.

Quickstart

Create a client and an invoice, then download its PDF. Every operation is reachable as <resource>.<method>; the per-endpoint snippets in the API reference show the exact call for each operation.

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()),
);

Run everything with a fact_test_ key first — sandbox effects (VeriFactu → AEAT, FACe, email, webhooks) are switched off. When your flow works end-to-end, swap the prefix to fact_live_. See Test mode & sandbox.

Next steps

The runtime behaviour — retries, idempotency, cursor auto-pagination, the typed error hierarchy and webhook verification — is shared across both SDKs and documented once in the SDK overview:

Install

Authenticate

Quickstart

Next steps

On this page