Chiavi API e ambiti

La API REST di Ringhum permette ai tuoi sistemi di interagire con il tuo spazio di lavoro: elencare chiamate e trascrizioni, creare assistenti, prenotare appuntamenti, gestire contatti, effettuare chiamate in uscita e altro ancora. Ogni richiesta viene autenticata con una chiave API che appartiene a uno spazio di lavoro. Questo articolo descrive come creare le chiavi e le convenzioni comuni a tutti gli endpoint. Il riferimento completo degli endpoint si trova su /docs.

Chi può gestire le chiavi

La API è disponibile su ogni piano. Ciò che una chiave può fare resta comunque limitato dal tuo piano: ad esempio, creare un assistente oltre il limite del piano restituisce un errore.

Crea una chiave API

1. Apri Sviluppatori nella barra laterale.
2. Nella scheda Chiavi API, clicca su Crea chiave.
3. Inserisci un Nome della chiave che indichi dove viene usata, ad esempio "Server di produzione".
4. In Ambiti, seleziona read, write o entrambi.
5. Clicca su Crea chiave.
6. Copia la chiave dal riquadro verde e conservala in un luogo sicuro, ad esempio l'archivio segreti del tuo server. Clicca su Fatto.

Importante: la chiave viene mostrata una sola volta. Ringhum conserva solo un'impronta della chiave, quindi non può essere mostrata di nuovo. Se la perdi, crea una nuova chiave e revoca quella vecchia.

Le chiavi iniziano con ck_live_. La tabella Chiavi API mostra il nome di ogni chiave, i primi caratteri della chiave, i suoi ambiti, l'ultimo utilizzo e se è Attivo o Revocata.

Ambiti

Ogni chiave può chiamare gli endpoint di sola lettura. Gli endpoint che creano, modificano o eliminano qualcosa richiedono l'ambito write. Esempi sono effettuare una chiamata, inviare un messaggio, prenotare un appuntamento o aggiornare un assistente. Il riferimento su /docs segnala questi endpoint. Una chiave senza write riceve un errore 403 su questi endpoint.

Dai a ogni sistema il minimo accesso necessario. Una dashboard di reportistica ha bisogno solo di read.

Revoca una chiave

1. Su Sviluppatori, trova la chiave nella tabella Chiavi API.
2. Clicca su Revoca e conferma.

Le richieste che usano la chiave falliscono immediatamente con 401. Le chiavi revocate restano nell'elenco, contrassegnate come Revocata, così puoi vederne la cronologia. Una chiave non può essere modificata: per cambiarne gli ambiti, crea una nuova chiave e revoca quella vecchia.

Effettuare le richieste

• URL di base: https://ringhum.com/api/v1
• Autenticazione: invia la chiave come token Bearer: Authorization: Bearer ck_live_…
• Formato: JSON in entrata e in uscita. Invia Content-Type: application/json con un corpo.
• Gli orari sono in ISO 8601 UTC. I numeri di telefono sono in formato E.164, ad esempio +14155550132. Gli id sono numeri interi.
• Gli aggiornamenti usano PATCH con solo i campi che vuoi modificare.
• Ogni risposta include un header X-Request-Id. Includilo quando contatti l'assistenza.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Per verificare a quale spazio di lavoro appartiene una chiave, chiama GET /me.

Risposte e paginazione

Un singolo oggetto viene restituito come {"data": {…}}. Gli elenchi paginati vengono restituiti con un oggetto meta:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Usa page e per_page per scorrere i risultati. per_page è 25 di default e può essere al massimo 100.

Errori

Ogni errore ha la stessa struttura, con un type stabile che puoi controllare nel tuo codice:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Limiti di frequenza

Puoi effettuare 120 richieste al minuto. Le risposte includono gli header X-RateLimit-Limit e X-RateLimit-Remaining. Quando superi il limite ricevi un 429 con un header Retry-After che indica i secondi di attesa.

Suggerimento: non fare polling per i risultati delle chiamate. Aggiungi un webhook per call.ended e Ringhum ti invierà il riepilogo e la trascrizione quando la chiamata sarà terminata. Vedi Webhook.

Domande frequenti

Esiste una specifica leggibile da macchina? Sì. La descrizione OpenAPI 3.1 si trova su /api/v1/openapi.json e non richiede una chiave. Puoi generare un client a partire da essa.

Una chiave smette di funzionare se la persona che l'ha creata lascia l'azienda? No. Le chiavi appartengono allo spazio di lavoro e continuano a funzionare finché non vengono revocate. Revoca le chiavi di cui non ti fidi più, soprattutto quando qualcuno che aveva accesso lascia l'azienda.

Posso usare la API da una pagina web? No. Chiunque apra la pagina potrebbe leggere la chiave. Chiama la API dal tuo server.