Famiglie
La famiglia è il tenant: conti, movimenti, budget, categorie, regole e chiavi appartengono tutti a una sola. Anche la tua chiave: ecco cosa ti permette di fare, e cosa no.
Un tenant, una famiglia
Ogni risorsa finanziaria dell'API vive dentro una famiglia e si raggiunge sotto /households/:householdId/…. Una persona può appartenere a più famiglie con un ruolo diverso in ciascuna (proprietario, editor o visualizzatore): è così che una casa condivisa, la famiglia vera e propria e una piccola attività restano separate dentro un unico account.
Le famiglie non condividono mai dati. Non esiste lettura da una famiglia all'altra, non c'è una lista di categorie comune e non c'è nessuna operazione di copia da un'altra famiglia. L'unica cosa che le attraversa è la persona.
La tua chiave è legata a una sola famiglia
Una chiave nasce dentro una famiglia e può agire soltanto su quella; una richiesta rivolta a un'altra famiglia riceve 403, a prescindere da cosa raggiunge il suo proprietario nell'app. Non devi conoscere l'id: il segmento letterale current punta sempre alla famiglia della chiave.
curl -H "Authorization: Bearer vokse_sk_…" \ https://api.vokse.ai/households/current# every scoped route takes the alias in place of the idcurl -H "Authorization: Bearer vokse_sk_…" \ "https://api.vokse.ai/households/current/transactions?limit=50"Cosa non può fare una chiave
Il ciclo di vita della famiglia e la gestione dei membri sono riservati alla sessione: una persona che ha fatto l'accesso nell'app, mai una chiave API. Queste rotte rispondono 403 API_KEY_NOT_ALLOWED:
- POST /households: creare una famiglia
- GET /households: elencare le famiglie a cui appartieni
- DELETE /households/{householdId}: eliminare una famiglia
- Inviti: inviare, accettare e revocare
- Membri: elencare, cambiare ruolo, rimuovere, uscire
- Trasferire la proprietà e riportare all'onboarding
Il motivo è limitare i danni: una chiave trafugata preoccupa già abbastanza dentro una famiglia sola, senza che possa anche crearne di nuove o elencare tutte quelle a cui appartiene il suo proprietario. GET /households/current è l'eccezione e richiede read:households: è così che un'integrazione scopre dove si trova.
{ "error": { "code": "API_KEY_NOT_ALLOWED", "message": "This endpoint is not available to API keys." }}Limiti di proprietà
Puoi appartenere a quante famiglie vuoi, ma puoi essere proprietario solo di un numero limitato: 2 sul piano gratuito e 10 su Pro. Crearne una oltre il tetto (dall'app, visto che la creazione è riservata alla sessione) restituisce 409. Ti serve un limite più alto? Scrivici e lo alziamo sul tuo piano.
{ "error": { "code": "HOUSEHOLD_LIMIT_REACHED", "message": "You already own 2 households, the maximum for your plan.", "details": { "limit": 2, "owned": 2 } }}Far partire una famiglia
Una famiglia nuova nasce vuota, con una lingua dei dati (`locale`, di default quella dell'interfaccia di chi la crea). GET /meta/category-packs?locale=&dataLocale= elenca i pacchetti iniziali con i gruppi e le categorie esatte che ognuno crea (etichette in `locale`, nomi in `dataLocale`), e POST /households/:householdId/starter-pack ne applica uno con write:categories nella lingua dei dati della famiglia. L'applicazione è idempotente per nome, quindi un nuovo tentativo non duplica mai la struttura.