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/sdkCrea 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 primaOpzioni: 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 |
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 |
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'); // BlobWebhook
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.