# Usa le API con una chiave

**Cosa ottieni.** Un tuo programma legge i dati dell'organizzazione e scrive operazioni, dentro le regole scelte dal proprietario.

**Ti serve.** Essere il proprietario, o chiedere a lui la chiave. Un terminale con `curl` per la prova.

## Passo per passo

1. Nel portale vai in Impostazioni, Chiavi per i programmi, e premi «Crea una chiave».
2. Dalle il nome del programma che la userà, per esempio «Gestionale magazzino».
3. Scegli cosa può fare: «Legge i dati» (`lettura`), «Propone operazioni» (`proposta`) o entrambe. Se vuoi, una scadenza.
4. Premi «Crea una chiave» e copia subito la chiave: comincia con `sm_` e non la vedrai più.
5. Mettila in una variabile d'ambiente e prova la prima chiamata:

```sh
export SM_API_KEY='<chiave>'
B=https://portal.smokingmirror.eu/api/v1
curl -s -H "Authorization: Bearer $SM_API_KEY" "$B/io"
curl -s -H "Authorization: Bearer $SM_API_KEY" "$B/tipi"
```

6. Proponi un'operazione, con una `idempotency_key` stabile così una ripetizione non crea doppioni:

```sh
curl -s -X POST -H "Authorization: Bearer $SM_API_KEY" -H "Content-Type: application/json" \
  -d '{"kind":"aggiorna_oggetto","payload":{"object_id":"<id>","data":{"stato":"spedito"}},"note":"Spedito dal magazzino","idempotency_key":"magazzino-ordine-0007"}' \
  "$B/operazioni"
```

7. Leggi lo `status` della risposta: `eseguita` se il proprietario lo ha lasciato fare alle chiavi, altrimenti `proposta`, in attesa in «Da approvare». Segui l'esito con `GET /operazioni/{id}`.

## Le rotte

| Metodo e rotta | Ambito | Risposta |
|---|---|---|
| `GET /io` | qualsiasi | organizzazione, ambiti e scadenza della chiave |
| `GET /tipi` | lettura | tipi, proprietà e legami |
| `GET /oggetti?tipo=&q=&limite=&da=` | lettura | schede di un tipo, al massimo 200 per pagina |
| `GET /oggetti/{id}` | lettura | una scheda con i suoi legami |
| `POST /operazioni` | proposta | `201` con `id` e `status` |
| `GET /operazioni/{id}` | lettura | stato ed esito |

## Se qualcosa non va

**Risponde 401.**
La chiave manca, è sbagliata, revocata o scaduta. Va solo nell'intestazione `Authorization: Bearer`, mai nell'indirizzo.

**Risponde 403 `ambito_mancante`.**
La chiave non ha l'ambito della rotta: per scrivere serve `proposta`.

**Risponde 429 `limite_superato`.**
Hai finito le chiamate del giorno previste dal piano. Non ritentare subito.

**Ho incollato la chiave dove non dovevo.**
Revocala subito dal portale e creane una nuova.

---

Questa pagina sul sito: https://smokingmirror.eu/documentazione/tutorial/usa-le-api-con-una-chiave/