# Quickstart (https://docs.getbeel.com/en/api/quickstart)

Create a test key, make your first call, validate an XML and send an invoice in the sandbox.

Send your first e-invoice in about five minutes, in the sandbox: nothing reaches the real SDI and nothing is billed.

## Before you start [#before-you-start]

- **A Getbeel account** with a team. Settings → Company does not need to be complete for test keys.
- **Permission to manage settings** in that team (owners and members, not auditors), to create a key.
- **Not needed:** a card, a plan, a live key or SDI set-up. The sandbox and test keys are free ([Pricing](/en/api/pricing)).

<Callout title="Using a coding agent?">
Copy this prompt into Claude Code, Cursor or Codex.

```text title="Prompt"
Add the Getbeel API to this project.

1. Read https://docs.getbeel.com/en/api/quickstart.md and https://docs.getbeel.com/llms.txt before writing code.
2. Read the API key from the GETBEEL_API_KEY environment variable. Never hard-code it. Use a test key (gb_test_...) until I say otherwise.
3. Base URL: https://www.getbeel.com/api/v1. Call GET /me first to check the key.
4. Validate invoices with POST /invoices/validate and create drafts with POST /invoices.
5. Show me the draft and wait for my OK before calling POST /invoices/{id}/send.
6. Send an Idempotency-Key header (a new UUID per operation) on every POST that creates or sends.
7. Handle errors by error.type and error.code; on 429 wait for the Retry-After seconds.
```

</Callout>

<Steps>
<Step>

### Create a test key [#create-a-test-key]

In the Getbeel app open **Settings → API keys & MCP** and create a key in **Test** mode. The key (`gb_test_…`) is shown once: copy it right away.

Members who can manage settings can create keys (owners and members, not auditors).

```bash
export GETBEEL_API_KEY="gb_test_..."
```

</Step>
<Step>

### Make your first call [#make-your-first-call]

```bash
curl https://www.getbeel.com/api/v1/me \
  -H "Authorization: Bearer $GETBEEL_API_KEY"
```

```json title="Response"
{
  "object": "account",
  "id": "5b0c2f8e-6a3d-4c1e-9f0a-2d7b1e4c9a10",
  "name": "Rossi S.r.l.",
  "slug": "rossi",
  "company": {
    "name": "Rossi S.r.l.",
    "vat_number": "01234567890",
    "regime_fiscale": "RF01",
    "sdi_configured": true
  },
  "api_key": {
    "prefix": "gb_test_a1B2",
    "mode": "test",
    "scopes": [
      "account:read",
      "invoices:read",
      "received_invoices:read",
      "invoices:validate"
    ]
  }
}
```

The response is shortened. `api_key.mode` confirms you are using a test key.

</Step>
<Step>

### Validate a FatturaPA XML [#validate-a-fatturapa-xml]

Send an XML file as is, or as JSON `{ "xml": "…" }`. Nothing is sent or stored.

```bash
curl https://www.getbeel.com/api/v1/invoices/validate \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @fattura.xml
```

```json title="Response"
{
  "object": "validation_result",
  "valid": false,
  "tipo_documento": "TD01",
  "errors": [
    {
      "code": "00421",
      "message": "DatiRiepilogo (rate 22): Imposta 30 does not match calculated 22.00"
    }
  ],
  "checks": ["structure", "xsd", "business_rules"]
}
```

Validation uses the official FatturaPA XSD schema (v1.2.3) and the SDI content controls that depend on the file alone (Specifiche tecniche v1.9.1, Appendice 1: VAT and natura, totals with SDI's tolerances, summaries, document type rules), the same checks Getbeel runs before every send. Each error carries the Agenzia delle Entrate code and wording: `00200` for the schema (with the line in the file), `00201` past 50 format errors, `00313`–`00476` for content. Not checked locally: signatures, the AdE registries (VAT numbers, recipient codes) and duplicates.

</Step>
<Step>

### Create a draft [#create-a-draft]

```bash
curl https://www.getbeel.com/api/v1/invoices \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "tipo_documento": "TD01",
    "customer": {
      "denominazione": "Bianchi S.p.A.",
      "partita_iva": "01234567890",
      "country": "IT",
      "codice_destinatario": "ABCDE12",
      "address": "Via Roma 1",
      "postal_code": "20121",
      "city": "Milano",
      "province": "MI"
    },
    "lines": [
      { "description": "Consulting, October", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00" }
    ]
  }'
```

The response is the invoice with `status: "draft"` and its `id`. The full list of fields is in the [API reference](/en/api/reference).

</Step>
<Step>

### Send the draft to the sandbox [#send-the-draft-to-the-sandbox]

```bash
curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

With a test key the send goes to the sandbox, which answers like SDI: the invoice moves to `sent` and then to `delivered`. Check the status with `GET /invoices/{id}` or receive [webhooks](/en/api/webhooks).

</Step>
<Step>

### Try a rejection [#try-a-rejection]

Create another draft with `"partita_iva": "00000000000"` for the customer and send it: the sandbox rejects it with code `00305` (customer IdCodice not valid) and the invoice becomes `rejected`: correct it and send it again with the same number and date (see [SDI lifecycle](/en/api/sdi-lifecycle)). Every outcome is on the [Sandbox](/en/api/sandbox) page.

</Step>
</Steps>

## What just happened [#what-just-happened]

- **You created a test key.** It acts on your team with your access, only on sandbox data. It is stored as a hash: Getbeel cannot show it again.
- **`GET /me` checked it.** `api_key.mode` is `test` and `api_key.scopes` lists what the key may do.
- **The XML was validated** with the same checks Getbeel runs before every send. Nothing was stored.
- **A draft was created** with `status: "draft"`, the next number of the test sequence and today's date. Until you send it, change it with `PATCH /invoices/{id}`.
- **The sandbox answered like SDI**: `sent`, then `delivered` (or `rejected` with the SDI code). With a live key the same calls reach the real SDI.

## If it fails [#if-it-fails]

| Error                        | Cause                                           | Fix                                                                  |
| ---------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
| `401` `missing_api_key`      | No `Authorization` header                       | Send `-H "Authorization: Bearer $GETBEEL_API_KEY"`                   |
| `401` `invalid_api_key`      | The key is mistyped, or the variable is empty   | `echo $GETBEEL_API_KEY`, then copy the key again or create a new one |
| `403` `insufficient_scope`   | The key lacks the scope named in the message    | Create a key with that scope (keys cannot be edited)                 |
| `403` `company_not_eligible` | Issuing needs an Italian company profile        | Complete **Settings → Company**                                      |
| `422` on `POST /invoices`    | A field is missing or invalid; `param` names it | Fix the field and send again with a new `Idempotency-Key`            |

```json title="401 response"
{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key provided. Send it as 'Authorization: Bearer gb_…'."
  }
}
```

Every code and what to do with it: [Errors](/en/api/errors).

## Next steps [#next-steps]

<Cards>
  <Card title="Webhooks" href="/en/api/webhooks">
    Get a signed event for every SDI outcome instead of polling.
  </Card>
  <Card title="MCP" href="/en/api/mcp">
    Let Claude, ChatGPT or Cursor prepare invoices for you to approve.
  </Card>
  <Card title="Go live" href="/en/api/authentication">
    Create a live key when the sandbox flow works end to end.
  </Card>
  <Card title="SDKs and CLI" href="/en/api/sdk-typescript">
    The same calls in TypeScript, Python or the terminal.
  </Card>
</Cards>
