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

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

`@getbeel/sdk` wraps the whole [API](/en/api/reference) 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.

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

## Create and send an invoice [#create-and-send-an-invoice]

```ts
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 [#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 [#idempotency-and-retries]

Every `POST` that supports [idempotency](/en/api/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:

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

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

## Errors [#errors]

```ts
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](/en/api/errors). Network failures have `status: 0` and code `connection_error` or `timeout`.

## Pagination [#pagination]

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

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

## Files [#files]

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

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

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