Riferimento API v1

Panoramica

L’API di Manilo è un’API REST JSON per gestire in modo programmatico lo stesso registro che usi nell’app iOS: conti, categorie, budget, gruppi condivisi e transazioni. Usala per costruire importatori, esportatori, ponti di sincronizzazione, dashboard o per alimentare le tue automazioni.

• URL di base: https://api.manilo.app — l’URL di base precedente api.ledgy.app continua a funzionare.
• Prefisso di versione: tutti gli endpoint di questo documento sono esposti sotto /api/v1/.
• Trasporto: solo HTTPS. Le richieste HTTP non vengono accettate.
• Codifica: corpi di richiesta e risposta in JSON. UTF-8. Nomi delle proprietà in camelCase.
• Autenticazione: Authorization: Bearer … a ogni richiesta.
• Abbonamento Cloud: richiesto su ogni endpoint v1. Vedi Requisito di abbonamento.

Avvio rapido

Tre passaggi per arrivare alla tua prima richiesta autenticata.

1. Genera un Personal Access Token

1. Accedi alla tua dashboard Manilo e apri Impostazioni → Accesso API.
2. Fai clic su + Nuovo token.
3. Dai al token un nome descrittivo (ad es. “Zapier — esportazione settimanale”), scegli gli ambiti che ti servono (vedi Ambiti) e, se vuoi, imposta una scadenza.
4. Copia il token. Viene mostrato una sola volta. I token iniziano con il prefisso lgpat_ seguito da 64 caratteri esadecimali.

La stessa pagina elenca i tuoi token attivi con la data dell’ultimo utilizzo e il numero di permessi, mostra un avviso “In scadenza tra 30 giorni” e ti permette di revocare qualsiasi token all’istante tramite l’icona del cestino. Ogni account può avere fino a 25 token attivi contemporaneamente.

2. Esegui una richiesta

# Replace lgpat_… with your token
curl "https://api.manilo.app/api/v1/accounts" \
  -H "Authorization: Bearer lgpat_a1b2c3d4e5…"

3. Esamina la risposta

{
  "items": [
    {
      "id": "acc_01HK8V…",
      "name": "Wise EUR",
      "currencyCode": "EUR",
      "initialBalance": 1240.50,
      "icon": "wallet",
      "color": "#4A90E2",
      "order": 0,
      "createdAt": "2026-04-12T08:13:09Z",
      "updatedAt": "2026-05-01T17:02:31Z"
    }
  ],
  "totalCount": 1
}

Autenticazione

Ogni richiesta a /api/v1/ deve includere un’intestazione Authorization. Sono accettati due tipi di token:

• Personal Access Token (PAT) — token bearer di lunga durata che crei dalla pagina Impostazioni → Accesso API della dashboard. Formato: lgpat_ + 64 caratteri esadecimali. Con ambiti, revocabile, con scadenza facoltativa. Consigliato per tutte le integrazioni di terze parti.
• JWT di sessione — token di breve durata emesso per le app first-party (iOS, dashboard). Non ha restrizioni di ambito. Puoi usarlo per un test occasionale, se riesci a estrarne uno da una sessione autenticata, ma la strada supportata sono i PAT.

Formato dell’intestazione

Authorization: Bearer lgpat_a1b2c3d4e5f6…

Limiti dei token

• Fino a 25 PAT attivi per account Manilo.
• Al momento della creazione si può impostare una scadenza facoltativa. I token scaduti restituiscono 401 Unauthorized.
• I token revocati smettono di funzionare immediatamente: Manilo conserva solo un hash SHA-256 del token, mai il valore, quindi un token trapelato non può essere recuperato, ma solo revocato e sostituito.

Errori di autenticazione comuni

401

Token mancante, malformato, scaduto o revocato.

403

Il token è valido, ma l’endpoint richiesto esige un ambito che il tuo PAT non possiede, oppure il tuo abbonamento Cloud non è attivo.

Ambiti

I PAT seguono un modello deny-by-default (tutto negato salvo esplicita concessione). Un token può chiamare solo gli endpoint di cui possiede l’ambito richiesto; tutto il resto restituisce 403 Forbidden. Concedi l’insieme di ambiti più ristretto di cui la tua integrazione ha davvero bisogno.

Ambiti disponibili:

