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

Crea una chiave di test, fai la prima chiamata, valida un XML e invia una fattura nella sandbox.

Invia la tua prima fattura elettronica in circa cinque minuti, nella sandbox: niente arriva allo SDI vero e niente si paga.

## Prima di iniziare [#prima-di-iniziare]

- **Un account Getbeel** con un team. Per le chiavi di test Impostazioni → Azienda non deve essere completa.
- **Il permesso di gestire le impostazioni** in quel team (titolari e membri, non i revisori), per creare una chiave.
- **Non servono:** una carta, un piano, una chiave live o la configurazione SDI. La sandbox e le chiavi di test sono gratuite ([Prezzi](/it/api/pricing)).

<Callout title="Usi un agente di programmazione?">
Copia questo prompt in Claude Code, Cursor o 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>

### Crea una chiave di test [#crea-una-chiave-di-test]

Nell'app Getbeel apri **Impostazioni → Chiavi API e MCP** e crea una chiave in modalità **Test**. La chiave (`gb_test_…`) viene mostrata una volta sola: copiala subito.

Possono creare chiavi i membri con il permesso di gestire le impostazioni (proprietari e membri, non i revisori).

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

</Step>
<Step>

### Fai la prima chiamata [#fai-la-prima-chiamata]

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

```json title="Risposta"
{
  "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"
    ]
  }
}
```

La risposta è abbreviata. `api_key.mode` ti conferma che stai usando una chiave di test.

</Step>
<Step>

### Valida un XML FatturaPA [#valida-un-xml-fatturapa]

Manda un file XML così com'è, oppure in JSON come `{ "xml": "…" }`. Niente viene inviato né salvato.

```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="Risposta"
{
  "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"]
}
```

La validazione usa lo schema XSD ufficiale FatturaPA (v1.2.3) e i controlli SdI sul contenuto che dipendono dal solo file (Specifiche tecniche v1.9.1, Appendice 1: IVA e natura, totali con le tolleranze SdI, riepiloghi, regole per tipo documento), gli stessi controlli che Getbeel esegue prima di ogni invio. Ogni errore ha il codice e la descrizione dell'Agenzia delle Entrate: `00200` per lo schema (con la riga del file), `00201` oltre 50 errori di formato, `00313`–`00476` per i contenuti. Non controllati in locale: firme, anagrafe tributaria (partite IVA, codici destinatario) e duplicati.

</Step>
<Step>

### Crea una bozza [#crea-una-bozza]

```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": "Consulenza ottobre", "quantity": "1", "unit_price": "1000.00", "vat_rate": "22.00" }
    ]
  }'
```

La risposta è la fattura con `status: "draft"` e il suo `id`. L'elenco completo dei campi è nel [riferimento API](/it/api/reference).

</Step>
<Step>

### Invia la bozza nella sandbox [#invia-la-bozza-nella-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)"
```

Con una chiave di test l'invio va alla sandbox, che risponde come lo SDI: la fattura passa a `sent` e poi a `delivered`. Controlla lo stato con `GET /invoices/{id}` oppure ricevi i [webhook](/it/api/webhooks).

</Step>
<Step>

### Prova uno scarto [#prova-uno-scarto]

Crea un'altra bozza con `"partita_iva": "00000000000"` per il cliente e inviala: la sandbox la scarta con il codice `00305` (IdCodice del cliente non valido) e la fattura passa a `rejected`: correggila e inviala di nuovo con lo stesso numero e la stessa data (vedi [ciclo di vita SDI](/it/api/sdi-lifecycle)). Tutti gli esiti sono nella pagina [Sandbox](/it/api/sandbox).

</Step>
</Steps>

## Cosa è successo [#cosa-è-successo]

- **Hai creato una chiave di test.** Agisce sul tuo team con i tuoi accessi, solo sui dati della sandbox. È salvata come hash: Getbeel non può mostrarla di nuovo.
- **`GET /me` l'ha verificata.** `api_key.mode` è `test` e `api_key.scopes` elenca cosa può fare la chiave.
- **L'XML è stato validato** con gli stessi controlli che Getbeel fa prima di ogni invio. Non è stato salvato nulla.
- **È stata creata una bozza** con `status: "draft"`, il numero successivo della sequenza di test e la data di oggi. Finché non la invii, la modifichi con `PATCH /invoices/{id}`.
- **La sandbox ha risposto come lo SDI**: `sent`, poi `delivered` (oppure `rejected` con il codice SDI). Con una chiave live le stesse chiamate arrivano allo SDI vero.

## Se qualcosa non va [#se-qualcosa-non-va]

| Errore                       | Causa                                                | Soluzione                                                                |
| ---------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
| `401` `missing_api_key`      | Manca l'header `Authorization`                       | Invia `-H "Authorization: Bearer $GETBEEL_API_KEY"`                      |
| `401` `invalid_api_key`      | La chiave è sbagliata o la variabile è vuota         | `echo $GETBEEL_API_KEY`, poi copia di nuovo la chiave o creane una nuova |
| `403` `insufficient_scope`   | Alla chiave manca il permesso indicato nel messaggio | Crea una chiave con quel permesso (le chiavi non si modificano)          |
| `403` `company_not_eligible` | Per emettere serve un profilo aziendale italiano     | Completa **Impostazioni → Azienda**                                      |
| `422` su `POST /invoices`    | Un campo manca o non è valido; `param` dice quale    | Correggi il campo e invia di nuovo con un nuovo `Idempotency-Key`        |

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

Tutti i codici e cosa fare: [Errori](/it/api/errors).

## Prossimi passi [#prossimi-passi]

<Cards>
  <Card title="Webhook" href="/it/api/webhooks">
    Ricevi un evento firmato per ogni esito SDI, senza interrogare l'API.
  </Card>
  <Card title="MCP" href="/it/api/mcp">
    Fai preparare le fatture a Claude, ChatGPT o Cursor, e approvale tu.
  </Card>
  <Card title="Passa a live" href="/it/api/authentication">
    Crea una chiave live quando il flusso nella sandbox funziona dall'inizio
    alla fine.
  </Card>
  <Card title="SDK e CLI" href="/it/api/sdk-typescript">
    Le stesse chiamate in TypeScript, Python o dal terminale.
  </Card>
</Cards>
