L'API pubblica di Bill Alps espone, in REST, ciò che l'applicazione fa a schermo: clienti, fatture, preventivi, dipendenti, buste paga, spese e contabilità. Questa guida vi porta da zero a una prima chiamata riuscita, nella sandbox, senza toccare i dati di produzione.
BASE=https://<deployment>.convex.site/api/v1
KEY=ba_...1. Cosa copre l'API
L'API v1 gira sullo stesso codice dell'applicazione: ogni rotta richiama la logica di business dell'app, con gli stessi controlli, le stesse quote e gli stessi PDF. Ciò che viene rifiutato a schermo viene rifiutato anche dall'API.
- Account e società:
/me,/companies(profilo e logo della società),/mandatesper le fiduciarie. - Fatturazione: clienti (singoli o in lotto), catalogo prodotti ed elenchi di prodotti, modelli di fattura, fatture, preventivi, fatture ricorrenti, con i loro PDF e l'invio per e-mail.
- Paghe: dipendenti, assenze, buste paga (creazione singola o in lotto, convalida, invio, correzione, duplicazione, PDF in lotto), giorni festivi e anteprime, stato dei link dell'area dipendente.
- Spese e banca: spese e giustificativi, bozze ed estrazione con l'IA, transazioni bancarie importate.
Il contratto pubblica anche le rotte del libro mastro, dell'IVA e del conto annuale, ma in produzione rispondono 403 LEDGER_DISABLED.
Le rotte indirizzate a una società (/companies/{companyId}/…) richiedono che la società sia sul piano Business e che il modulo interessato (fatturazione, paghe o contabilità) sia attivato in Il mio accountModuli. Se il tuo abbonamento Business non copre un modulo attivato, le sue rotte rispondono comunque, ma con i limiti del piano Starter. Le chiavi sono credenziali server-to-server: gli endpoint non hanno CORS, di proposito, quindi mai una chiave in un browser o in un'app mobile.
2. Iniziare nella sandbox
Nella sandbox ogni società è considerata Business, qualunque sia il suo piano reale, il che apre tutte le rotte anche a un account Starter. Le e-mail non partono, Stripe non addebita nulla, gli inviti al team non vengono inviati. Tutto il resto funziona, compresi i job pianificati: è il posto ideale per costruire e testare un'integrazione.
Due differenze rispetto alla produzione. Nella sandbox il libro mastro è aperto, quindi le sue rotte non rispondono 403 LEDGER_DISABLED; il piano dei conti e le registrazioni, però, non vengono copiati: per usarli devi attivare la contabilità nella sandbox. E in un ambiente vuoto la società creata conserva le quote del piano Starter, anche se tutte le rotte rispondono.
3. Creare una chiave
- Crea la chiave da una qualsiasi società Business che amministri: la società serve solo ad autorizzare la creazione, la chiave è personale e non è legata ad alcuna società.
- Serve il ruolo proprietario o admin sulla società attiva, e questa deve essere su Business (nella sandbox lo è sempre).
- Una chiave appartiene alla persona che l'ha creata, non alla società: agisce su tutte le società a cui quella persona ha accesso, con i suoi permessi. Fino a 10 chiavi attive per utente.
- Il campo Scadenza è impostato su Nessuna scadenza per impostazione predefinita. Una chiave scaduta risponde
401 INVALID_API_KEY, come una chiave revocata. - Per ruotare una chiave: creane una seconda, migra l'integrazione, poi revoca la prima dalla stessa schermata.
4. URL di base e header
L'API non vive sull'host dell'applicazione ma su un indirizzo in .convex.site, proprio di ogni ambiente. Il pannello Chiavi API non lo mostra in chiaro: il suo link Swagger API apre https://<deployment>.convex.site/api/docs, e l'URL di base è la stessa origine seguita da /api/v1. Il pannello della sandbox punta alla sandbox, quello della produzione alla produzione; le chiavi non sono intercambiabili tra i due ambienti, una chiave della sandbox è sconosciuta alla produzione.
Ogni richiesta porta la chiave nell'header Authorization:
Authorization: Bearer ba_...5. Prima chiamata
La prima chiamata da fare è GET /me: ti dice chi possiede la chiave e su cosa può agire.
curl -H "Authorization: Bearer $KEY" $BASE/meLa risposta contiene data.companies[], ogni società con il suo id, il tuo role, il suo plan effettivo e i suoi modules. Questi id sono quelli che prendono tutte le rotte /companies/{companyId}/…. La stessa lista esiste come array semplice:
curl -H "Authorization: Bearer $KEY" $BASE/companiesUna società sul piano Starter o Team (plan vale free o team) compare nella lista, ma le sue rotte rispondono 403 PLAN_NOT_ALLOWED. Scegli una società con il modulo che ti interessa attivo e puoi passare alle guide successive.
6. Documentazione interattiva
Ogni deployment si descrive da solo. Su https://<deployment>.convex.site/api/docs, una Swagger UI mostra il contratto in vigore: clicca Authorize, incolla una chiave ba_, poi «Try it out» su qualsiasi rotta. La chiave resta nello storage locale del browser fino al Logout, quindi preferisci una chiave revocabile e la sandbox.
Il documento OpenAPI 3.1 è servito su https://<deployment>.convex.site/api/v1/openapi.json, pubblico, senza chiave, con CORS aperto. Viene generato su richiesta a partire dalla tabella delle rotte e dagli schemi di richiesta e di risposta: ciò che descrive è esattamente ciò che l'API applica. servers[0].url riprende l'origine da cui l'hai scaricato, seguita da /api/v1, quindi produzione e sandbox puntano ciascuna a sé stessa. Incolla l'URL in editor.swagger.io per sfogliarlo, oppure usalo per generare un client.
Nella sandbox il pannello Il mio accountChiavi API offre anche un link Documentazione DEV allo schema dei dati dell'applicazione (diagramma entità-relazioni), utile per capire come le risorse sono collegate tra loro.
Il seguito si legge nell'ordine che preferisci: fatturare con l'API, paghe, spese e contabilità con l'API, ciclo paghe con l'API e, per le regole trasversali, convenzioni ed errori. La Swagger UI del tuo deployment resta il riferimento per ogni campo.