API di OuiHeberg: creare una chiave API e fare la prima chiamata

L'area clienti OuiHeberg ha una propria API. Con una chiave API, uno script o un programma interroga il tuo account senza passare dall'interfaccia, per esempio per tenere d'occhio i tuoi domini o le tue fatture. Questa guida spiega dove creare una chiave, come leggere la documentazione, fare una prima chiamata, rispettare i limiti e revocare una chiave.

Aprire la sezione Chiavi API

Accedi a dash.ouiheberg.com.
In alto a destra, clicca sul tuo nome, poi su Il mio profilo.
Nel menu della pagina Impostazioni account, scegli Chiavi API.

Il link diretto è dash.ouiheberg.com/settings?section=apikeys.

Sezione Chiavi API delle impostazioni dell'account, con i pulsanti Documentazione API e Nuova chiave

Qui trovi l'elenco delle tue chiavi. Finché non ne hai creata nessuna, compare Nessuna chiave API al momento. Ogni chiave accede solo al tuo account.

Creare una chiave

Clicca su Nuova chiave.
Dalle un nome chiaro, quello dello script o dello strumento che la userà. Il giorno in cui quello script sparisce, saprai quale chiave revocare.
Conferma la creazione della chiave.
L'area clienti mostra la chiave una sola volta. Copiala subito e conservala in un posto sicuro, per esempio in un gestore di password. Non potrai più rivederla.

Una chiave si può anche limitare a certi indirizzi IP, per esempio quelli dei server che la usano. Senza elenco, funziona da qualsiasi indirizzo. Con un elenco, una chiamata che arriva da un altro indirizzo viene rifiutata.

💡 Se l'area clienti ti chiede di attivare l'autenticazione a due fattori prima di creare una chiave, segui la nostra guida Attivare l'autenticazione a due fattori (2FA), poi torna su Chiavi API.

Leggere la documentazione dell'API

Il pulsante Documentazione API di questa sezione apre dash.ouiheberg.com/settings/api-docs.

Pagina della documentazione API con introduzione, autenticazione, errori e l'elenco degli endpoint per famiglia

Questa documentazione è fatta su misura per il tuo account. Mostra solo gli endpoint aperti per te, ordinati per famiglia (domini, negozio, account…). Ogni riga indica il suo metodo, GET per leggere, POST, PUT o PATCH per inviare o modificare, DEL per eliminare. In alto, alcune etichette indicano quanti endpoint ti sono aperti e quanti modificano il tuo account. Il campo di ricerca in alto a sinistra trova un endpoint a partire da una parola come «fattura» o «dominio».

Dall'introduzione conviene ricordare tre punti.

L'indirizzo di base dell'API è https://dash.ouiheberg.com/api/v1.
Tutte le risposte sono in JSON. Invia l'intestazione Accept: application/json e aggiungi Content-Type: application/json quando la richiesta ha un corpo.
In alto nella pagina, Le mie chiavi API ti riporta alle tue chiavi e Area clienti all'area clienti.

Manca un endpoint che ti serve? Allora non è aperto per il tuo account. Scrivici con un ticket spiegando cosa vuoi automatizzare.

Fare una prima chiamata

Ogni chiamata porta la tua chiave nell'intestazione Authorization, preceduta dalla parola Bearer. Tieni la chiave in una variabile d'ambiente, qui OH_API_KEY, invece di scriverla nei tuoi comandi. Una chiave incollata in uno script condiviso o in un ticket è una chiave da revocare.

Ecco la prima chiamata proposta dalla documentazione.

curl -H "Authorization: Bearer $OH_API_KEY" -H "Accept: application/json" https://dash.ouiheberg.com/api/v1/domains/check

Per vedere i parametri di un endpoint e cosa restituisce, aprilo nella documentazione.

Provare dalla pagina

La documentazione ti permette anche di lanciare una chiamata senza installare nulla. Incolla una delle tue chiavi nella pagina. Non viene salvata e sparisce se ricarichi. Poi avvia la prova dall'endpoint aperto.

Queste prove sono chiamate vere. Una chiamata che modifica il tuo account lo modifica davvero, e la pagina ti chiede una conferma prima dell'invio. Una chiamata che effettua un ordine emette una fattura reale, esattamente come un ordine dal negozio.

Importare in Postman

La sezione Importare in Postman offre una collezione pronta da importare, con i tuoi endpoint ordinati per famiglia. Il file non contiene la tua chiave. La inserisci in Postman, nella variabile prevista.

Postman non ti chiede alcuna conferma. Una chiamata che modifica il tuo account o effettua un ordine parte appena la invii.

Limiti di chiamate

Ogni chiave ha un proprio limite di chiamate al minuto e al giorno, fissato al momento della creazione. Ogni chiamata conta, anche le prove lanciate dalla documentazione. La sezione Limiti di chiamate della documentazione spiega il funzionamento.

Oltre il limite, l'API risponde con un errore 429. Prevedi una pausa nei tuoi script invece di ripetere la chiamata in un ciclo. Il limite al minuto si libera dopo un minuto, quello giornaliero il giorno dopo.

Capire gli errori

Una chiamata rifiutata restituisce un codice HTTP e un corpo JSON. Il campo code indica il motivo esatto e resta stabile da una versione all'altra. È il campo che i tuoi programmi devono leggere. Il campo message è pensato per le persone.

Risposta	Significato
`401`	La chiave manca, è sconosciuta, disattivata o scaduta. Controlla di averla copiata per intero.
`403` `ip_not_allowed`	La chiave accetta solo certi indirizzi IP, e la chiamata è arrivata da un altro.
`403` `endpoint_not_granted`	Questo endpoint non è aperto per il tuo account. Scrivici per ottenerlo.
`403` `route_not_allowed`	L'endpoint è aperto per il tuo account, ma questa chiave non lo copre. Modifica la chiave o usane un'altra.
`403` `api_access_blocked`	L'accesso API del tuo account è sospeso. Scrivici per conoscerne il motivo.
`429` `rate_limit_exceeded`	Il limite al minuto della chiave è stato raggiunto. La risposta indica quanto aspettare.
`429` `daily_quota_exceeded`	Il limite giornaliero della chiave è stato raggiunto.

Revocare una chiave

Revoca una chiave appena non serve più, o al minimo dubbio, per esempio se è stata incollata in un ticket, condivisa in uno script o lasciata su un computer perso.

Apri Impostazioni account › Chiavi API.
Sulla riga della chiave, clicca su Revoca.

I programmi che usavano questa chiave ricevono ora un errore 401. Se devono continuare a funzionare, crea una nuova chiave e sostituisci la vecchia nella loro configurazione.

💡 Sei un rivenditore? Le chiavi dell'API rivenditore non si creano qui, ma dall'area rivenditore, che si apre dalla sezione Account rivenditore.

Hai bisogno di aiuto?

Per far aprire un endpoint o ripristinare un accesso API, apri un ticket da Ticket › Aprire un ticket (dash.ouiheberg.com/tickets/new) e descrivi cosa vuoi automatizzare. Non incollare mai la tua chiave nel ticket.
Puoi anche scriverci sul nostro Discord.