API e webhook del negozio

La scheda «Développeurs» (Sviluppatori) della sezione «Boutique» (Negozio online) permette a un altro software (gestione del magazzino, cassa, contabilità, sito su misura) di leggere e aggiornare il tuo negozio e di ricevere in tempo reale gli eventi importanti: ordine effettuato, magazzino modificato, reso richiesto. Per consultare la schermata basta poter leggere il negozio; per creare, modificare o revocare bisogna poterlo modificare. Vedi anche il negozio online.

Azioni frequenti

Creare una chiave API

1. Apri Boutique, scheda Développeurs, sezione «Clés d'API» (Chiavi API), poi «Nouvelle clé» (Nuova chiave).
2. Indica un «nom» (nome) che dica a cosa serve la chiave (per esempio «Software di cassa»).
3. Spunta i «droits» (permessi) necessari, oppure usa le impostazioni predefinite «Lecture seule» (Sola lettura) e «Lecture et écriture» (Lettura e scrittura). Spunta solo lo stretto necessario.
4. Se serve, imposta il «limite de débit» (limite di richieste) (120 richieste al minuto per impostazione predefinita, da 10 a 1.200) e una «date d'expiration» (data di scadenza) (al massimo un anno).
5. Clicca su «Créer la clé» (Crea la chiave).

La chiave completa, che inizia con shk_, viene mostrata una sola volta, in un riquadro a parte. Copiala subito con il pulsante «Copier» (Copia) e conservala nel gestore di password dello strumento che la userà. Una volta chiuso il riquadro, SheepOS non può più mostrarla: nell'elenco resta visibile solo il suo inizio. Se l'hai persa, revocala e creane un'altra.

I permessi di una chiave

Ogni permesso riguarda una risorsa, in lettura o in scrittura: prodotti, magazzino, ordini, clienti. Un permesso di scrittura dà anche la lettura della stessa risorsa. Per esempio, una chiave che sincronizza soltanto il magazzino ha bisogno solo di «Lire le stock» (Leggere il magazzino) e «Modifier le stock» (Modificare il magazzino): anche se finisce in mani sbagliate, non dà accesso né agli ordini né ai clienti. I permessi di una chiave si modificano in un secondo momento, senza cambiare la chiave.

Buone pratiche di sicurezza

• Crea una chiave per integrazione: saprai quale usa cosa (colonna «Dernière utilisation» (Ultimo utilizzo)) e potrai revocarne una senza toccare le altre.
• Revoca subito una chiave che è trapelata o il cui strumento non è più usato. La revoca è immediata e irreversibile.
• Non mettere mai una chiave in un sito web, in una pagina o in un'app mobile: qualsiasi visitatore potrebbe leggerla. Deve stare solo su un tuo server.
• Non inviarla per e-mail o tramite messaggistica, non inserirla nell'indirizzo di una richiesta e non farne il commit in un repository di codice.
• Dai una data di scadenza alle chiavi temporanee (fornitore, prova).
• Tieni d'occhio il «Journal d'accès» (Registro degli accessi): rifiuti 401 o 403 ripetuti, o richieste a orari insoliti, sono un segnale.

Fare una prima chiamata

L'API ha come indirizzo di base https://IL-TUO-SERVER/api/v1/shop, mostrato nella sezione «Documentation» (Documentazione). Ogni richiesta porta la chiave nell'intestazione Authorization.

Per verificare che la chiave funzioni: curl "https://IL-TUO-SERVER/api/v1/shop" -H "Authorization: Bearer shk_LA_TUA_CHIAVE"

Per elencare i prodotti (permesso «Lire les produits» (Leggere i prodotti)): curl "https://IL-TUO-SERVER/api/v1/shop/products?limit=50" -H "Authorization: Bearer shk_LA_TUA_CHIAVE"

Per fissare il magazzino di un prodotto (permesso Modifier le stock): curl -X PUT "https://IL-TUO-SERVER/api/v1/shop/stock/ID_PRODOTTO" -H "Authorization: Bearer shk_LA_TUA_CHIAVE" -H "Content-Type: application/json" -d '{"quantity": 12}'

Gli importi sono numeri interi in centesimi. I prezzi dei prodotti sono al netto delle imposte, i totali degli ordini comprensivi di tutte le imposte. Gli elenchi sono paginati: passa il valore nextCursor della pagina ricevuta nel parametro cursor per ottenere la successiva, e updatedSince per recuperare solo ciò che è cambiato. La sezione Documentation della schermata elenca tutte le rotte, i loro parametri, il loro corpo e un esempio curl.

