API di BillMate

L’API di BillMate è gratuita e permette a un client o a uno script tuo di leggere e gestire i tuoi gruppi, le spese e i pagamenti. Ogni utente genera le proprie chiavi dal profilo.

Per iniziare

Accedi a BillMate, apri Profilo → Chiavi API e crea una chiave (sola lettura o lettura e scrittura). Copiala subito: non verrà più mostrata.

Invia la chiave nell’header Authorization di ogni richiesta:

curl 'https://billmate.it/api/me' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Le risposte sono JSON. Gli importi sono interi in unità minori (centesimi).

Chiavi e permessi

Ogni chiave agisce a nome dell’utente che l’ha creata e vede solo i dati a cui lui ha accesso.
Sola lettura: solo richieste GET. Lettura e scrittura: anche creazione, modifica ed eliminazione.
Puoi avere fino a 10 chiavi attive, con scadenza facoltativa (da 1 giorno a 2 anni). Revoca una chiave dal profilo: smette di funzionare subito.
Il server conserva solo l’impronta (hash) della chiave: se la perdi, creane un’altra.
Tratta la chiave come una password: non inserirla in app pubbliche, repository o pagine web. Se pensi sia trapelata, revocala.

Non disponibile con le chiavi

Per sicurezza le chiavi non possono gestire altre chiavi, sessioni, metodi di pagamento cifrati, inviti, eliminazione dell’account né l’area admin. Gli endpoint non elencati qui rispondono 403 API_KEY_FORBIDDEN.

Convenzioni

Importi: interi in unità minori (4000 = 40,00 €). Un valore positivo nei saldi significa «ti devono», negativo «devi».
Id: UUID. Date di calendario: AAAA-MM-GG. Istanti: ISO 8601 in UTC.
Il corpo delle richieste è JSON con Content-Type: application/json, massimo 1 MB.
Spese e pagamenti sono sempre registrati: BillMate non sposta denaro.
CORS: le chiavi API possono essere usate anche da client web in altri domini.

Limiti di utilizzo

Fino a 240 richieste al minuto per utente, di cui al massimo 90 scritture. Oltre il limite la risposta è 429 con l’header Retry-After. L’uso è gratuito e senza quote giornaliere.

Errori

Gli errori hanno uno status HTTP e un corpo JSON {"error": {"code": "…", "details": …}}.

HTTP	code	Descrizione
401	UNAUTHORIZED	Chiave mancante, non valida, scaduta o revocata.
403	API_KEY_READ_ONLY	La chiave è di sola lettura e la richiesta scrive.
403	API_KEY_FORBIDDEN	Endpoint non disponibile con le chiavi API.
403	FORBIDDEN	L’utente non ha i permessi per l’azione (es. modificare la spesa di un altro).
403	LEGAL_REQUIRED	L’utente deve accettare i documenti aggiornati dall’app.
404	NOT_FOUND	Risorsa inesistente o non visibile all’utente.
409	CONFLICT	Conflitto di stato (es. `expectedVersion` non aggiornata).
422	VALIDATION	Dati non validi: `details.fields` indica i campi.
429	RATE_LIMITED	Troppe richieste: attendi `details.retryAfterSec` secondi.

Endpoint

Account e dati di riferimento

GET`/api/me`Permesso: sola lettura

Profilo dell’utente della chiave

Esempio

curl -X GET 'https://billmate.it/api/me' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "id": "47542df6-597a-45b4-ab18-816c4b538265",
  "name": "Anna",
  "email": "anna@example.com",
  "avatarUrl": null,
  "locale": "it",
  "defaultCurrency": "EUR",
  "onboarded": true,
  "createdAt": "2026-10-21T15:11:20.346Z"
}

GET`/api/meta`Permesso: sola lettura

Valute abilitate, categorie e limiti

Dati di riferimento per creare spese: valute (con decimali), categorie di piattaforma e del gruppo, e il tasso suggerito tra due valute.

Parametri

Campo	Tipo	Descrizione
groupId query	string (uuid)	Include anche le categorie personalizzate di questo gruppo.
from query	string	Valuta di partenza per il tasso suggerito.max 3
to query	string	Valuta di arrivo per il tasso suggerito.max 3

Esempio

