Per sviluppatori
Il sito parla con gli altri programmi. Con una chiave.
Il sito e il negozio hanno un'API aperta, con la sua documentazione: per il gestionale, la contabilità, il CRM e le automazioni. La chiave la crei dal pannello, in tre passi.
Documentazione in italiano · Contratto OpenAPI 3.1 · Una chiave per sito, con scadenza e indirizzi
A cosa serve. Far parlare il sito con altri programmi.
L'API serve a chi deve collegare il sito o il negozio a un altro programma: leggere e scrivere i dati senza copiarli a mano. Per usare il sito, invece, c'è il pannello.
Cosa colleghi. Senza copiare a mano.
Il gestionale
Articoli, prezzi e giacenze dal gestionale al negozio; ordini, clienti e rimborsi dal negozio al gestionale. Un connettore pronto per Mexal, BMAN o Zucchetti non c'è: il collegamento lo scrive il tuo tecnico con questa API, oppure Blagoweb, a preventivo.
La contabilità
Ordini, rimborsi, fatture e rapporti delle vendite, in sola lettura, per il commercialista o per il programma di contabilità. Con una chiave che non può cambiare niente.
Il CRM
Richieste, contatti, gruppi di persone ed etichette nel programma che usi già, con i consensi. L'email di un gruppo esce solo di chi ha detto sì a quel canale.
Le automazioni
Con n8n, Make e Zapier, senza scrivere codice: una richiesta nuova diventa una riga in un foglio, un ordine pagato parte per la spedizione.
Una chiave in tre passi. Dal pannello.
Passo 1: Apri le chiavi
Nel pannello del sito: Integrazioni, poi Per tecnici, poi Chiavi API. Lo vede solo chi gestisce le impostazioni.
Passo 2: Scegli cosa può fare
Parti da una scelta pronta (gestionale, contabilità, cruscotto, CRM, automazioni) e aggiungi o togli permessi. Se vuoi, metti una scadenza e gli indirizzi IP da cui vale.
Passo 3: Copia la chiave
Si vede una volta sola: nel nostro database resta solo la sua impronta. Provala con il comando qui sotto.
Permessi, scadenza e indirizzi. Una chiave fa solo quello che le dici.
Un permesso per ogni cosa
Leggere e scrivere sono permessi separati: chi legge gli ordini non li cambia. I prezzi e i rimborsi hanno un permesso loro, che non arriva con uno più largo.
Una chiave, un sito
Il sito si ricava dalla chiave, mai dall'indirizzo. Quello che è di un altro sito risponde «non trovato», come se non ci fosse.
Non più di chi la crea
Una chiave non può avere permessi che chi la crea non ha nel pannello.
Scadenza
Facoltativa. Per un consulente che lavora un mese: dopo il giorno scelto la chiave non vale più.
Indirizzi consentiti
Facoltativi. Dici da quali indirizzi IP vale la chiave: il server del gestionale, non il computer di chi l'ha vista.
Si revoca subito
Un clic nel pannello e la chiave smette di funzionare. Il registro delle chiamate dice cosa ha fatto.
Un primo comando. Per vedere che funziona.
Metti la chiave nell'intestazione e chiedi chi sei: la risposta dice il sito, i permessi della chiave, la scadenza e i limiti.
curl https://bdev.blagoweb.com/api/v1 -H "Authorization: Bearer pfk_…"
Se risponde, la chiave funziona. Il resto è nella documentazione.
Cosa leggi e cosa scrivi. Per gruppi.
Ogni gruppo ha i suoi permessi. Quello che non scrivi nella chiave, la chiave non lo fa.
Catalogo e magazzino
Prodotti, varianti, categorie, prezzi e giacenze, in lettura e in scrittura, anche a blocchi di 250. Ogni articolo porta il codice del tuo gestionale.
Ordini e clienti
Ordini, resi e clienti in lettura; spedito e tracking in scrittura; il rimborso con un permesso a parte. Solo per i negozi.
Fatture e IVA
Fatture, note di credito e il trattamento dell'IVA di ogni ordine, in lettura.
Vendita alle aziende
Aziende, listini per cliente, preventivi e condizioni di pagamento, con il modulo B2B acceso.
Richieste e contatti
Le richieste arrivate dal sito e la rubrica, in lettura e in scrittura, con i consensi di ogni persona.
Prenotazioni, menu e camere
Servizi e orari liberi, tavoli, camere e soggiorni, con i moduli accesi.
Le ultime aggiunte. Numeri, gruppi, etichette e campagne.
Quattro permessi nuovi, tutti di sola lettura, e la scelta pronta «Cruscotto» per averli insieme.
Numeri
Le schede di Numeri del pannello: visite, da dove arrivano, pagine, vendite e clienti, con le stesse definizioni.
Gruppi di persone
I gruppi, quante persone ci sono, chi si raggiunge per email e per WhatsApp, e le persone di un gruppo per portarle nel CRM.
Etichette
Le etichette automatiche e quelle a mano, e chi le ha. Accenderle resta nel pannello.
Campagne
Le campagne di email e WhatsApp con stato, report e a chi arrivano. Inviarle e programmarle resta nel pannello, di proposito: il consenso e il costo si guardano prima.
Euro e persone. Solo con il permesso.
Gli importi in euro escono solo se la chiave può leggere gli ordini: senza, il campo c'è e vale null, mai zero. Le persone escono solo con il permesso sui contatti o sui clienti. L'email e il telefono di una persona di un gruppo escono solo se ha dato il consenso al canale che chiedi. Sotto cinque persone un conteggio non si dice, se la chiave non vede insieme le persone e gli importi.
Webhook. Ti avvisiamo noi.
Invece di chiedere ogni minuto, iscrivi un indirizzo https e scegli gli eventi: un ordine pagato, una scorta che cambia, una fattura emessa, una richiesta nuova.
Firmati
Ogni messaggio porta una firma (HMAC-SHA256) da controllare con il segreto che ricevi una volta sola, quando iscrivi l'indirizzo.
Senza doppioni
L'id dell'evento è lo stesso a ogni tentativo: lo usi per non contare due volte la stessa cosa.
Con i tentativi
Se il tuo server non risponde, riproviamo a distanza di minuti e poi di ore. Ogni consegna si rimanda a mano dal pannello.
Limiti. Detti chiaramente.
Richieste al minuto
120 per chiave e 600 per sito. Oltre, la risposta è 429 con il tempo da aspettare. Ogni risposta dice quante ne restano.
Letture che non cambiano
Rimandi l'ETag che hai ricevuto: se non è cambiato niente, la risposta è 304 e non porta niente.
Scritture ripetibili
Ogni scrittura accetta una Idempotency-Key: la stessa richiesta ripetuta entro 24 ore riceve la stessa risposta, senza rifare niente.
Operazioni in blocco
Fino a 250 elementi per volta, ognuno con il suo esito: uno che non va non ferma gli altri.
Versioni. Niente si rompe da solo.
La versione è nell'indirizzo
Oggi è la v1. Dentro la v1 aggiungiamo campi e risorse: quello che c'è non si toglie e non cambia.
La data è in ogni risposta
L'intestazione X-Api-Revisione dice la data del contratto che sta rispondendo. Le novità sono scritte nel registro della documentazione.
Se una rotta va in pensione
Lo dice nelle intestazioni Deprecation e Sunset, con la data, e nella guida.
Dove leggere tutto. In italiano.
La documentazione
Una pagina sola: le regole, i casi (il gestionale, il cruscotto, il CRM), tutte le risorse con i loro permessi, gli errori e i webhook.
Il contratto OpenAPI
Per Postman, Insomnia, n8n o un generatore di client. Si genera dagli stessi schemi che controllano le richieste: non si stacca dal codice.
Le domande di chi la collega. Una per una.
Serve per usare il sito?
No. Il sito si gestisce dal pannello e dall'app. L'API serve a chi deve far parlare il sito con un altro programma.
Posso collegare Mexal, BMAN o Zucchetti?
Un connettore pronto non c'è. Con l'API il collegamento si scrive: lo fa il tuo tecnico, oppure Blagoweb, a preventivo.
Dall'API posso mandare una campagna?
No. Le campagne si leggono: stato, report e a chi arrivano. Si preparano, si programmano e si mandano dal pannello, dove consenso, anteprima e costo si guardano prima.
E se la chiave finisce in mani sbagliate?
La revochi dal pannello e smette di funzionare subito. Con una scadenza e gli indirizzi consentiti rischi meno: la chiave vale solo da dove e fino a quando serve.
Quanto costa?
Quello che comprende il tuo sito e quanto costa te lo scriviamo in una proposta, voce per voce. Un collegamento fatto da noi, se ti serve, sta nella stessa proposta.
A chi scrivo se qualcosa non va?
A info@blagoweb.com, oppure su WhatsApp, dal lunedì al venerdì, 9-18. Scrivi l'id della richiesta: è nell'intestazione X-Richiesta-Id di ogni risposta.
Hai un programma da collegare? Scrivici.
Ci dici quale programma usi e cosa deve passare da dove a dove. Ti diciamo se basta l'API o se serve un collegamento su misura.
Ti risponde una persona, entro 24 ore lavorative.