Ogni endpoint elencato di seguito mostra l’ambito richiesto in una piccola etichetta viola. Gli ambiti :write non implicano quelli :read: richiedili entrambi se ti servono entrambi.

Requisito di abbonamento

Tutti gli endpoint v1 — comprese le operazioni di sola lettura — richiedono che l’utente chiamante abbia un abbonamento Manilo Cloud attivo. Se l’abbonamento è decaduto, è scaduto o non è mai stato attivato, l’API risponde con:

HTTP/1.1 403 Forbidden
X-Subscription-Required: true
Content-Type: application/json

{ "error": "Active cloud subscription required" }

L’intestazione X-Subscription-Required permette ai client di distinguere un blocco dovuto all’abbonamento da un generico rifiuto per permessi insufficienti. Per ripristinare l’accesso, riattiva Cloud nell’app iOS oppure su dashboard.manilo.app/upgrade.

Errori

Gli errori usano i codici di stato HTTP standard. Il corpo della risposta è un oggetto JSON con un solo campo:

{ "error": "Human-readable message" }

Codici di stato da gestire:

200

OK — risorsa restituita, oppure elenco restituito.

201

Created — nuova risorsa creata. L’intestazione Location punta all’URL canonico.

204

No Content — eliminazione riuscita; nessun corpo.

400

Convalida non riuscita — campo obbligatorio mancante, valore fuori intervallo, JSON malformato.

401

Autenticazione non riuscita — vedi Autenticazione.

403

Permesso negato — ambito insufficiente o abbonamento non attivo.

404

Risorsa non trovata, oppure nascosta da un controllo di autorizzazione.

409

Conflict — ad es. violazione di un vincolo di unicità.

5xx

Errore lato server. È sicuro riprovare le letture idempotenti con backoff esponenziale.

Paginazione e filtri

Per impostazione predefinita, gli endpoint di elenco restituiscono tutti gli elementi corrispondenti. Le transazioni, l’unica risorsa che può diventare voluminosa, supportano la paginazione a cursore.

Cursore delle transazioni

curl "https://api.manilo.app/api/v1/transactions?limit=50&type=expense&dateFrom=2026-01-01" \
  -H "Authorization: Bearer lgpat_…"

La risposta include un nextCursor. Rimandalo indietro come parametro di query cursor per ottenere la pagina successiva; quando nextCursor è null, sei arrivato alla fine.

• limit — dimensione della pagina, limitata all’intervallo 1..200. Valore predefinito 50.
• cursor — token opaco. Trattalo come una scatola nera.
• type, dateFrom, dateTo, categoryId, accountId, groupId — filtri facoltativi; vedi l’endpoint Elenca transazioni.

Tipi e formati

• ID — stringhe opache. Non analizzarle; trattale come identificatori UTF-8 sensibili a maiuscole e minuscole.
• Timestamp — ISO-8601 in UTC con un carattere Z finale, ad es. "2026-05-13T10:30:00Z".
• Date (ad es. il campo date di una transazione) — stesso formato ISO-8601, ma è significativa solo la parte della data.
• Importi — numeri JSON espressi in unità principali con un massimo di 4 decimali (ad es. 12.50). Mai in unità secondarie. Sempre accompagnati da currencyCode.
• Codici valuta — ISO-4217, esattamente tre lettere maiuscole (ad es. "EUR", "USD", "GBP").
• Eliminazioni — tutte le operazioni di eliminazione sono eliminazioni logiche. Gli elementi eliminati smettono di comparire nelle risposte di elenco e di lettura; i partner di condivisione e gli scontrini storici vengono conservati.
• Effetti collaterali — eliminare un conto, una categoria o un gruppo lascia intatte le transazioni collegate; i loro riferimenti vengono staccati. L’endpoint Elimina conto accetta una strategia esplicita.

Conti

I conti sono i contenitori che custodiscono i saldi: un conto bancario, una carta di credito, un portafoglio in contanti, un conto di investimento. Ogni transazione è collegata a un conto (o a due, nel caso dei trasferimenti).

POST /api/v1/accounts
{
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E"
}