curl -X GET 'https://billmate.it/api/meta' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "currencies": [
    {
      "code": "EUR",
      "name": "Euro",
      "symbol": "€",
      "decimals": 2,
      "enabled": true
    }
  ],
  "categories": [
    {
      "id": "c1…",
      "key": "food",
      "name": null,
      "labels": {
        "it": "Cibo",
        "en": "Food"
      },
      "icon": "utensils",
      "color": "#c2410c"
    }
  ],
  "rate": null
}

GET`/api/dashboard`Permesso: sola lettura

Riepilogo: totali, gruppi, amici e attività recente

Esempio

curl -X GET 'https://billmate.it/api/dashboard' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "totals": [
    {
      "currency": "EUR",
      "owedToYou": 1500,
      "youOwe": 0,
      "net": 1500
    }
  ],
  "groups": [
    "…"
  ],
  "friends": [
    "…"
  ],
  "friendCount": 1,
  "incomingRequests": 0,
  "activity": [
    "…"
  ],
  "unread": 0
}

GET`/api/balances`Permesso: sola lettura

Saldi totali, per amico e per gruppo

Importi in unità minori. Un valore positivo significa che ti devono dei soldi, negativo che ne devi tu.

Esempio

curl -X GET 'https://billmate.it/api/balances' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "totals": [
    {
      "currency": "EUR",
      "owedToYou": 1500,
      "youOwe": 0,
      "net": 1500
    }
  ],
  "friends": {
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": [
      {
        "currency": "EUR",
        "amountMinor": 1500
      }
    ]
  },
  "groups": {
    "d19d0200-ea0e-4d0a-a899-2b96bf06ac03": {
      "currency": "EUR",
      "net": 1500
    }
  }
}

GET`/api/activity`Permesso: sola lettura

Registro delle attività

Parametri

Campo	Tipo	Descrizione
before query	string	Data ISO 8601: restituisce solo attività precedenti (paginazione, 50 per volta).

Esempio

curl -X GET 'https://billmate.it/api/activity' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "items": [
    {
      "id": "a1…",
      "type": "expense_added",
      "entityType": "expense",
      "entityId": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
      "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "data": {
        "description": "Cena in Trastevere",
        "amountMinor": 4000,
        "currency": "EUR"
      },
      "createdAt": "2026-10-21T15:11:20.735Z",
      "actor": {
        "id": "47542df6-597a-45b4-ab18-816c4b538265",
        "name": "Anna",
        "avatarUrl": null
      }
    }
  ]
}

Gruppi

GET`/api/groups`Permesso: sola lettura

Elenco dei tuoi gruppi

Parametri

Campo	Tipo	Descrizione
archived query	string	`true` per i gruppi archiviati (predefinito: `false`).true \| false

Esempio

curl -X GET 'https://billmate.it/api/groups' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "items": [
    {
      "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "name": "Weekend a Roma",
      "type": "trip",
      "currency": "EUR",
      "archivedAt": null,
      "role": "owner",
      "memberCount": 2,
      "members": [
        {
          "id": "47542df6-597a-45b4-ab18-816c4b538265",
          "name": "Anna",
          "avatarUrl": null
        },
        {
          "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
          "name": "Luca",
          "avatarUrl": null
        }
      ],
      "myBalanceMinor": 1500
    }
  ]
}

POST`/api/groups`Permesso: scrittura

Crea un gruppo

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
name	string	sì	Nome del gruppo (max 60 caratteri).max 60
type	string	no	Tipo di gruppo.trip \| home \| couple \| event \| family \| other · default "other"
currency	string	no	Valuta del gruppo (ISO 4217, predefinita EUR).default "EUR"
notes	object	no	Note facoltative.
simplifyDebts	boolean	no	Semplifica i debiti in meno pagamenti (predefinito: true).default true
memberIds	string (uuid)[]	no	Amici da aggiungere subito (devono essere già tuoi amici).max 50

Esempio

curl -X POST 'https://billmate.it/api/groups' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Weekend a Roma","type":"trip","currency":"EUR","simplifyDebts":true}'

Risposta 201

{
  "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03"
}

GET`/api/groups/{id}`Permesso: sola lettura

Dettaglio di un gruppo, con membri e saldi

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Esempio

