{ "openapi": "3.1.0", "info": { "title": "BillMate API", "version": "1.0.0", "description": "API gratuita di BillMate per client alternativi. Autenticazione con una chiave personale generata dal profilo. Importi sempre in unità minori (centesimi)." }, "servers": [ { "url": "https://billmate.it" } ], "security": [ { "apiKey": [] } ], "paths": { "/api/me": { "get": { "operationId": "me", "tags": [ "Account e dati di riferimento" ], "summary": "Profilo dell’utente della chiave", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/meta": { "get": { "operationId": "meta", "tags": [ "Account e dati di riferimento" ], "summary": "Valute abilitate, categorie e limiti", "description": "Dati di riferimento per creare spese: valute (con decimali), categorie di piattaforma e del gruppo, e il tasso suggerito tra due valute.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "description": "Include anche le categorie personalizzate di questo gruppo.", "schema": { "type": "string", "format": "uuid" } }, { "name": "from", "in": "query", "required": false, "description": "Valuta di partenza per il tasso suggerito.", "schema": { "type": "string", "minLength": 3, "maxLength": 3 } }, { "name": "to", "in": "query", "required": false, "description": "Valuta di arrivo per il tasso suggerito.", "schema": { "type": "string", "minLength": 3, "maxLength": 3 } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/dashboard": { "get": { "operationId": "dashboard", "tags": [ "Account e dati di riferimento" ], "summary": "Riepilogo: totali, gruppi, amici e attività recente", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "totals": [ { "currency": "EUR", "owedToYou": 1500, "youOwe": 0, "net": 1500 } ], "groups": [ "…" ], "friends": [ "…" ], "friendCount": 1, "incomingRequests": 0, "activity": [ "…" ], "unread": 0 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/balances": { "get": { "operationId": "balances", "tags": [ "Account e dati di riferimento" ], "summary": "Saldi totali, per amico e per gruppo", "description": "Importi in unità minori. Un valore positivo significa che ti devono dei soldi, negativo che ne devi tu.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/activity": { "get": { "operationId": "activity", "tags": [ "Account e dati di riferimento" ], "summary": "Registro delle attività", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "before", "in": "query", "required": false, "description": "Data ISO 8601: restituisce solo attività precedenti (paginazione, 50 per volta).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } }, "/api/groups": { "get": { "operationId": "groups_list", "tags": [ "Gruppi" ], "summary": "Elenco dei tuoi gruppi", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "archived", "in": "query", "required": false, "description": "`true` per i gruppi archiviati (predefinito: `false`).", "schema": { "type": "string", "enum": [ "true", "false" ] } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "post": { "operationId": "groups_create", "tags": [ "Gruppi" ], "summary": "Crea un gruppo", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "id": "d19d0200-ea0e-4d0a-a899-2b96bf06ac03" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Nome del gruppo (max 60 caratteri)." }, "type": { "default": "other", "type": "string", "enum": [ "trip", "home", "couple", "event", "family", "other" ], "description": "Tipo di gruppo." }, "currency": { "default": "EUR", "type": "string", "pattern": "^[A-Z]{3}$", "description": "Valuta del gruppo (ISO 4217, predefinita EUR)." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ], "description": "Note facoltative." }, "simplifyDebts": { "default": true, "type": "boolean", "description": "Semplifica i debiti in meno pagamenti (predefinito: true)." }, "memberIds": { "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Amici da aggiungere subito (devono essere già tuoi amici)." } }, "required": [ "name" ] }, "example": { "name": "Weekend a Roma", "type": "trip", "currency": "EUR", "simplifyDebts": true } } } } } }, "/api/groups/{id}": { "get": { "operationId": "groups_get", "tags": [ "Gruppi" ], "summary": "Dettaglio di un gruppo, con membri e saldi", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "patch": { "operationId": "groups_update", "tags": [ "Gruppi" ], "summary": "Modifica un gruppo", "description": "Tutti i campi sono facoltativi; servono i permessi di modifica del gruppo. Restituisce il dettaglio aggiornato.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60 }, "type": { "type": "string", "enum": [ "trip", "home", "couple", "event", "family", "other" ] }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "notes": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "simplifyDebts": { "type": "boolean" }, "policy": { "type": "object", "properties": { "addExpense": { "type": "string", "enum": [ "members", "admins" ] }, "editExpense": { "type": "string", "enum": [ "members", "creator", "admins" ] }, "deleteExpense": { "type": "string", "enum": [ "members", "creator", "admins" ] }, "invite": { "type": "string", "enum": [ "members", "admins" ] }, "archive": { "type": "string", "enum": [ "admins", "owner" ] } }, "required": [ "addExpense", "editExpense", "deleteExpense", "invite", "archive" ] } } }, "example": { "name": "Weekend a Napoli" } } } } }, "delete": { "operationId": "groups_delete", "tags": [ "Gruppi" ], "summary": "Elimina un gruppo", "description": "Solo il proprietario, e solo scrivendo il nome esatto del gruppo in `confirmName`.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmName": { "type": "string" } }, "required": [ "confirmName" ] }, "example": { "confirmName": "Weekend a Roma" } } } } } }, "/api/expenses": { "get": { "operationId": "expenses_list", "tags": [ "Spese" ], "summary": "Elenco delle spese visibili", "description": "Paginato (`page`, `limit` fino a 100). La risposta include `users` con i nomi delle persone citate.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "description": "Solo spese di questo gruppo.", "schema": { "type": "string", "format": "uuid" } }, { "name": "friendId", "in": "query", "required": false, "description": "Solo spese tra te e questo amico.", "schema": { "type": "string", "format": "uuid" } }, { "name": "personId", "in": "query", "required": false, "description": "Solo spese a cui partecipa questa persona.", "schema": { "type": "string", "format": "uuid" } }, { "name": "categoryId", "in": "query", "required": false, "description": "Solo questa categoria.", "schema": { "type": "string", "format": "uuid" } }, { "name": "q", "in": "query", "required": false, "description": "Ricerca testuale nella descrizione e nelle note.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "from", "in": "query", "required": false, "description": "Data minima (AAAA-MM-GG).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "description": "Data massima (AAAA-MM-GG).", "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "status", "in": "query", "required": false, "description": "`active` (predefinito), `deleted` o `all`.", "schema": { "default": "active", "type": "string", "enum": [ "active", "deleted", "all" ] } }, { "name": "kind", "in": "query", "required": false, "description": "`expense` o `refund`.", "schema": { "type": "string", "enum": [ "expense", "refund" ] } }, { "name": "page", "in": "query", "required": false, "description": "Pagina, da 1.", "schema": { "default": 1, "type": "integer", "minimum": 1, "maximum": 1000 } }, { "name": "limit", "in": "query", "required": false, "description": "Elementi per pagina (1–100, predefinito 30).", "schema": { "default": 30, "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "post": { "operationId": "expenses_create", "tags": [ "Spese" ], "summary": "Crea una spesa", "description": "Restituisce il dettaglio della spesa creata. Importi sempre in unità minori. Per un invio sicuro da riprovare usa `clientId`.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Gruppo della spesa; assente o null per una spesa tra amici fuori gruppo." }, "description": { "type": "string", "maxLength": 140, "description": "Descrizione breve (max 140 caratteri)." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Note facoltative (max 1000 caratteri)." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "Importo totale in unità minori (centesimi): 4000 = 40,00. Deve essere maggiore di zero." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Codice ISO 4217 della valuta in cui è stata pagata la spesa (es. EUR)." }, "fxRate": { "anyOf": [ { "type": "string", "pattern": "^\\d+([.,]\\d+)?$" }, { "type": "null" } ], "description": "Tasso verso la valuta del gruppo, solo se le valute differiscono e non c’è un tasso noto." }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Categoria (id da GET /api/meta)." }, "expenseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Data della spesa (AAAA-MM-GG)." }, "splitMethod": { "type": "string", "enum": [ "equal", "exact", "percent", "shares", "adjust", "items" ], "description": "Metodo di divisione: equal, exact, percent, shares, adjust o items." }, "payments": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "paidMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 } }, "required": [ "userId", "paidMinor" ] }, "description": "Chi ha pagato e quanto (la somma deve coincidere con amountMinor)." }, "participants": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "value": { "type": "integer", "minimum": -9999999999999, "maximum": 9999999999999 } }, "required": [ "userId" ] }, "description": "Chi partecipa alla divisione; `value` serve per exact (importo), percent (percentuale ×100), shares (quote) e adjust." }, "items": { "maxItems": 60, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 }, "userIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name", "amountMinor", "userIds" ] }, "description": "Voci dello scontrino, solo con splitMethod=items." }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID generato dal client: rende la creazione idempotente (un secondo invio con lo stesso id non duplica la spesa)." } }, "required": [ "description", "amountMinor", "currency", "expenseDate", "splitMethod", "payments", "participants" ] }, "example": { "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" } ] } } } } } }, "/api/expenses/{id}": { "get": { "operationId": "expenses_get", "tags": [ "Spese" ], "summary": "Dettaglio di una spesa", "description": "Include voci, rimborsi, allegati (metadati) e cronologia delle revisioni.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "put": { "operationId": "expenses_update", "tags": [ "Spese" ], "summary": "Modifica una spesa", "description": "Sostituisce l’intera spesa (stesso corpo della creazione, più `expectedVersion` facoltativo). Restituisce il dettaglio aggiornato.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Gruppo della spesa; assente o null per una spesa tra amici fuori gruppo." }, "description": { "type": "string", "maxLength": 140, "description": "Descrizione breve (max 140 caratteri)." }, "notes": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ], "description": "Note facoltative (max 1000 caratteri)." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "Importo totale in unità minori (centesimi): 4000 = 40,00. Deve essere maggiore di zero." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Codice ISO 4217 della valuta in cui è stata pagata la spesa (es. EUR)." }, "fxRate": { "anyOf": [ { "type": "string", "pattern": "^\\d+([.,]\\d+)?$" }, { "type": "null" } ], "description": "Tasso verso la valuta del gruppo, solo se le valute differiscono e non c’è un tasso noto." }, "categoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Categoria (id da GET /api/meta)." }, "expenseDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Data della spesa (AAAA-MM-GG)." }, "splitMethod": { "type": "string", "enum": [ "equal", "exact", "percent", "shares", "adjust", "items" ], "description": "Metodo di divisione: equal, exact, percent, shares, adjust o items." }, "payments": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "paidMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 } }, "required": [ "userId", "paidMinor" ] }, "description": "Chi ha pagato e quanto (la somma deve coincidere con amountMinor)." }, "participants": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid" }, "value": { "type": "integer", "minimum": -9999999999999, "maximum": 9999999999999 } }, "required": [ "userId" ] }, "description": "Chi partecipa alla divisione; `value` serve per exact (importo), percent (percentuale ×100), shares (quote) e adjust." }, "items": { "maxItems": 60, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 80 }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999 }, "userIds": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "name", "amountMinor", "userIds" ] }, "description": "Voci dello scontrino, solo con splitMethod=items." }, "clientId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "UUID generato dal client: rende la creazione idempotente (un secondo invio con lo stesso id non duplica la spesa)." }, "expectedVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Versione che il client ha letto: se la spesa è cambiata nel frattempo la modifica è rifiutata con 409." } }, "required": [ "description", "amountMinor", "currency", "expenseDate", "splitMethod", "payments", "participants" ] }, "example": { "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": { "operationId": "expenses_delete", "tags": [ "Spese" ], "summary": "Elimina una spesa", "description": "Eliminazione logica: la spesa resta nella cronologia con `deletedAt`.", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write" } }, "/api/settlements": { "get": { "operationId": "settlements_list", "tags": [ "Pagamenti" ], "summary": "Elenco dei pagamenti registrati", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "groupId", "in": "query", "required": false, "description": "Solo pagamenti di questo gruppo.", "schema": { "type": "string", "format": "uuid" } }, { "name": "friendId", "in": "query", "required": false, "description": "Solo pagamenti tra te e questo amico.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" }, "post": { "operationId": "settlements_create", "tags": [ "Pagamenti" ], "summary": "Registra un pagamento tra due persone", "description": "BillMate è un registro: questa chiamata annota un pagamento già avvenuto, non sposta denaro.", "security": [ { "apiKey": [] } ], "responses": { "201": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "id": "s1…" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "groupId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ], "description": "Gruppo del pagamento; null per un pagamento tra amici." }, "fromUserId": { "type": "string", "format": "uuid", "description": "Chi ha pagato." }, "toUserId": { "type": "string", "format": "uuid", "description": "Chi ha ricevuto." }, "amountMinor": { "type": "integer", "minimum": 0, "maximum": 9999999999999, "description": "Importo in unità minori, maggiore di zero." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Valuta ISO 4217." }, "method": { "default": "cash", "type": "string", "enum": [ "cash", "bank_transfer", "paypal", "revolut", "satispay", "other" ], "description": "cash, bank_transfer, paypal, revolut, satispay o other (predefinito cash)." }, "note": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ], "description": "Nota facoltativa (max 300 caratteri)." }, "settledOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Data del pagamento (AAAA-MM-GG)." } }, "required": [ "fromUserId", "toUserId", "amountMinor", "currency", "settledOn" ] }, "example": { "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" } } } } } }, "/api/settlements/{id}": { "delete": { "operationId": "settlements_delete", "tags": [ "Pagamenti" ], "summary": "Annulla un pagamento registrato", "security": [ { "apiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "ok": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "write" } }, "/api/friends": { "get": { "operationId": "friends_list", "tags": [ "Amici" ], "summary": "Amici e richieste di amicizia", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Operazione riuscita", "content": { "application/json": { "example": { "friends": [ { "id": "b93e456c-f17f-4d42-a36f-96f75dad14f3", "name": "Luca", "email": "luca@example.com", "avatarUrl": null, "explicit": true, "balances": [ { "currency": "EUR", "amountMinor": 1500 } ] } ], "incoming": [], "outgoing": [] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "x-required-scope": "read" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "bm_…", "description": "Chiave API personale: `Authorization: Bearer bm_…`" } }, "responses": { "Unauthorized": { "description": "Chiave mancante, non valida, scaduta o revocata", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "details": {} }, "required": [ "code" ] } }, "required": [ "error" ] } } } }, "Forbidden": { "description": "Chiave di sola lettura, endpoint non disponibile con le chiavi o permessi insufficienti", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "details": {} }, "required": [ "code" ] } }, "required": [ "error" ] } } } }, "RateLimited": { "description": "Troppe richieste: riprova dopo `retryAfterSec` secondi", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "UNAUTHORIZED" }, "details": {} }, "required": [ "code" ] } }, "required": [ "error" ] } } } } } } }