Sviluppatori

API e webhook

Ogni spazio CursusOffice espone un'API REST in JSON e invia webhook firmati quando qualcosa accade. Serve a collegare il tuo sito, un altro gestionale o uno strumento di automazione, restando sotto il tuo controllo.

Cosa puoi fare

Leggere clienti, prodotti, aliquote IVA, preventivi, fatture, incassi e progetti, con filtri e paginazione.

Creare e aggiornare clienti; creare BOZZE di preventivi e di fatture con gli stessi controlli dell'interfaccia.

Ricevere un avviso (webhook) per cliente creato o modificato, preventivi inviati e accettati, fatture emesse e consegnate, incassi, progetti e prodotti creati, richieste dal sito.

Sottoscrivere e annullare i webhook anche via API, per le automazioni che si registrano da sole.

Come funziona

Dal pannello Gestione → API e webhook crei un token con i permessi che ti servono: si mostra una sola volta e nel database resta solo l'impronta.
Chiami l'API con l'intestazione Authorization: Bearer e il token, sull'indirizzo del tuo spazio.
Per ricevere gli eventi aggiungi un indirizzo https: ogni consegna è firmata con un segreto che vedi una volta sola e si ritenta in caso di errore.

Esempio

curl https://<il-tuo-spazio>/api/v1/invoices?per_page=5 \
  -H "Authorization: Bearer co_..."

# Verifica della firma di un webhook (intestazione Cursus-Signature: t=<tempo>,v1=<firma>):
# firma = HMAC-SHA256( "<tempo>.<corpo ricevuto>", segreto del webhook )

Cosa serve

Un token API con i permessi giusti.
Per i webhook, un indirizzo https pubblico che risponde con un codice 2xx.

Limiti da sapere

Le API non emettono mai documenti: preventivi e fatture nascono bozze, l'emissione resta a una persona.
Fino a 120 richieste al minuto per token; importi sempre come stringhe decimali.
Nei POST usa l'intestazione Idempotency-Key per i ritentativi: la stessa chiave con lo stesso corpo entro 24 ore restituisce la risposta già data.
Webhook: consegna almeno una volta, senza garanzia d'ordine; fino a 6 tentativi (dopo 1 minuto, 5 minuti, 30 minuti, 2 ore, 12 ore); indirizzi di reti interne rifiutati.
Per ora l'accesso è con token personali con permessi: l'autorizzazione OAuth per applicazioni di terze parti non è ancora disponibile.

Domande frequenti

Dove trovo la documentazione completa?

Nel pannello Gestione → API e webhook e nella guida «API e webhook» dell'Aiuto di CursusOffice, con esempi, codici di errore e controllo della firma.

Quanto sono sicuri i token?

Hanno permessi limitati, una scadenza facoltativa e si revocano subito. Nel database resta solo l'impronta, non il token. Chi sbaglia il token ripetutamente viene rallentato.

Posso collegare il modulo di contatto del mio sito?

Sì, con la funzione «Richieste dal sito»: vedi la pagina dedicata.

Altre integrazioni

Tutte le integrazioni

Funzioni collegate

Integrazioni — Connettori, API e webhook per collegare i tuoi strumenti.

Provalo con CursusOffice

Prova gratis per 30 giorni: non serve la carta di credito per iniziare.

Prova gratis 30 giorni