curl -X GET 'https://billmate.it/api/groups/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "group": {
    "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
    "name": "Weekend a Roma",
    "type": "trip",
    "currency": "EUR",
    "simplifyDebts": true,
    "archivedAt": null
  },
  "myRole": "owner",
  "members": [
    {
      "userId": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "role": "owner"
    }
  ],
  "balances": {
    "currency": "EUR",
    "simplified": true,
    "net": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "amountMinor": 1500
      },
      {
        "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "amountMinor": -1500
      }
    ],
    "transfers": [
      {
        "from": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "to": "47542df6-597a-45b4-ab18-816c4b538265",
        "amountMinor": 1500
      }
    ],
    "totalSpentMinor": 4000,
    "settledUp": false
  }
}

PATCH`/api/groups/{id}`Permesso: scrittura

Modifica un gruppo

Tutti i campi sono facoltativi; servono i permessi di modifica del gruppo. Restituisce il dettaglio aggiornato.

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
name	string	no	max 60
type	string	no	trip \| home \| couple \| event \| family \| other
currency	string	no
notes	object	no
simplifyDebts	boolean	no
policy	object	no

Esempio

curl -X PATCH 'https://billmate.it/api/groups/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Weekend a Napoli"}'

DELETE`/api/groups/{id}`Permesso: scrittura

Elimina un gruppo

Solo il proprietario, e solo scrivendo il nome esatto del gruppo in `confirmName`.

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
confirmName	string	sì

Esempio

curl -X DELETE 'https://billmate.it/api/groups/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"confirmName":"Weekend a Roma"}'

Risposta 200

{
  "ok": true
}

Spese

GET`/api/expenses`Permesso: sola lettura

Elenco delle spese visibili

Paginato (`page`, `limit` fino a 100). La risposta include `users` con i nomi delle persone citate.

Parametri

Campo	Tipo	Descrizione
groupId query	string (uuid)	Solo spese di questo gruppo.
friendId query	string (uuid)	Solo spese tra te e questo amico.
personId query	string (uuid)	Solo spese a cui partecipa questa persona.
categoryId query	string (uuid)	Solo questa categoria.
q query	string	Ricerca testuale nella descrizione e nelle note.max 100
from query	string	Data minima (AAAA-MM-GG).
to query	string	Data massima (AAAA-MM-GG).
status query	string	`active` (predefinito), `deleted` o `all`.active \| deleted \| all · default "active"
kind query	string	`expense` o `refund`.expense \| refund
page query	integer	Pagina, da 1.1–1000 · default 1
limit query	integer	Elementi per pagina (1–100, predefinito 30).1–100 · default 30

Esempio

curl -X GET 'https://billmate.it/api/expenses' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "items": [
    {
      "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
      "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "groupName": "Weekend a Roma",
      "kind": "expense",
      "description": "Cena in Trastevere",
      "notes": null,
      "amountMinor": 4000,
      "currency": "EUR",
      "baseCurrency": "EUR",
      "fxRate": "1.00000000",
      "amountBaseMinor": 4000,
      "category": null,
      "expenseDate": "2026-10-21",
      "splitMethod": "equal",
      "createdBy": "47542df6-597a-45b4-ab18-816c4b538265",
      "createdAt": "2026-10-21T15:11:20.630Z",
      "updatedAt": "2026-10-21T15:11:20.630Z",
      "deletedAt": null,
      "version": 1,
      "payments": [
        {
          "userId": "47542df6-597a-45b4-ab18-816c4b538265",
          "paidMinor": 4000
        }
      ],
      "splits": [
        {
          "userId": "47542df6-597a-45b4-ab18-816c4b538265",
          "owedMinor": 2000,
          "inputValue": null
        },
        {
          "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
          "owedMinor": 2000,
          "inputValue": null
        }
      ],
      "myNetMinor": 2000,
      "canEdit": true,
      "canDelete": true
    }
  ],
  "hasMore": false,
  "page": 1,
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

POST`/api/expenses`Permesso: scrittura

Crea una spesa

