CursusOffice per Zapier: documentazione

Panoramica

CursusOffice è un gestionale per agenzie, professionisti e piccole imprese: clienti, preventivi, fatture, incassi e progetti in un solo posto, con la fatturazione elettronica per i Paesi supportati. Ogni cliente di CursusOffice ha il proprio spazio con un proprio indirizzo, per esempio tuaazienda.cursusoffice.com.

L'integrazione permette a uno spazio CursusOffice di scambiare dati con le altre app collegate a Zapier. Usa l'API REST pubblica di CursusOffice (JSON, solo HTTPS) e i webhook in uscita, gli stessi descritti in questa pagina.

Stato: l'app CursusOffice per Zapier è realizzata e provata ed è in preparazione per la directory di Zapier. Finché non è elencata puoi collegare CursusOffice con l'app «Webhooks by Zapier», come descritto nella pagina dell'integrazione.

Autenticazione

L'app usa l'autenticazione con chiave API. Quando colleghi l'account Zapier chiede due valori:

• Il tuo indirizzo CursusOffice: l'indirizzo del tuo spazio, senza https://, per esempio tuaazienda.cursusoffice.com.
• Token API: un token che inizia con co_.

1. In CursusOffice apri Gestione, poi API e webhook, poi la scheda Token API.
2. Crea un token e scegli solo i permessi che ti servono (vedi la tabella). Il token si mostra una sola volta: copialo subito.
3. In Zapier collega l'account CursusOffice e incolla indirizzo e token.

Ogni richiesta va a https://<il tuo indirizzo>/api/v1 con l'intestazione Authorization: Bearer <token>. In produzione HTTP non è accettato. Un token appartiene a un solo spazio, può avere una scadenza e si revoca in qualsiasi momento, con effetto dalla richiesta successiva. La prova di connessione è GET /api/v1/, che risponde 200 se indirizzo e token sono validi.

Trigger

Tutti i trigger sono istantanei (REST hook). Quando uno Zap si accende, Zapier registra il proprio indirizzo con POST /api/v1/webhooks; quando si spegne, toglie la sottoscrizione con DELETE /api/v1/webhooks/{id}. Un token vede e cancella solo le sottoscrizioni che ha creato.

Gli eventi vengono messi in coda quando l'azione avviene in CursusOffice e consegnati da un lavoro in background che gira ogni minuto: un trigger può impiegare fino a circa un minuto per arrivare a Zapier. Le consegne fallite si ritentano dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 12 ore. Ogni evento ha un identificativo unico (id nella busta), così i doppioni si possono ignorare.

I dati di un trigger sono l'oggetto stesso (la stessa forma dell'API). Gli importi sono stringhe decimali, date e ore sono in ISO 8601 con fuso orario, gli identificativi sono numeri interi.

Azioni

Le azioni creano dati in CursusOffice. Preventivi e fatture nascono sempre come bozze: numerazione, emissione e invio restano un passo deliberato di una persona dentro CursusOffice (le fatture hanno effetti fiscali). Totali e IVA li calcola sempre CursusOffice, mai Zapier.

«Righe come testo» permette a uno Zap di costruire le righe da un'altra app senza mappare i gruppi di righe. Scrivi una riga per ogni voce: descrizione | quantità | prezzo unitario (netto) | aliquota IVA | unità (facoltativa). L'aliquota IVA può essere una percentuale come 22, il codice di un'aliquota come elencato da GET /vat-rates, oppure # seguito dall'id dell'aliquota. Esempio:

Progetto sito web | 1 | 1200 | 22
Manutenzione mensile | 3 | 80 | 22 | mese

Gli elenchi Cliente e Aliquota IVA si riempiono dallo spazio (GET /customers e GET /vat-rates).

Ricerche

Errori e limiti

Gli errori tornano come JSON con un code stabile (in inglese), un message leggibile e, se serve, il nome del field. Il messaggio è scritto nella lingua dello spazio (italiano per uno spazio italiano); i messaggi aggiunti dall'app sono in inglese. L'app mostra messaggio e campo nella cronologia dello Zap:

La creazione dei record accetta l'intestazione Idempotency-Key: la stessa chiave con lo stesso corpo entro 24 ore restituisce la prima risposta invece di creare un secondo documento.

{ "error": { "code": "bad_parameter", "message": "Data non valida: usa il formato AAAA-MM-GG o AAAA-MM-GGTHH:MM:SS.", "field": "updated_since" } }

Come provare l'app

Uno spazio di prova, con un account amministratore, viene fornito nel modulo di pubblicazione di Zapier; le credenziali non sono mai pubblicate qui. Per vedere tutto in funzione:

1. Collega l'account con l'indirizzo dello spazio e un token API con tutti i permessi elencati sopra.
2. New Customer: crea un cliente nello spazio. New Product: crea un prodotto o servizio. New Project: crea un progetto. New Website Request: invia una richiesta di prova a uno dei moduli del sito dello spazio.
3. Invoice Issued: crea una fattura per un cliente ed emettila. New Payment: registra un incasso su quella fattura emessa. Quote Accepted: invia un preventivo a un cliente e accettalo dal link pubblico nell'email.
4. Azioni: Create Customer, Create Invoice Draft e Create Quote Draft creano record che vedi nelle pagine Clienti, Fatture e Preventivi. Fattura e preventivo restano bozze, senza numero.
5. Ricerche: Find Customer e Find Invoice restituiscono i record creati sopra.

I trigger sono consegnati da un lavoro in background che gira ogni minuto: se «Test trigger» non trova nulla subito dopo l'evento, attendi un minuto e riprova.

Endpoint dell'API usati dall'app

Indirizzo base: https://<il tuo indirizzo>/api/v1. Tutte le risposte sono JSON. Gli elenchi sono paginati con page e per_page (massimo 100) e accettano updated_since.