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/sdkCreate 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 firstOptions: apiKey (default GETBEEL_API_KEY), baseUrl (default https://www.getbeel.com/api/v1), company, maxRetries (2), timeoutMs (60 000), fetch.
Resources
| Property | Methods |
|---|---|
me() | Account, company, key mode and scopes |
invoices | list, listAll, get, create, validate, send, email, listDeliveries, recordPayment, listPayments, createPaymentLink, sendReminder |
recurringInvoices | list, get, create, update, delete, pause, resume |
receivedInvoices | list, listAll, approve, reject |
bankStatements | upload, uploadFromUrl, list, listAll, get |
bankTransactions | list, listAll |
reconciliations | create, get, listMatches, createMatch, approveMatch, rejectMatch |
unmatched | payments, invoices |
bankConnections | list, get, create, delete, sync, reconnect |
connections | list, createEmail, scan, forwardingAddress, createStripe, syncStripe |
companies | list, get, create, update |
taxes | calendar, vatPosition, vatRegisters, vatSettlement, report, accountantExport |
filings | prepare, 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'); // BlobWebhooks
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.