API

Olvano dispone di una REST API per connettere i tuoi sistemi — crea e leggi fatture, gestisci i contatti e ascolta gli eventi tramite webhook. Questa pagina ti porta da un token alla prima chiamata; l'elenco completo ed eseguibile degli endpoint è nel riferimento interattivo.

Prima di iniziare

Hai bisogno di due cose:

1. Un account con il piano byznys (il piano free non include l'API).
2. Un token API associato a quell'account (vedi sotto).

I token vengono creati dal proprietario dell'account. Un token appartiene esattamente a un account e ha le proprie autorizzazioni (scope), così puoi emettere un token separato per ogni integrazione.

Creare un token API

Nell'app vai in Impostazioni → Token API (/app/{slug}/settings/api-tokens), scegli Nuovo token, dagli un nome e seleziona i permessi. Il token in chiaro è mostrato una sola volta — copialo subito e conservalo al sicuro.

I token hanno il prefisso sg_. Viene conservato solo un digest HMAC, quindi il token non può più essere visualizzato — se lo perdi, creane uno nuovo ed elimina il vecchio.

Permessi (scope)

Per leggere (GET) le risorse comuni non serve uno scope; per scrivere sì. Le operazioni riservate al proprietario (gestione di token, webhook e conti bancari) non sono mai disponibili a un token API — anche uno emesso da un proprietario restituisce 403.

Autenticazione e URL di base

Autentifica ogni richiesta con il token nell'header Authorization:

Authorization: Bearer sg_your_token

L'URL di base è il dominio della tua istanza + /api. Gli endpoint per account hanno la forma /api/accounts/{slug}/…. Gli esempi seguenti usano variabili d'ambiente:

export STARGATE="https://app.stargate.app"   # replace with your instance domain (locally http://localhost:3000)
export SLUG="your-account-slug"
export TOKEN="sg_your_token"

La tua prima richiesta

Elenca le fatture di un account:

curl "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN"

La risposta è un elenco paginato:

{
  "invoices": [ { "id": "…", "number": "2026-0001", "status": "open", "total": "3630.00" } ],
  "total": 128,
  "page": 1,
  "pageSize": 40
}

Paginazione, ordinamento e ricerca

Gli endpoint di lista accettano questi parametri di query:

Le fatture possono essere filtrate anche per status, documentType e subjectId. Un parametro non valido non causa errori — viene usato il valore predefinito (es. ?page=abc → 1). Ogni risposta include total, page e pageSize, così il numero di pagine è facile da calcolare.

Creare una fattura

curl -X POST "$STARGATE/api/accounts/$SLUG/invoices" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "CUSTOMER_ID",
    "lines": [
      { "name": "Consulting", "quantity": 2, "unitPrice": "1500", "vatRate": 21 }
    ]
  }'

subjectId è l'ID del cliente — recuperalo dall'elenco contatti (GET /api/accounts/$SLUG/subjects) oppure creane uno con POST …/subjects. I campi obbligatori sono subjectId e almeno una voce in lines (ciascuna con name e unitPrice). Facoltativamente puoi inviare documentType, currency, variableSymbol, due, issuedOn e altro — schema completo nel riferimento interattivo.

In caso di successo la risposta è 201 con la fattura creata:

{ "invoice": { "id": "…", "number": "2026-0002", "status": "open", "total": "3630.00" } }

Errori

Gli errori condividono un envelope uniforme — uno status HTTP con JSON contenente statusMessage e un campo data per la gestione automatica:

{
  "statusCode": 400,
  "statusMessage": "Invalid invoice",
  "data": { "formErrors": [], "fieldErrors": { "subjectId": ["Required"] } }
}

Per gli errori di dominio, data.code è un codice machine-readable (es. subject_not_found) su cui fare affidamento più che sul testo del messaggio.

Limiti del piano

Il piano free non consente chiamate API (quota 0); il piano byznys include l'API e tutte le funzioni. Quando un limite viene superato (es. numero di contatti) l'API restituisce 402 con plan_limit_reached; per una funzione non inclusa nel piano (webhook, spese…) restituisce 403 con plan_feature_unavailable. Leggi i limiti e l'utilizzo corrente del tuo account con:

curl "$STARGATE/api/accounts/$SLUG/entitlements" -H "Authorization: Bearer $TOKEN"

Webhook

Un webhook ti notifica degli eventi in tempo reale, invece di interrogare l'API. I webhook sono una funzione del piano byznys e vengono gestiti dal proprietario dell'account.

Registra un webhook via API (o nelle impostazioni account):

curl -X POST "$STARGATE/api/accounts/$SLUG/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/hooks/stargate",
    "events": ["invoice_paid", "invoice_sent"],
    "authHeader": "Bearer your-shared-secret"
  }'

Inserisci nomi specifici in events, oppure * per tutti. Eventi disponibili:

invoice_created, invoice_sent, invoice_paid, invoice_overdue, invoice_cancelled, invoice_uncollectible, invoice_viewed, invoice_reminder_sent, recurring_generator_invoice_created.

Olvano invia un POST al tuo URL con il body:

{ "event_name": "invoice_paid", "body": { "…": "event data" } }

• Se imposti authHeader, viene inviato come header Authorization — usalo per verificare che la richiesta provenga davvero da Olvano.
• Ogni consegna include un header Idempotency-Key (UUID) — usalo per deduplicare.
• La consegna viene riprovata fino a 5× con backoff esponenziale finché non restituisci uno status 2xx. Le consegne fallite sono elencate tramite GET …/webhooks/{id}/failed_deliveries.

Riferimento interattivo

L'elenco completo e sempre aggiornato degli endpoint — con parametri, schemi e la possibilità di richiamarli direttamente dal browser:

• Apri il riferimento API (/api-docs)
• Schema OpenAPI machine-readable: /api/_openapi.json