{
  "id": "acc_01HK8V…",
  "name": "Cash",
  "currencyCode": "EUR",
  "initialBalance": 50.00,
  "order": 2,
  "icon": "wallet",
  "color": "#22C55E",
  "iconColor": null,
  "shareInviteToken": null,
  "createdAt": "2026-05-13T10:30:00Z",
  "updatedAt": "2026-05-13T10:30:00Z"
}

Categorie

Le categorie indicano a cosa si riferisce una transazione (spesa alimentare, affitto, entrate da lavoro autonomo). Le categorie di sistema sono di sola lettura e condivise da tutti gli utenti; le categorie utente sono tue e le gestisci tu. I gruppi di categorie riuniscono categorie correlate.

Categorie utente

Gruppi di categorie

Budget

Un budget limita la spesa su una categoria (oppure, quando categoryId è null, sull’intero registro) in una finestra temporale ricorrente. Condividi un budget con un gruppo impostando groupId.

Gruppi

I gruppi sono registri condivisi: una famiglia, un viaggio, una casa condivisa. Ogni membro vede le stesse transazioni; la proprietà resta personale. Membri e inviti si gestiscono nell’app iOS; qui l’API espone la risorsa in sé.

Transazioni

Le transazioni sono i verbi del registro. Esistono in quattro forme: income, expense, transfer (da conto a conto) e adjustment (riallineamento una tantum). L’endpoint di base crea entrate e spese; i trasferimenti hanno un endpoint dedicato; per gli importatori ad alto volume esistono le varianti in blocco.

{
  "items": [ /* TransactionDto[] */ ],
  "totalCount": 317,
  "nextCursor": "eyJrIjoiMjAyNi0wNS0xM1QxMDoz…"
}

POST /api/v1/transactions
{
  "type": "expense",
  "amount": 8.50,
  "currencyCode": "EUR",
  "date": "2026-05-12T09:14:00Z",
  "accountId": "acc_01HK8V…",
  "categoryId": "cat_food_drinks",
  "payee": "Pret",
  "note": "Flat white"
}

Operazioni in blocco

Pensate per gli importatori. Ogni lotto è limitato a 100 elementi e viene eseguito in modalità best-effort: una singola riga errata non annulla le altre. Gli elementi riusciti e gli errori riga per riga vengono riportati separatamente, così puoi riprovare solo quelli non riusciti.

{
  "items": [ /* successful TransactionDto[] */ ],
  "errors": [
    { "index": 3, "error": "Invalid currency code" }
  ]
}

{
  "deleted": 97,
  "notFound": [ "tx_old1", "tx_old2", "tx_old3" ]
}

L’oggetto transazione

Icone

Manilo include un set di icone curato e una palette di colori usati ovunque: conti, categorie, gruppi. Recupera il catalogo una volta sola, mettilo in cache e riusa gli identificatori quando crei le risorse.

{
  "version": "2026.05.10",
  "library": "font-awesome-6",
  "categories": [
    {
      "id": "finance",
      "name": "Finance",
      "icons": [ "wallet", "credit-card", "piggy-bank" ]
    }
  ],
  "colors": [
    { "name": "Blue", "hex": "#4A90E2" },
    { "name": "Green", "hex": "#22C55E" }
  ]
}

Versionamento

• Nessuna modifica incompatibile all’interno di v1. Aggiungeremo soltanto nuovi endpoint, nuovi campi facoltativi e nuovi valori di enum. Il tipo di un campo, la sua nullabilità o la sua obbligatorietà non cambieranno.
• I nuovi valori di enum non sono modifiche incompatibili. Tratta i valori sconosciuti di type, source o action come “da non renderizzare” invece di andare in crash: li aggiungeremo man mano che il prodotto cresce.
• Le modifiche incompatibili datate (se mai fossero necessarie) verranno rilasciate sotto /api/v2/ con almeno 6 mesi di disponibilità in parallelo e un’intestazione di deprecazione sulle risposte v1.

Assistenza

Hai trovato un bug, ti serve un endpoint o ti sei imbattuto in qualcosa di non documentato? Apri il centro assistenza oppure scrivi a support@manilo.app — quando segnali un problema, includi l’id della richiesta (riportato nell’intestazione di risposta X-Request-Id).

Per segnalazioni sensibili sul piano della sicurezza (un token trapelato, un aggiramento dei permessi, una lettura non autorizzata) scrivi a security@manilo.app.