Creare un webhook

1. Sezione «Webhooks», poi «Nouvelle adresse» (Nuovo indirizzo).
2. Inserisci l'indirizzo del tuo server, che deve iniziare con https://, e una descrizione.
3. Scegli gli «événements» (eventi) ricevuti, oppure tutti.
4. Clicca su «Créer l'adresse» (Crea l'indirizzo) e copia il secret whsec_…: come una chiave API, viene mostrato una sola volta.
5. Clicca su «Tester» (Testa): SheepOS invia un evento di prova e mostra lo stato HTTP, la durata e l'eventuale errore.

Il pulsante «Nouveau secret» (Nuovo secret) sostituisce il secret, dopo conferma: il vecchio smette subito di funzionare, aggiorna quindi il tuo server immediatamente. «Supprimer» (Elimina) rimuove l'indirizzo e il suo registro di consegna.

Verificare la firma di un webhook

Ogni invio porta l'intestazione SheepOS-Signature: t=SECONDES,v1=HEX. Verificala prima di agire, altrimenti chiunque potrebbe inviare falsi eventi al tuo server:

1. Leggi il corpo grezzo della richiesta, prima di qualsiasi elaborazione JSON.
2. Estrai t e v1 dall'intestazione.
3. Calcola l'HMAC-SHA256 del testo formato da t, da un punto e poi dal corpo grezzo, con il tuo secret whsec_…, in esadecimale.
4. Confronta il risultato con v1 in tempo costante (e non con una semplice uguaglianza).
5. Rifiuta l'evento se t si discosta di più di 300 secondi dall'ora attuale: è ciò che impedisce il replay di un vecchio invio.
6. Elimina i duplicati in base all'id dell'evento: è identico a ogni nuovo tentativo, quindi uno stesso evento può arrivarti due volte.

Estratti pronti da copiare in Node.js, PHP e Python si trovano nella sezione Documentation, parte «Vérifier la signature» (Verificare la firma). Rispondi con un codice 2xx il più in fretta possibile (entro 10 secondi) ed elabora l'evento dopo.

Nuovi tentativi, disattivazione e reinvio

Una risposta che non è 2xx, un tempo scaduto o un errore di rete conta come fallimento. SheepOS riprova fino a sei volte dopo il primo invio, dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore e poi 24 ore. Una consegna che fallisce ovunque passa allo stato «Abandonnée» (Abbandonata).

Dopo 15 fallimenti di fila, l'indirizzo viene disattivato automaticamente: un messaggio rosso ne indica il motivo nell'elenco. Correggi il tuo server, poi clicca su «Activer» (Attiva): il contatore dei fallimenti riparte da zero. Nel «Journal de livraison» (Registro di consegna), filtra per indirizzo o per stato e usa «Renvoyer» (Reinvia) su una consegna fallita o abbandonata.

Consultare il registro degli accessi

La sezione Journal d'accès elenca le richieste ricevute dall'API: chiave, metodo, rotta, stato, durata e data, con un filtro per chiave e per stato. Il registro viene conservato 30 giorni.

Limiti

• Al massimo 20 chiavi per negozio, 10 indirizzi di webhook.
• 120 richieste al minuto e per chiave per impostazione predefinita, regolabile da 10 a 1.200. Oltre, l'API risponde 429 con l'intestazione Retry-After: attendi quel numero di secondi.
• Al massimo 100 elementi per pagina.
• Il pagamento, il rimborso e le contestazioni non si gestiscono tramite l'API: restano nel back-office.
• I registri di accesso e di consegna vengono conservati 30 giorni.

Domande frequenti

Ho perso la mia chiave o il mio secret, come lo ritrovo?

Non è possibile: SheepOS non lo conserva in chiaro. Per una chiave, revocala e creane un'altra. Per un webhook, usa Nouveau secret.

Il mio strumento riceve un errore 401

La chiave è assente, copiata male, scaduta o revocata. Controlla il suo stato nell'elenco delle chiavi.

Il mio strumento riceve un errore 403

La chiave non ha il permesso richiesto dalla rotta. Modifica i permessi della chiave nella schermata, oppure usa un'altra chiave.

Non ricevo più eventi

Guarda prima se l'indirizzo è disattivato (messaggio rosso nell'elenco), poi il Journal de livraison: il codice e l'errore indicano cosa ha risposto il tuo server.