API e webhook

Tramite l'API di allverto, shop, fornitori di servizi logistici, programmi di contabilità o software proprietari scambiano dati con allverto: articoli, giacenze, clienti, ordini, pagamenti, spedizioni, resi, canali di vendita, fatture e acquisti. I webhook comunicano subito le modifiche a un indirizzo a tua scelta – ad esempio «Ordine creato» o «Giacenza modificata».

Configuri tutto in Impostazioni → API e webhook. Lì trovi anche la Documentazione completa di tutti gli endpoint.

#Prima di iniziare

• Chiavi API e webhook sono gestiti dai ruoli con l'autorizzazione Gestire chiavi API e webhook – di norma Titolare e Amministrazione. Vedi Utenti e ruoli.
• Una chiave riceve al massimo le autorizzazioni che hai tu. Se in seguito perdi un'autorizzazione, la perde anche la chiave.
• Lo stesso vale per i webhook: puoi abbonarti solo a eventi i cui dati puoi leggere tu stesso – ad esempio «Cliente modificato» solo con «Visualizzare clienti», «Fattura creata» solo con «Visualizzare documenti». allverto nasconde gli eventi senza il permesso corrispondente.

#Creare una chiave API

1. Apri Impostazioni → API e webhook, scheda Chiavi API.
2. Fai clic su Crea chiave.
3. Inserisci un Nome da cui riconosci il sistema esterno (ad es. «Connessione Shopify»).
4. Scegli le Autorizzazioni, ad es. «Leggere ordini» e «Importare ordini». Prendi solo ciò di cui il sistema esterno ha davvero bisogno.
5. Facoltativo: limita la chiave a un'Azienda (così vede e scrive solo ordini e documenti di quell'azienda), imposta una Data di scadenza e il Limite di richieste al minuto.
6. Fai clic su Crea chiave. allverto mostra la chiave (av_…) una sola volta – copiala con Copia e inseriscila nel sistema esterno.

Nel menu della riga puoi usare Copia prefisso (così ritrovi la chiave nel sistema esterno) e revocare la chiave in qualsiasi momento. Da quel momento l'API la rifiuta immediatamente. Nell'elenco vedi quando una chiave è stata usata l'ultima volta (Ultimo utilizzo) e da quale indirizzo IP.

#Richieste all'API

Ogni richiesta porta la chiave nell'header Authorization: Bearer av_…. Gli endpoint si trovano sotto /api/v1, ad esempio:

curl https://deine-firma.allverto.cloud/api/v1/orders?status=paid \
  -H "Authorization: Bearer av_…"

• Gli elenchi restituiscono { data, page: { nextCursor, hasMore } }. La pagina successiva la ottieni con cursor=<nextCursor>. Con updatedSince=2026-10-01T00:00:00Z arrivano solo le voci create o modificate da quel momento – ideale per sincronizzazioni regolari.
• Gli errori hanno sempre la forma { error, message, fields } con lo stato HTTP appropriato (400 input, 401 chiave, 403 autorizzazione mancante, 404 non trovato, 409 conflitto, 429 limite).
• Idempotenza: nelle richieste POST invia un header univoco Idempotency-Key. Se ripeti la richiesta (ad es. dopo un errore di rete), allverto non registra nulla due volte, ma restituisce la stessa risposta per 24 ore.
• Limite di richieste: lo standard è 120 richieste al minuto per chiave. Se viene superato, l'API risponde con 429 e Retry-After (secondi).
• Resi e canali di vendita: GET /api/v1/returns e /returns/{id} restituiscono i resi con righe, motivi e rimborso (permesso «Leggere resi»), GET /api/v1/channels i canali di vendita – la controparte di channelId in ordini e resi.

Le modifiche tramite API compaiono nel Registro modifiche come «API: nome della chiave».

#Configurare i webhook

1. Scheda Webhook, fai clic su Aggiungi webhook.
2. Inserisci nome e Indirizzo (https://…) del destinatario e scegli gli Eventi, ad es. «Ordine creato», «Pagamento ricevuto», «Giacenza modificata». Con più aziende puoi limitare il webhook a un'azienda: ordini, documenti, resi e ordini d'acquisto di altre aziende non vengono inviati a questo indirizzo.
3. Fai clic su Salva. allverto mostra il secret per verificare la firma – anche questo una sola volta.
4. Con Invia test verifichi la connessione. Il risultato compare nel Registro consegne.
5. I nuovi webhook sono inattivi. Solo con Attiva allverto invia eventi reali – come per tutte le sincronizzazioni.

Gli eventi nascono nella stessa transazione della modifica: se una registrazione viene annullata, non parte nemmeno alcun webhook. Il contenuto (data) ha lo stesso formato dell'API (ad es. GET /api/v1/orders/{id}, per i resi GET /api/v1/returns/{id}).

A ogni consegna allverto verifica i permessi attuali della persona che ha creato o modificato per ultima il webhook. Se le manca il permesso di lettura per un evento o non ha più un accesso attivo, non viene inviato alcun contenuto; il registro consegne mostra la consegna come non riuscita con il motivo. Chi salva il webhook in seguito diventa la persona responsabile.

#Verificare la firma

Ogni chiamata porta l'header allverto-signature: t=<Unix-Zeit>,v1=<Signatur>. La firma è un HMAC-SHA256 con il secret calcolato su t + "." + Body. Verificala sul body non modificato e scarta le chiamate il cui orario si discosta di più di 5 minuti.

#Consegne non riuscite

Se il destinatario non risponde con 2xx, allverto riprova – dopo 1 minuto, 5 minuti, 30 minuti, 2, 6, 12 e 24 ore. Dopo 20 errori consecutivi il webhook viene disattivato automaticamente e ricevi una notifica. Nel Registro consegne (periodo predefinito «Ultimi 30 giorni») vedi stato, codice di risposta e durata di ogni consegna e puoi inviarla di nuovo.

I webhook possono chiamare solo indirizzi pubblici – destinazioni interne come localhost o reti private sono bloccate.