Torna alla guida

Iniziare con l'API Bill Alps

Cosa copre l'API REST v1, come ottenere una chiave senza rischi nel sandbox, e la prima chiamata che vi dice su quali società potete agire.

Sviluppatori6 min di lettura
Indice+

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, nel 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 chiama la logica di business dell'app, con gli stessi controlli, le stesse quote e gli stessi PDF. Ciò che viene rifiutato a schermo è rifiutato dall'API, e viceversa.

  • Account e società: /me, /companies, /mandates per i fiduciari.
  • Fatturazione: clienti, modelli di fattura, fatture, preventivi, fatture ricorrenti, con i loro PDF e l'invio per e-mail.
  • Paghe: dipendenti, buste paga (singole e in lotto), assenze.
  • Spese e contabilità: spese fornitori, transazioni bancarie importate, rendiconto finanziario annuale.

Le rotte indirizzate a una società (/companies/{companyId}/…) richiedono che quella società sia sul piano Business e che il modulo interessato (fatturazione, paghe, spese, rendiconti) sia attivo. 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 nel sandbox

Nel sandbox ogni società è vista come Business qualunque sia il piano reale, il che apre tutte le rotte anche a un account Free. 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 giusto per costruire e testare un'integrazione.

3. Creare una chiave

  • Create la chiave da una qualsiasi società Business che amministrate — la società serve solo ad autorizzare la creazione; la chiave è personale e non porta alcuna società.
  • Serve il ruolo proprietario o admin sulla società attiva, e questa deve essere su Business (nel 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.
  • Per ruotare una chiave: createne una seconda, migrate l'integrazione, poi revocate la prima dalla stessa schermata.

4. URL di base e header

L'API non vive sull'host dell'applicazione ma sul deployment Convex che la serve: un indirizzo in .convex.site, mostrato nel pannello Chiavi API subito sotto le vostre chiavi. Il pannello del sandbox mostra l'indirizzo del sandbox, quello di produzione l'indirizzo di produzione; le chiavi non sono intercambiabili, una chiave del 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: vi dice chi possiede la chiave e su cosa può agire.

curl -H "Authorization: Bearer $KEY" $BASE/me

La risposta contiene data.companies[], ogni società con il suo id, il vostro 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/companies

Una società su Free o Team appare nella lista, ma le sue rotte rispondono 403 PLAN_NOT_ALLOWED. Scegliete una società con il modulo che vi interessa attivo, e siete pronti per le 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: cliccate Authorize, incollate una chiave ba_, poi «Try it out» su qualsiasi rotta. La chiave resta nello storage locale del browser fino al Logout, quindi preferite una chiave revocabile e il sandbox.

Il documento OpenAPI 3.1 è servito su https://<deployment>.convex.site/api/v1/openapi.json, pubblico, senza chiave, con CORS aperto. È generato su richiesta dalla tabella delle rotte e dagli schemi di richiesta e risposta: ciò che descrive è esattamente ciò che l'API applica. servers[0].url vale l'origine da cui l'avete scaricato, quindi produzione e sandbox puntano ciascuno a sé stesso. Incollate l'URL in editor.swagger.io per sfogliarlo, o usatelo per generare un client.

Nel sandbox, il pannello AccountChiavi API offre anche un link «Documentation DEV» verso il modello dati dell'applicazione (diagramma entità-relazioni), utile per capire come le risorse si legano tra loro.

Il resto si legge nell'ordine che preferite: fatturare con l'API, paghe, spese e contabilità con l'API e, per le regole trasversali, convenzioni ed errori. La Swagger UI del vostro deployment resta il riferimento per ogni campo.