ConnectWiz + API e webhook
Integrazione attivaL’API che vendiamo è l’API che usiamo
L’intera piattaforma è specificata in un solo contratto OpenAPI, quello da cui vengono generati il nostro pannello e la nostra app mobile: nessun endpoint fantasma, nessuna documentazione che si allontana dal codice. Sopra ci stanno le chiavi della Commerce API con i loro scope, i trigger webhook protetti e i flussi che chiamano i vostri sistemi.
Sviluppatori
Che cosa fa, esattamente
Un solo contratto di riferimento
Un unico documento OpenAPI 3 specifica la piattaforma; i nostri client TypeScript si generano da lì: la documentazione non può allontanarsi dalla realtà, perché è dalla documentazione che la realtà viene costruita.
Chiavi della Commerce API
Chiavi emesse dal tenant con scope espliciti — lettura catalogo, lettura ordini, scrittura ordini — fanno funzionare la vostra vetrina o la vostra app sullo stesso motore degli ordini, con i prezzi sempre risolti lato server.
Webhook in entrata, protetti
Ogni trigger webhook di un flusso ha il proprio URL e il proprio secret, la verifica HMAC sul corpo grezzo e la protezione dai replay. Un payload può nominare una persona; non può in nessun caso guidare il funzionamento interno del flusso.
In uscita, attraverso i flussi
Lo step REST chiama i vostri sistemi esattamente nei momenti che disegnate sul canvas: ordine inserito, consenso concesso, prenotazione fatta.
Il lato tecnico
Le scelte di progetto dell’API, dichiarate
I prezzi non arrivano mai dal client
Una richiesta d’ordine dice che cosa e quanti: nome e prezzo vengono letti dal catalogo in quel momento, lato server, e scritti sulla riga come istantanea. Una richiesta manomessa non può inventarsi uno sconto.
Prima le capacità, poi le chiamate
Ogni punto di integrazione pubblica un contratto di capacità — sa riconoscere un cliente dal telefono, elencare gli ordini degli ospiti, creare ordini? — e una chiamata che va oltre un «no» dichiarato solleva subito un errore, invece di fallire da qualche parte in fondo.
Errori che vogliono dire qualcosa
Il livello di trasporto distingue «non autorizzato» da «servizio non attivo», così «il negozio è irraggiungibile» non diventa mai «questo cliente non ha mai comprato nulla». Gli errori con un nome sono la differenza tra un’API e un gioco a indovinare.
Webhook a prova di replay
Ogni evento in arrivo rivendica una chiave univoca in un registro di idempotency prima di essere elaborato: una consegna ritentata o riprodotta muore a livello di database, non dentro la vostra automazione.
Chiavi in hash, secret con uno scope
Le chiavi API sono conservate come hash, e alla porta si possono risolvere solo l’hash e gli scope: una riga di database che trapela non nomina nessun workspace e non apre nulla oltre i propri scope.
Bozze e conferme sono esplicite
La creazione di un ordine accetta un parametro di conferma esplicito — l’API pubblica lo considera confermato per impostazione predefinita, i flussi del pannello possono preparare delle bozze — così «questo è vero?» è un campo, non una convenzione.
Configurazione
Come si collega
Emettere una chiave
Create nel pannello una chiave della Commerce API con i suoi scope; revocarla è altrettanto semplice.
Collegare un webhook
Create un flusso con un trigger webhook e firmate le richieste con il suo secret.
Richiamare verso l’esterno
Aggiungete step REST dove i vostri sistemi devono venirlo a sapere.
Meglio insieme
Con che cosa si combina
Flows
I trigger webhook avviano i flussi; gli step REST richiamano i vostri sistemi nei momenti che disegnate voi: l’automazione in entrata e quella in uscita condividono un solo canvas.
Commerce
Il catalogo e il motore degli ordini dietro l’API sono gli stessi che usano il negozio in chat e l’AI: una sola verità sugli ordini, quattro porte.
La vostra vetrina
Oggi ci sono team che fanno girare vetrine headless sulla Commerce API: è la strada che la pagina Shopify consiglia senza giri di parole mentre il connettore nativo viene costruito.
Sicurezza e garanzie
Le garanzie noiose
HMAC sul corpo grezzo
La verifica del webhook firma il corpo grezzo della richiesta con un secret specifico del trigger e confronta in tempo costante: il parsing avviene solo dopo la prova.
I payload sono dati, mai comandi
Il payload di un webhook può fare riferimento a una persona; non può in nessun caso guidare il funzionamento interno di un flusso, riscrivere i prompt o invocare strumenti. Il confine tra dati e istruzioni è architetturale, non comportamentale.
Limiti di frequenza su ogni porta
Gli endpoint pubblici passano dal throttling standard, e i limiti di lettura sono ridotti lato server: un client che si comporta male peggiora la propria esperienza, non la piattaforma.
Le clausole, senza giri di parole
I limiti, messi per iscritto
Nessun flusso continuo, per ora
Un feed webhook generico a cui iscriversi per ricevere tutto non esiste: oggi gli eventi in uscita passano dagli step dei flussi. Lo scriviamo qui, così nessuna telefonata di vendita deve lasciar intendere altro.
Letture limitate, di progetto
Le letture restituiscono fino a 100 righe con il cursore: l’API è fatta per l’integrazione operativa, non per l’esportazione massiva. Se servono grandi volumi se ne parla, non si cerca una scappatoia.
Meglio un’integrazione onesta che un’integrazione rumorosa.
Ogni integrazione di questa pagina è descritta per quello che fa davvero: direzione della sincronizzazione, proprietà dei dati e limiti compresi.