TypeScript

npm install @factuarea/sdk

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

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

import { writeFile } from "node:fs/promises";
import { Factuarea } from "@factuarea/sdk";

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

// Company axis: every company resource hangs off `/v1/companies/{company}/…`, so the
// company id is the FIRST argument of each call (`data.scope[].id` of GET /v1/me).
const company = process.env.FACTUAREA_COMPANY_ID!;

// Responses are the API's `{ data: … }` envelope — read the resource off `.data`.

// 1. Create a customer contact.
const { data: contact } = await factuarea.contacts.create(company, {
  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(company, {
  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. It is a BinaryOrJsonResponse: narrow it on `kind` first.
const pdf = await factuarea.invoices.pdf(company, invoice.id);
if (pdf.kind === "binary") {
  await writeFile("invoice.pdf", pdf.toBuffer());
} else {
  // 202 (`kind: "json"`): still being generated. Ask again after `pdf.retryAfter` seconds.
  console.log("The PDF is not ready yet:", pdf.status);
}

import { readFile } from "node:fs/promises";
import { Factuarea } from "@factuarea/sdk";

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

// The account id is `data.account.id` of `factuarea.account.show()` (GET /v1/me).
const me = (await factuarea.account.show()) as { data: { account: { id: string } } };
const account = me.data.account.id;

// 1. List the NIF of the account (the account id goes FIRST).
const nifs = await factuarea.companies.list(account, { limit: 50 });
for await (const nif of nifs) {
  console.log((nif as { id: string }).id);
}

// 2. Preview and apply a bulk import of managed accounts (multipart/form-data).
const form = new FormData();
form.append(
  "accounts_file",
  new Blob([await readFile("accounts.csv")], { type: "text/csv" }),
  "accounts.csv",
);
form.append("options[send_email]", "false");

await factuarea.managedAccounts.imports.preview(form); // writes nothing
await factuarea.managedAccounts.imports.create(form);  // applies it

// 3. Create an account webhook (needs a fact_live_ key).
const created = (await factuarea.account.webhooks.create(account, {
  url: "https://example.com/webhooks/factuarea",
  enabled_events: ["account.nif_added", "invoice.paid"],
  account_relationship: "all",
})) as { data: { id: string; secret: string | null } };

// `secret` (whsec_…) is returned only now: store it to verify deliveries.
console.log(created.data.id, created.data.secret);

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

const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });
const company = process.env.FACTUAREA_COMPANY_ID!; // `data.scope[].id` of GET /v1/me
const invoiceId = "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b";

// 1. Create a template: only `name` is required.
const template = await factuarea.pdfTemplates.create(company, {
  name: "Factura clásica",
  base_preset: "classic",
});

// 2. List the library, one page per call.
const page = await factuarea.pdfTemplates.list(company, { page: 1, per_page: 20 });
for (const item of page.items) {
  console.log(item.id, item.name);
}

// 3. Pin the template on an invoice. `expected_version` is the `selection_version`
//    of the presentation state; `template_id: null` hands the choice back to the defaults.
const state = await factuarea.invoices.getPresentation(company, invoiceId);
await factuarea.invoices.assignPresentation(company, invoiceId, {
  template_id: template.id,
  expected_version: state.data.selection_version,
});

const templateId = "0199f3b2-5c1d-7e8f-9a0b-1c2d3e4f5a6b";

// Read the template and keep the ETag of the response.
let etag: string | null = null;
await factuarea.pdfTemplates.find(company, templateId, {
  onResponse: (meta) => {
    etag = meta.etag;
  },
});

// Send it back as If-Match. `null` clears the description; `name` is not sent, so it is kept.
await factuarea.pdfTemplates.update(
  company,
  templateId,
  { description: null },
  { ifMatch: etag ?? undefined },
);

import { writeFile } from "node:fs/promises";
import { setTimeout as sleep } from "node:timers/promises";

// `cachedEtag` is the ETag of the copy you already hold, if any.
let cachedEtag: string | undefined;

for (let attempt = 0; attempt < 5; attempt++) {
  const pdf = await factuarea.invoices.pdf(company, invoiceId, undefined, { ifNoneMatch: cachedEtag });
  if (pdf.kind === "binary") {
    await writeFile("invoice.pdf", pdf.toBuffer());
    cachedEtag = pdf.etag ?? undefined;
    break;
  }
  if (pdf.kind === "not_modified") {
    break; // 304: your copy is current.
  }
  await sleep((pdf.retryAfter ?? 1) * 1000); // 202: still being generated.
}