Restituisce il dettaglio della spesa creata. Importi sempre in unità minori. Per un invio sicuro da riprovare usa `clientId`.

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
groupId	object	no	Gruppo della spesa; assente o null per una spesa tra amici fuori gruppo.
description	string	sì	Descrizione breve (max 140 caratteri).max 140
notes	object	no	Note facoltative (max 1000 caratteri).
amountMinor	integer	sì	Importo totale in unità minori (centesimi): 4000 = 40,00. Deve essere maggiore di zero.0–9999999999999
currency	string	sì	Codice ISO 4217 della valuta in cui è stata pagata la spesa (es. EUR).
fxRate	object	no	Tasso verso la valuta del gruppo, solo se le valute differiscono e non c’è un tasso noto.
categoryId	object	no	Categoria (id da GET /api/meta).
expenseDate	string	sì	Data della spesa (AAAA-MM-GG).
splitMethod	string	sì	Metodo di divisione: equal, exact, percent, shares, adjust o items.equal \| exact \| percent \| shares \| adjust \| items
payments	object[]	sì	Chi ha pagato e quanto (la somma deve coincidere con amountMinor).max 50
participants	object[]	sì	Chi partecipa alla divisione; `value` serve per exact (importo), percent (percentuale ×100), shares (quote) e adjust.max 50
items	object[]	no	Voci dello scontrino, solo con splitMethod=items.max 60
clientId	object	no	UUID generato dal client: rende la creazione idempotente (un secondo invio con lo stesso id non duplica la spesa).

Esempio

curl -X POST 'https://billmate.it/api/expenses' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"d19d0200-ea0e-4d0a-a899-2b96bf06ac03","description":"Cena in Trastevere","amountMinor":4000,"currency":"EUR","expenseDate":"2026-10-21","splitMethod":"equal","payments":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265","paidMinor":4000}],"participants":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265"},{"userId":"b93e456c-f17f-4d42-a36f-96f75dad14f3"}]}'

Risposta 201

{
  "expense": {
    "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
    "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
    "groupName": "Weekend a Roma",
    "kind": "expense",
    "description": "Cena in Trastevere",
    "notes": null,
    "amountMinor": 4000,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "fxRate": "1.00000000",
    "amountBaseMinor": 4000,
    "category": null,
    "expenseDate": "2026-10-21",
    "splitMethod": "equal",
    "createdBy": "47542df6-597a-45b4-ab18-816c4b538265",
    "createdAt": "2026-10-21T15:11:20.630Z",
    "updatedAt": "2026-10-21T15:11:20.630Z",
    "deletedAt": null,
    "version": 1,
    "payments": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "paidMinor": 4000
      }
    ],
    "splits": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "owedMinor": 2000,
        "inputValue": null
      },
      {
        "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "owedMinor": 2000,
        "inputValue": null
      }
    ],
    "myNetMinor": 2000,
    "canEdit": true,
    "canDelete": true
  },
  "attachments": [],
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

GET`/api/expenses/{id}`Permesso: sola lettura

Dettaglio di una spesa

Include voci, rimborsi, allegati (metadati) e cronologia delle revisioni.

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Esempio

curl -X GET 'https://billmate.it/api/expenses/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "expense": {
    "id": "1a7fed19-c0b0-4607-aef2-8422b592dc14",
    "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
    "groupName": "Weekend a Roma",
    "kind": "expense",
    "description": "Cena in Trastevere",
    "notes": null,
    "amountMinor": 4000,
    "currency": "EUR",
    "baseCurrency": "EUR",
    "fxRate": "1.00000000",
    "amountBaseMinor": 4000,
    "category": null,
    "expenseDate": "2026-10-21",
    "splitMethod": "equal",
    "createdBy": "47542df6-597a-45b4-ab18-816c4b538265",
    "createdAt": "2026-10-21T15:11:20.630Z",
    "updatedAt": "2026-10-21T15:11:20.630Z",
    "deletedAt": null,
    "version": 1,
    "payments": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "paidMinor": 4000
      }
    ],
    "splits": [
      {
        "userId": "47542df6-597a-45b4-ab18-816c4b538265",
        "owedMinor": 2000,
        "inputValue": null
      },
      {
        "userId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
        "owedMinor": 2000,
        "inputValue": null
      }
    ],
    "myNetMinor": 2000,
    "canEdit": true,
    "canDelete": true,
    "items": [],
    "refunds": [],
    "refundedMinor": 0,
    "remainingRefundableMinor": 4000
  },
  "attachments": [],
  "revisions": [
    {
      "id": "r1…",
      "version": 1,
      "changeType": "create",
      "changedBy": "47542df6-597a-45b4-ab18-816c4b538265",
      "createdAt": "2026-10-21T15:11:20.630Z"
    }
  ],
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

