Autenticazione
Autenticazione con chiave API e limiti di frequenza
Autenticazione
Tutte le richieste all’API di Umbrella richiedono l’autenticazione. Esistono due metodi, a seconda dell’endpoint.
Autenticazione tramite header Shopify
Gli endpoint pubblici (dati dei widget, sinistri, ricerca delle polizze) si autenticano tramite gli header con il dominio del negozio Shopify:
X-Shopify-Shop-Domain: your-store.myshopify.com
X-Shopify-Customer-Id: 1234567890Quando installi l’app Shopify di Umbrella, il dominio del tuo negozio viene registrato automaticamente. Per gli endpoint del negozio online non serve alcuna configurazione manuale.
Autenticazione con chiave API interna
Gli endpoint lato server (valutazione dell’idoneità, sincronizzazione dei prodotti) si autenticano con una chiave API nel corpo della richiesta:
{
"internalApiKey": "your-internal-api-key",
"orgId": "your-org-id"
}Per generare o ruotare una chiave API interna:
- Vai su Dashboard > Impostazioni > Integrazioni
- Individua la sezione Chiavi API
- Fai clic su Genera nuova chiave o Ruota chiave
La rotazione di una chiave invalida immediatamente quella precedente. Aggiorna tutte le integrazioni prima di ruotarla.
Ambienti di test e live
| Ambiente | Dominio del negozio | Comportamento |
|---|---|---|
| Test | *.test, demo.myshopify.com, test.myshopify.com | Restituisce dati fittizi, nessuna transazione reale |
| Live | Il tuo dominio *.myshopify.com effettivo | Dati reali, transazioni reali |
Le richieste in modalità test restituiscono "testingMode": true nelle risposte e usano dati di garanzia di esempio.
Gestione degli errori
Codici di stato di errore comuni a tutti gli endpoint:
| Stato | Significato |
|---|---|
400 | Parametri mancanti o non validi |
401 | Nessuna credenziale di autenticazione fornita |
403 | Origine non autorizzata o chiave API non valida |
404 | Risorsa non trovata |
408 | Timeout della richiesta (limite di 25 secondi) |
429 | Limite di frequenza superato — attendi e riprova |
500 | Errore interno del server |
Quando ricevi una risposta 429, attendi il periodo indicato prima di inviare altre richieste. Per gli scenari ad alto volume, implementa un backoff esponenziale.
Correlati
- Panoramica degli endpoint — Elenco completo degli endpoint disponibili
- API delle garanzie — Endpoint per la gestione dei piani di garanzia
- Riferimento Webhook — Integrazioni basate sugli eventi
