Come accedere alla documentazione
Puoi raggiungere la documentazione API in due modi: dalla home page di Perno oppure dalla dashboard, una volta effettuato l'accesso.
Dalla home page
- Vai su perno.io.
- Nel menu in alto clicca su API documentation.
Dalla dashboard, da autenticato
- Accedi alla dashboard di Perno.
- Clicca sulle tue iniziali in alto a destra per aprire il menu dell'account.
- Seleziona API access.
- In fondo alla pagina, nella sezione Documentation, clicca su Open API reference - accanto trovi anche il campo API base URL con l'indirizzo dell'API.
Entrambi i percorsi portano alla stessa documentazione all'indirizzo perno.io/api/v1/reference/.
Dove trovare la documentazione
Il riferimento completo si trova all'indirizzo perno.io/api/v1/reference/. Elenca tutti gli endpoint con i relativi parametri, un esempio di richiesta e un esempio di risposta, raggruppati in un menu laterale con funzione di ricerca in base al prodotto.
La stessa specifica è disponibile anche come:
- Redoc - una versione di sola lettura, su un'unica pagina, dell'intera API.
- Swagger - una vista interattiva in cui puoi inviare richieste direttamente dal browser.
- Lo schema OpenAPI grezzo - utile se vuoi generare una libreria client per il tuo linguaggio, o importare l'API in uno strumento come Postman o Insomnia.
Dove trovare le tue chiavi API
Solo il proprietario dell'account (owner) può visualizzare e generare il token API:
- Accedi alla dashboard di Perno.
- Clicca sulle tue iniziali in alto a destra per aprire il menu dell'account - accanto a API access trovi anche, tra le altre, Company data, Merchant accounts e Your subscriptions.
- Seleziona API access.
- Nella sezione API token clicca su Show token per visualizzarlo, oppure direttamente su Copy token per copiarlo negli appunti.
Se non sei il proprietario, questa voce di menu non comparirà per te: chiedi al proprietario dell'account Perno della tua organizzazione di condividere o gestire l'accesso alle API.
La pagina API access avverte esplicitamente: "Treat this token like a password. Do not include it in browser code, public repositories, screenshots, or support messages." Tratta il token come una password: non inserirlo in codice lato browser, repository pubblici, screenshot o messaggi al supporto.
Invia il token con ogni richiesta protetta nell'header Authorization - trovi lo stesso identico esempio anche nella pagina API access, nella sezione How to authenticate:
Authorization: Token YOUR_API_TOKEN
La tua prima richiesta
La sezione Quick start della documentazione contiene un esempio pronto all'uso che chiama l'endpoint di health check:
export PERNO_API_TOKEN="YOUR_API_TOKEN" curl "https://perno.io/api/v1/health_check" \ -H "Authorization: Token $PERNO_API_TOKEN"
Se il token è valido, riceverai una risposta JSON corretta. Se manca, è errato o è scaduto, ogni endpoint protetto restituirà lo stesso errore 401 - un modo rapido per verificare che il token sia configurato correttamente prima di costruirci sopra un'integrazione.
Gli endpoint sono organizzati per prodotto
Il menu laterale della documentazione raggruppa gli endpoint come la dashboard raggruppa i contesti (vedi Cos'è un contesto in Perno?) - il prodotto che selezioni nella dashboard è la stessa sezione in cui troverai i suoi endpoint:
- Core resources - health check e schema OpenAPI, disponibili indipendentemente dal prodotto.
- Orchestration - link di pagamento, account merchant e metodi di pagamento, per elaborare pagamenti tramite Perno Orchestration.
- Perno Commerce - tutto ciò che riguarda un negozio: categorie, produttori e prodotti, oltre ai dati del catalogo aziende, come aziende, paesi, città, stati/regioni, servizi e specializzazioni.
Gli endpoint di Perno Commerce sono legati a uno specifico negozio, quindi le richieste di lista e dettaglio richiedono un parametro store_id che indica a quale dei tuoi negozi si riferisce la richiesta.
Le stesse convenzioni REST valgono ovunque
Indipendentemente dal prodotto, le risorse dell'API seguono lo stesso schema, quindi una volta capito un endpoint, tutti gli altri si comportano allo stesso modo:
- GET su una collezione restituisce un elenco di record, su un singolo record ne restituisce i dettagli.
- POST crea un nuovo record.
- PUT sostituisce interamente un record, PATCH aggiorna solo i campi inviati.
- DELETE elimina un record.
Esempio: creare un link di pagamento
Ecco come si presenta in pratica una coppia richiesta/risposta, usando l'endpoint di Orchestration per creare un link di pagamento hosted:
curl -X POST "https://perno.io/api/v1/payment_links/" \
-H "Authorization: Token YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchant_account": 1,
"amount": "10.00",
"currency": "USD",
"customer_email": "[email protected]",
"trx_id": "123"
}'
Una richiesta riuscita restituisce 201 con la risorsa creata:
{
"payment_hash": "string",
"merchant_account": 1,
"trx_hash": "string",
"trx_id": "string",
"amount": "string",
"customer_email": "string",
"one_time_link": true,
"used": true
}
Codici di risposta e di errore
Ogni endpoint restituisce JSON e usa gli stessi codici di stato in tutti i prodotti:
- 200 - la richiesta è andata a buon fine e il corpo della risposta contiene la risorsa o l'elenco richiesto.
- 201 - una nuova risorsa è stata creata con successo.
- 400 - errore di validazione; il corpo della risposta contiene errori sui singoli campi o un messaggio dettagliato, quindi controlla i campi della richiesta e i valori dei parametri.
- 401 - il token è mancante, non valido o scaduto; invia un header Authorization valido.