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

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

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"

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

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"

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.

Non trovi quello che cerchi? Chiedilo all’assistente nel portale, oppure scrivi a hello@smokingmirror.eu.
Versione per le AI (markdown)