# SDK TypeScript (https://docs.getbeel.com/it/api/sdk-typescript)

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

`@getbeel/sdk` copre tutta l'[API](/it/api/reference) 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.

```bash
npm install @getbeel/sdk
```

## Crea e invia una fattura [#crea-e-invia-una-fattura]

```ts
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 [#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 [#idempotenza-e-nuovi-tentativi]

Ogni `POST` che supporta l'[idempotenza](/it/api/idempotency) (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:

```ts
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 [#errori]

```ts
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](/it/api/errors) dell'API. Gli errori di rete hanno `status: 0` e codice `connection_error` o `timeout`.

## Paginazione [#paginazione]

```ts
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 [#aziende-clienti]

```ts
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](/it/api/companies).

## File [#file]

```ts
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 [#webhook]

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

```ts
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](/it/api/webhooks).
