brivio-sdk

brivio-sdk

Official TypeScript/JavaScript SDK for the Brivio public API — invoicing, contacts, articles, payments, e-Factura and the TrustFlow eIDAS trust services (signatures, seals, validation, timestamps).

Install

npm install brivio-sdk
# or
pnpm add brivio-sdk

Quick start

import { BrivioClient } from "brivio-sdk";

const brivio = new BrivioClient({ apiKey: "brivio_sk_live_…" });

const me = await brivio.me.get();
const { data: contacts } = await brivio.contacts.list({ search: "srl" });
const contact = await brivio.contacts.create({
  name: "ACME SRL",
  vat_number: "RO12345678",
});
const article = await brivio.articles.create({
  name: "Consultanță",
  price: 100,
  vat_rate: 21,
});

const invoice = await brivio.invoices.create({
  contact_id: contact.id,
  series: "FAC",
  items: [
    { description: "Consultanță", quantity: 1, unit_price: 100, vat_rate: 21 },
  ],
});
await brivio.invoices.submitToEFactura(invoice.id);

Available resources: me, contacts, articles, locations, modules, invoices (CRUD + submitToEFactura), documents (CRUD), projects (list/create), quotes (list/get), timeEntries (list/get), expenses (list/create), contracts (list/create), payments (charge), catalog (list), subscriptions (manage), webhooks (CRUD + rotateSecret + deliveries), apiKeys (list/create/revoke), trust (sign/validate/timestamp/providers).

Webhooks

Pagination

Every list endpoint returns a { data, meta } page. For large datasets use the built-in async iterator — it fetches subsequent pages automatically:

// Iterate all contacts without manual page management
for await (const contact of brivio.paginate<Contact>("/contacts", {
  search: "srl",
})) {
  console.log(contact.name);
}

Resilience

Transient failures (429, 502-504, network errors) are retried automatically (default: 2 retries, exponential backoff + jitter, honors Retry-After). Each request has a 30-second timeout. Both are configurable:

const brivio = new BrivioClient({
  apiKey: "brivio_sk_live_…",
  maxRetries: 3, // 0 to disable
  timeoutMs: 10_000,
});

Webhooks

const hook = await brivio.webhooks.create({
  url: "https://app.example/hooks/brivio",
  events: ["invoice.paid", "contact.created"],
});
// hook.secret is returned ONCE — store it for signature verification.

// Server-side signature verification (Node 18+):
import { verifyWebhookSignature } from "brivio-sdk";
const ok = verifyWebhookSignature(
  rawBody, // raw request body string
  req.headers["x-brivio-signature"], // "sha256=<hex>"
  hook.secret,
  req.headers["x-brivio-timestamp"], // optional replay protection
);

API surfaces

Two backends serve the API, both behind the same key:

• Gateway (https://api.brivio.ro/v1, default) — core data resources: me, contacts, articles, invoices, documents, projects, expenses, contracts, locations, modules, webhooks.
• App (https://app.brivio.ro/api/v1) — Stripe/KMS-bound resources that must run in the app: payments, catalog, subscriptions.

Point those resources at the app surface by constructing a second client:

const billing = new BrivioClient({
  apiKey: "brivio_sk_live_…",
  baseUrl: "https://app.brivio.ro/api/v1",
});
await billing.payments.charge({
  amount: 1000,
  currency: "RON",
  order_id: "o1",
});

Authentication

Mint an API key in Developers → API keys:

brivio_sk_live_…   # production
brivio_sk_test_…   # sandbox

Migrating from a competitor?

For PHP, the brivio/sdk Composer package ships drop-in shims for FGO, SmartBill, Oblio and Facturis. See the migration guides.

Types

The SDK ships full TypeScript types generated from the OpenAPI spec (trustflow-openapi.json). Bring your own fetch (Node 18+, edge, browsers).

License

MIT