API di Contabilità Remota

Accedi come admin, apri Impostazioni → 🔑 API di Contabilità Remota e clicca su "Genera token".

Il token in chiaro viene mostrato una sola volta — copialo subito. Il server memorizza solo l'hash SHA-256, quindi un token smarrito può essere sostituito solo ruotandolo (cosa che invalida quello vecchio).

Formato del token: bb_<userId>_<secret>. Invialo a ogni richiesta come Authorization: Bearer <token>.

Il corpo della richiesta è un oggetto JSON con questi campi:

• title (string, obbligatorio) — nome della transazione
• amount (number, obbligatorio) — deve essere positivo
• type (string, opzionale, default expense) — uno tra expense / income / prepaid_expense / pending_income
• category (string, opzionale) — nome della categoria
• note (string, opzionale) — nota libera
• created_at (string, opzionale) — ISO 8601; default ora

curl -X POST https://billbook.me/api/ingest \
  -H "Authorization: Bearer bb_<userId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Coffee","amount":120,"type":"expense","category":"Food"}'

# response: 201
{ "id": "...", "created_at": "..." }

Restituisce i nomi delle categorie dell'admin nell'ordine del menu a tendina della dashboard. La risposta contiene solo i nomi — niente id, user id o dati di transazione.

curl https://billbook.me/api/ingest/categories \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "categories": ["Food", "Rent", "..."] }

Restituisce i prefissi tag aggiornati di recente (i marcatori #XXX incorporati nei titoli). Default 20; usa ?limit= per modificare (max 100).

Restituisce un array vuoto invece di un errore se la tabella tag_prefixes non esiste ancora.

curl "https://billbook.me/api/ingest/tags?limit=20" \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "tags": ["#management-fee", "#travel", "..."] }

Tutti gli errori sono in JSON: { "error": "messaggio" }.

• 401 — autorizzazione mancante, token malformato, revocato o non corrispondente
• 402 — abbonamento scaduto; serve rinnovare per scrivere
• 405 — metodo non supportato (es. GET su /api/ingest)
• 501 — al server manca SUPABASE_SERVICE_ROLE_KEY
• 500 — altro errore interno

Per design il token può scrivere solo nella propria organizzazione — non può impersonare altre org né leggere dati esistenti:

• user_id è sempre il proprietario del token; non falsificabile
• org_id è sempre l'org del proprietario; le scritture cross-org sono impossibili
• I token sono emessi solo al ruolo admin (manager / staff ricevono 403)
• Le risposte non rivelano altre righe — viene restituito solo { id, created_at }
• La revoca è immediata; ruota in qualsiasi momento dalle Impostazioni

Aggiungi un'azione "Ottieni contenuto URL", URL https://billbook.me/api/ingest, metodo POST, header Authorization: Bearer bb_... e Content-Type: application/json, e corpo della richiesta in JSON: {"title":"Caffè","amount":120,"type":"expense"}. Collega title e amount all'input del Comando o a variabili "Chiedi ogni volta".