PUT`/api/expenses/{id}`Permesso: scrittura

Modifica una spesa

Sostituisce l’intera spesa (stesso corpo della creazione, più `expectedVersion` facoltativo). Restituisce il dettaglio aggiornato.

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
groupId	object	no	Gruppo della spesa; assente o null per una spesa tra amici fuori gruppo.
description	string	sì	Descrizione breve (max 140 caratteri).max 140
notes	object	no	Note facoltative (max 1000 caratteri).
amountMinor	integer	sì	Importo totale in unità minori (centesimi): 4000 = 40,00. Deve essere maggiore di zero.0–9999999999999
currency	string	sì	Codice ISO 4217 della valuta in cui è stata pagata la spesa (es. EUR).
fxRate	object	no	Tasso verso la valuta del gruppo, solo se le valute differiscono e non c’è un tasso noto.
categoryId	object	no	Categoria (id da GET /api/meta).
expenseDate	string	sì	Data della spesa (AAAA-MM-GG).
splitMethod	string	sì	Metodo di divisione: equal, exact, percent, shares, adjust o items.equal \| exact \| percent \| shares \| adjust \| items
payments	object[]	sì	Chi ha pagato e quanto (la somma deve coincidere con amountMinor).max 50
participants	object[]	sì	Chi partecipa alla divisione; `value` serve per exact (importo), percent (percentuale ×100), shares (quote) e adjust.max 50
items	object[]	no	Voci dello scontrino, solo con splitMethod=items.max 60
clientId	object	no	UUID generato dal client: rende la creazione idempotente (un secondo invio con lo stesso id non duplica la spesa).
expectedVersion	integer	no	Versione che il client ha letto: se la spesa è cambiata nel frattempo la modifica è rifiutata con 409.

Esempio

curl -X PUT 'https://billmate.it/api/expenses/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"d19d0200-ea0e-4d0a-a899-2b96bf06ac03","description":"Cena in Trastevere (con mancia)","amountMinor":4400,"currency":"EUR","expenseDate":"2026-10-21","splitMethod":"equal","payments":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265","paidMinor":4400}],"participants":[{"userId":"47542df6-597a-45b4-ab18-816c4b538265"},{"userId":"b93e456c-f17f-4d42-a36f-96f75dad14f3"}],"expectedVersion":1}'

DELETE`/api/expenses/{id}`Permesso: scrittura

Elimina una spesa

Eliminazione logica: la spesa resta nella cronologia con `deletedAt`.

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Esempio

curl -X DELETE 'https://billmate.it/api/expenses/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "ok": true
}

Pagamenti

GET`/api/settlements`Permesso: sola lettura

Elenco dei pagamenti registrati

Parametri

Campo	Tipo	Descrizione
groupId query	string (uuid)	Solo pagamenti di questo gruppo.
friendId query	string (uuid)	Solo pagamenti tra te e questo amico.

Esempio

curl -X GET 'https://billmate.it/api/settlements' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "items": [
    {
      "id": "s1…",
      "groupId": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03",
      "fromUserId": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "toUserId": "47542df6-597a-45b4-ab18-816c4b538265",
      "amountMinor": 500,
      "currency": "EUR",
      "method": "cash",
      "note": null,
      "settledOn": "2026-10-21",
      "createdBy": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "canDelete": true
    }
  ],
  "users": {
    "47542df6-597a-45b4-ab18-816c4b538265": {
      "id": "47542df6-597a-45b4-ab18-816c4b538265",
      "name": "Anna",
      "avatarUrl": null
    },
    "b93e456c-f17f-4d42-a36f-96f75dad14f3": {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "avatarUrl": null
    }
  }
}

POST`/api/settlements`Permesso: scrittura

Registra un pagamento tra due persone

