GetbeelDocs

SDK TypeScript

Il client ufficiale per Node.js e TypeScript, generato dalla specifica OpenAPI.

@getbeel/sdk copre tutta l'API con i tipi generati dalla specifica OpenAPI. Aggiunge un Idempotency-Key a ogni POST che lo supporta, riprova i limiti di frequenza e gli errori del server, lancia errori tipizzati, scorre le liste e verifica le firme dei webhook. ESM, nessuna dipendenza: Node.js 20.19+, Deno, Bun, Cloudflare Workers e Vercel Edge.

npm install @getbeel/sdk

Crea e invia una fattura

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

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

const bozza = 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: 'Consulenza, ottobre',
      quantity: '1',
      unit_price: '1000.00',
      vat_rate: '22.00',
    },
  ],
});

const inviata = await getbeel.invoices.send(bozza.id); // mostra la bozza e chiedi l'OK prima

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

Risorse

ProprietàMetodi
me()Account, azienda, modalità della chiave e scope
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

I tipi delle richieste e delle risposte sono esportati (Invoice, CreateInvoiceRequest, Filing…), e tutti sotto types.

Idempotenza e nuovi tentativi

Ogni POST che supporta l'idempotenza (creazioni, invii, pagamenti, caricamenti, sincronizzazioni) riceve un Idempotency-Key casuale, lo stesso a ogni nuovo tentativo automatico: un create ripetuto non crea mai due fatture. Una chiamata fallita lo riporta in error.idempotencyKey: riprova con quella chiave, mai con una nuova. Per sceglierla tu:

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

Le letture e quei POST vengono riprovati due volte con attesa crescente su 408, 429 (dopo Retry-After), 5xx, errori di rete e 409 idempotency_key_in_use. Gli altri POST (approva, rifiuta, sospendi, caricamento della quietanza) solo su 429, così non agiscono mai due volte.

Errori

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

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

code è il codice d'errore dell'API. Gli errori di rete hanno status: 0 e codice connection_error o timeout.

Paginazione

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

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

Aziende clienti

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

Ogni chiamata porta l'header Getbeel-Company. Vedi Aziende.

File

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

await getbeel.bankStatements.upload({
  file: await readFile('ottobre.csv'),
  filename: 'ottobre.csv',
});
await getbeel.bankStatements.uploadFromUrl({
  file_url: 'https://…/estratto.pdf',
}); // oltre 4,5 MB
const pdf = await getbeel.filings.file('FILING_ID'); // Blob (l'XML per una 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

Webhook

Verifica la firma sul corpo grezzo, prima di leggerlo come JSON:

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('firma non valida', { status: 400 });
  if (event.type === 'invoice.delivered') {
    // …
  }

  return new Response('ok');
}

webhooks.verify(body, header, secret) restituisce true o false. Le firme più vecchie di 5 minuti sono rifiutate (toleranceSeconds). Vedi Webhook.

In questa pagina