GetbeelDocs

TypeScript SDK

The official Node.js and TypeScript client, generated from the OpenAPI spec.

@getbeel/sdk wraps the whole API with types generated from the OpenAPI spec. It adds an Idempotency-Key to every POST that supports one, retries rate limits and server errors, throws typed errors, pages through lists and verifies webhook signatures. ESM, no runtime dependencies: Node.js 20.19+, Deno, Bun, Cloudflare Workers and Vercel Edge.

npm install @getbeel/sdk

Create and send an invoice

import { Getbeel } from '@getbeel/sdk';

const getbeel = new Getbeel({ apiKey: process.env.GETBEEL_API_KEY }); // gb_test_… in the sandbox

const draft = await getbeel.invoices.create({
  tipo_documento: 'TD01',
  currency: 'EUR',
  customer: {
    denominazione: 'Bianchi S.p.A.',
    partita_iva: '01234567890',
    country: 'IT',
    codice_destinatario: 'ABCDE12',
  },
  lines: [
    {
      description: 'Consulting, October',
      quantity: '1',
      unit_price: '1000.00',
      vat_rate: '22.00',
    },
  ],
});

const sent = await getbeel.invoices.send(draft.id); // show the draft and get an OK first

Options: apiKey (default GETBEEL_API_KEY), baseUrl (default https://www.getbeel.com/api/v1), company, maxRetries (2), timeoutMs (60 000), fetch.

Resources

PropertyMethods
me()Account, company, key mode and scopes
invoiceslist, listAll, get, create, validate, send, email, listDeliveries, recordPayment, listPayments, createPaymentLink, sendReminder
recurringInvoiceslist, get, create, update, delete, pause, resume
receivedInvoiceslist, listAll, approve, reject
bankStatementsupload, uploadFromUrl, list, listAll, get
bankTransactionslist, listAll
reconciliationscreate, get, listMatches, createMatch, approveMatch, rejectMatch
unmatchedpayments, invoices
bankConnectionslist, get, create, delete, sync, reconnect
connectionslist, createEmail, scan, forwardingAddress, createStripe, syncStripe
companieslist, get, create, update
taxescalendar, vatPosition, vatRegisters, vatSettlement, report, accountantExport
filingsprepare, list, listAll, get, file, uploadReceipt

Request and response types are exported (Invoice, CreateInvoiceRequest, Filing…), and all of them under types.

Idempotency and retries

Every POST that supports idempotency (creates, sends, payments, uploads, syncs) gets a random Idempotency-Key, the same on every automatic retry, so a retried create never creates two invoices. A failed call carries it in error.idempotencyKey: retry with that key, never a new one. To choose it yourself:

await getbeel.invoices.send(draft.id, { idempotencyKey: `send-${draft.id}` });

Reads and those POSTs are retried twice with backoff on 408, 429 (after Retry-After), 5xx, network errors and 409 idempotency_key_in_use. Other POSTs (approve, reject, pause, receipt upload) are retried only on 429, so they never act twice.

Errors

import { GetbeelError } from '@getbeel/sdk';

try {
  await getbeel.invoices.get('missing');
} catch (error) {
  if (error instanceof GetbeelError) {
    console.log(
      error.status,
      error.type,
      error.code,
      error.param,
      error.requestId,
    );
  }
}

code is the API error code. Network failures have status: 0 and code connection_error or timeout.

Pagination

const page = await getbeel.invoices.list({ status: 'delivered', limit: 50 });
// page.data, page.has_more, page.next_cursor

for await (const invoice of getbeel.invoices.listAll({ status: 'delivered' })) {
  console.log(invoice.number);
}

Client companies

const client = getbeel.withCompany('COMPANY_ID'); // or new Getbeel({ company: 'COMPANY_ID' })
await client.invoices.list();

Every call carries the Getbeel-Company header. See Companies.

Files

import { readFile } from 'node:fs/promises';

await getbeel.bankStatements.upload({
  file: await readFile('october.csv'),
  filename: 'october.csv',
});
await getbeel.bankStatements.uploadFromUrl({
  file_url: 'https://…/statement.pdf',
}); // over 4.5 MB
const pdf = await getbeel.filings.file('FILING_ID'); // Blob (XML for a LIPE)
const registers = await getbeel.taxes.vatRegisters('2026-Q3');
const settlement = await getbeel.taxes.vatSettlement('2026-10');
const pnl = await getbeel.taxes.report('profit-and-loss', { period: '2026' });
const zip = await getbeel.taxes.accountantExport('2026-Q3'); // Blob

Webhooks

Verify the signature on the raw body, before parsing it:

import { webhooks } from '@getbeel/sdk';

export async function POST(request: Request) {
  const body = await request.text();
  const event = await webhooks
    .constructEvent(
      body,
      request.headers.get('Getbeel-Signature'),
      process.env.GETBEEL_WEBHOOK_SECRET!,
    )
    .catch(() => null);

  if (!event) return new Response('invalid signature', { status: 400 });
  if (event.type === 'invoice.delivered') {
    // …
  }

  return new Response('ok');
}

webhooks.verify(body, header, secret) returns true or false. Signatures older than 5 minutes are refused (toleranceSeconds). See Webhooks.

On this page