BillMate è un registro: questa chiamata annota un pagamento già avvenuto, non sposta denaro.

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
groupId	object	no	Gruppo del pagamento; null per un pagamento tra amici.
fromUserId	string (uuid)	sì	Chi ha pagato.
toUserId	string (uuid)	sì	Chi ha ricevuto.
amountMinor	integer	sì	Importo in unità minori, maggiore di zero.0–9999999999999
currency	string	sì	Valuta ISO 4217.
method	string	no	cash, bank_transfer, paypal, revolut, satispay o other (predefinito cash).cash \| bank_transfer \| paypal \| revolut \| satispay \| other · default "cash"
note	object	no	Nota facoltativa (max 300 caratteri).
settledOn	string	sì	Data del pagamento (AAAA-MM-GG).

Esempio

curl -X POST 'https://billmate.it/api/settlements' \
  -H 'Authorization: Bearer bm_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"groupId":"d19d0200-ea0e-4d0a-a899-2b96bf06ac03","fromUserId":"b93e456c-f17f-4d42-a36f-96f75dad14f3","toUserId":"47542df6-597a-45b4-ab18-816c4b538265","amountMinor":500,"currency":"EUR","method":"cash","settledOn":"2026-10-21"}'

Risposta 201

{
  "id": "s1…"
}

DELETE`/api/settlements/{id}`Permesso: scrittura

Annulla un pagamento registrato

Parametri

Campo	Tipo	Descrizione
id path	string (uuid)	Id della risorsa.

Esempio

curl -X DELETE 'https://billmate.it/api/settlements/{id}' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "ok": true
}

Amici

GET`/api/friends`Permesso: sola lettura

Amici e richieste di amicizia

Esempio

curl -X GET 'https://billmate.it/api/friends' \
  -H 'Authorization: Bearer bm_YOUR_KEY'

Risposta 200

{
  "friends": [
    {
      "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3",
      "name": "Luca",
      "email": "luca@example.com",
      "avatarUrl": null,
      "explicit": true,
      "balances": [
        {
          "currency": "EUR",
          "amountMinor": 1500
        }
      ]
    }
  ],
  "incoming": [],
  "outgoing": []
}

Specifica OpenAPI 3.1

Scarica la specifica per generare un client o importarla in Postman e Insomnia: /developers/openapi.json

API di BillMate

Per iniziare

Chiavi e permessi

Non disponibile con le chiavi

Convenzioni

Limiti di utilizzo

Errori

Endpoint

Account e dati di riferimento

GET/api/mePermesso: sola lettura

GET/api/metaPermesso: sola lettura

GET/api/dashboardPermesso: sola lettura

GET/api/balancesPermesso: sola lettura

GET/api/activityPermesso: sola lettura

Gruppi

GET/api/groupsPermesso: sola lettura

POST/api/groupsPermesso: scrittura

GET/api/groups/{id}Permesso: sola lettura

PATCH/api/groups/{id}Permesso: scrittura

DELETE/api/groups/{id}Permesso: scrittura

Spese

GET/api/expensesPermesso: sola lettura

POST/api/expensesPermesso: scrittura

GET/api/expenses/{id}Permesso: sola lettura

PUT/api/expenses/{id}Permesso: scrittura

DELETE/api/expenses/{id}Permesso: scrittura

Pagamenti

GET/api/settlementsPermesso: sola lettura

POST/api/settlementsPermesso: scrittura

DELETE/api/settlements/{id}Permesso: scrittura

Amici

GET/api/friendsPermesso: sola lettura

Specifica OpenAPI 3.1

GET`/api/me`Permesso: sola lettura

GET`/api/meta`Permesso: sola lettura

GET`/api/dashboard`Permesso: sola lettura

GET`/api/balances`Permesso: sola lettura

GET`/api/activity`Permesso: sola lettura

GET`/api/groups`Permesso: sola lettura

POST`/api/groups`Permesso: scrittura

GET`/api/groups/{id}`Permesso: sola lettura

PATCH`/api/groups/{id}`Permesso: scrittura

DELETE`/api/groups/{id}`Permesso: scrittura

GET`/api/expenses`Permesso: sola lettura

POST`/api/expenses`Permesso: scrittura

GET`/api/expenses/{id}`Permesso: sola lettura

PUT`/api/expenses/{id}`Permesso: scrittura

DELETE`/api/expenses/{id}`Permesso: scrittura

GET`/api/settlements`Permesso: sola lettura

POST`/api/settlements`Permesso: scrittura

DELETE`/api/settlements/{id}`Permesso: scrittura

GET`/api/friends`Permesso: sola lettura