{ "openapi": "3.0.3", "info": { "title": "Onesto.it API", "description": "Benvenuto nella documentazione ufficiale delle API di **Onesto.it** — il fisco, ma intelligente.\n\nQueste API ti permettono di integrare nei tuoi sistemi le funzionalità fiscali di Onesto: creazione fatture attive (manuali o da Partita IVA con recupero dati automatico), invio al **SDI** (Sistema di Interscambio), gestione anagrafica clienti, e altro ancora.\n\n\n\nMentre scorri vedrai a destra (o nel contenuto, da mobile) esempi di codice nei principali linguaggi di programmazione. Puoi cambiare il linguaggio dai tab in alto a destra (o dal menu di navigazione, da mobile).\n\nPer andare più veloce mettiamo a disposizione **SDK ufficiali** che gestiscono autenticazione, retry, parsing JSON e modellano i payload con classi tipizzate. Vedi la sezione **SDK** nel menu a sinistra per la lista completa e gli esempi di installazione. Sono open source su [github.com/Onesto-it](https://github.com/Onesto-it).", "version": "1.0.0", "x-logo": { "url": "https://app.onesto.it/images/logo-docs.svg", "href": "https://onesto.it", "altText": "Onesto.it" } }, "servers": [ { "url": "https://api.onesto.it", "description": "Produzione" }, { "url": "https://api.sandbox.onesto.it", "description": "Sandbox" } ], "tags": [ { "name": "Aziende", "description": "\nAnagrafica delle aziende (account) visibili al token. Serve a mappare le aziende\nOnesto sui clienti del consumer (match su P.IVA / codice fiscale)." }, { "name": "Clienti", "description": "" }, { "name": "Fatture", "description": "\nLista delle fatture elettroniche (attive e passive) degli account gestiti, con\nstato SdI normalizzato e stato di incasso (`payment_status`). Usi tipici:\nintercettare le fatture scartate/in errore e monitorare le fatture non incassate." }, { "name": "Spese", "description": "\nCentri di costo delle aziende gestite: la dimensione ANALITICA con cui le\nspese vengono attribuite a un cliente, un prodotto, una commessa o una sede.\n\nIl riferimento stabile è `code`, non `id`: è quello che i sistemi esterni\ndevono mappare. È univoco per azienda e non cambia quando il centro viene\nrinominato." }, { "name": "F24", "description": "\nF24 degli account gestiti: scadenze, importi, stato pagamento, link al PDF e\nquietanze. È il cuore della supervisione fiscale (alert su scaduti / in scadenza)." }, { "name": "Scadenze fiscali", "description": "\nScadenzario fiscale generico degli account (F24, IVA, INPS, dichiarazioni…).\nEstende la supervisione oltre i soli F24. Sorgente: record `taxes`." }, { "name": "Corrispettivi", "description": "\nStato del caricamento corrispettivi telematici. ⚠️ Onesto NON gestisce\nnativamente i corrispettivi/registratori telematici: l'endpoint esiste per\ncompletezza del contratto API ma risponde con `supported=false` e lista vuota,\ncosì il consumer non lo tratta come errore. Verrà popolato se/quando Onesto\nintrodurrà la gestione dei corrispettivi." }, { "name": "Automazioni e webhook", "description": "\nEndpoint con cui Zapier, n8n e le integrazioni fatte in casa si sottoscrivono\nagli eventi di Onesto (REST Hooks): catalogo degli eventi disponibili, dati di\nesempio per configurare i passi a valle, e gestione delle sottoscrizioni.\n\n⚠️ Una sottoscrizione appartiene a UNA azienda: la chiave usata deve essere\nquella della singola azienda (creata da /company/integrations), non un token\ndi studio che ne vede molte — indovinare l'azienda manderebbe i dati di un\ncliente dentro l'automazione di un altro." }, { "name": "Laravel SDK (PHP)", "description": "Pacchetto Composer ufficiale per progetti Laravel.\n\n- **Repo GitHub**: \n- **Packagist**: \n- **Requisiti**: PHP 8.1+, Laravel 9 / 10 / 11 / 12\n\n## Installazione\n\n```bash\ncomposer require onesto-it/laravel-sdk\n```\n\nService provider e alias `Onesto` registrati automaticamente da Laravel package discovery. Nessun setup manuale richiesto.\n\nOpzionale — pubblica il file di configurazione:\n\n```bash\nphp artisan vendor:publish --tag=onesto-config\n```\n\n## Configurazione `.env`\n\n```env\nONESTO_TOKEN=il_tuo_api_token\n# opzionale, default https://api.onesto.it\nONESTO_URL=https://api.onesto.it\n# opzionale, default 30s\nONESTO_TIMEOUT=30\n```\n\nIl token si genera da **Impostazioni → Integrazioni** ([app.onesto.it/company/integrations](https://app.onesto.it/company/integrations)) nel tuo pannello Onesto.\n\n## Esempi\n\n### Creazione fattura da Partita IVA\n\nI dati anagrafici vengono recuperati automaticamente da Onesto:\n\n```php\nuse Onesto;\n\nOnesto::createInvoiceFromPIVA([\n 'piva' => '01234567890',\n 'numerazione' => 'Standard',\n 'issue_date' => '2026-05-20',\n 'tipo_documento' => 'TD01',\n 'metodo_pagamento' => 'Bonifico',\n 'articoli' => [/* ... */],\n 'scadenze' => [/* ... */],\n 'invia_sdi' => true,\n]);\n```\n\n### Creazione fattura manuale\n\n```php\nOnesto::createInvoiceManually([\n 'cliente' => [\n 'ragione_sociale' => 'Acme SRL',\n 'piva' => '01234567890',\n 'indirizzo' => 'Via Roma 1',\n 'cap' => '20121',\n 'citta' => 'Milano',\n 'provincia' => 'MI',\n 'nazione' => 'IT',\n 'pec' => 'acme@pec.it',\n ],\n 'articoli' => [\n ['descrizione' => 'Consulenza', 'quantita' => 1, 'prezzo' => 1000, 'iva' => 22],\n ],\n 'scadenze' => [\n ['data' => '2026-06-30', 'importo' => 1220],\n ],\n 'invia_sdi' => true,\n]);\n```\n\n### Riferimenti Pubblica Amministrazione (CIG, CUP, ordine, determina…)\n\nPer progetti finanziati, appalti pubblici o PNRR puoi passare un oggetto opzionale `pa` con i riferimenti amministrativi. Tutti i campi sono opzionali; quelli passati finiscono nei `` della FatturaPA al momento dell'invio SDI.\n\n```php\nOnesto::createInvoiceManually([\n // ... cliente, articoli, scadenze ...\n\n 'pa' => [\n 'cig' => 'ZF3392A8B7',\n 'cups' => ['J53D23000170006', 'K12C24000050001'],\n 'numero_ordine' => 'ORD-2025-001',\n 'data_ordine' => '2025-04-15',\n 'impegno' => 'IMP-123',\n 'determina' => 'DET-456',\n 'codice_commessa' => 'COMM-789',\n ],\n]);\n```\n\n### Senza Facade (dependency injection)\n\n```php\nuse OnestoIt\\Sdk\\Onesto;\n\nclass FattureController\n{\n public function __construct(private Onesto $onesto) {}\n\n public function store()\n {\n return $this->onesto->createInvoiceManually([/* ... */]);\n }\n}\n```\n\nL'SDK è un thin wrapper sulle stesse API REST documentate nella sezione **API**: tutto ciò che puoi inviare via HTTP puoi inviarlo via SDK." } ], "components": { "securitySchemes": { "default": { "type": "http", "scheme": "bearer", "description": "Puoi creare e gestire i tuoi token API accedendo a https://app.onesto.it/company/integrations.

\nOgni richiesta alle API deve includere un'intestazione:\n\n
Authorization: Bearer {YOUR_API_TOKEN}
\n\nI token sono legati alla tua azienda e permettono di accedere alle relative risorse. Produzione e Sandbox hanno host e token separati: un token usato sull'host sbagliato riceve un 403 che indica quello giusto." } } }, "security": [ { "default": [] } ], "paths": { "/v1/accounts": { "get": { "summary": "Lista account", "operationId": "listaAccount", "description": "Ritorna gli account gestiti dal token (tutti i clienti dello studio, o la\nsingola company). Paginato.", "parameters": [ { "in": "query", "name": "page", "description": "Numero pagina.", "example": 1, "required": false, "schema": { "type": "integer", "description": "Numero pagina.", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Elementi per pagina (max 100).", "example": 100, "required": false, "schema": { "type": "integer", "description": "Elementi per pagina (max 100).", "example": 100, "nullable": false } }, { "in": "query", "name": "updated_since", "description": "ISO8601: solo account aggiornati da allora.", "example": "2026-07-01T00:00:00+02:00", "required": false, "schema": { "type": "string", "description": "ISO8601: solo account aggiornati da allora.", "example": "2026-07-01T00:00:00+02:00", "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "id": "12", "name": "TRUE SOLUTIONS S.R.L.", "vat_number": "14288140966", "fiscal_code": "14288140966", "status": "active" } ], "meta": { "page": 1, "per_page": 100, "total": 1, "next_page": null } }, "properties": { "data": { "type": "array", "example": [ { "id": "12", "name": "TRUE SOLUTIONS S.R.L.", "vat_number": "14288140966", "fiscal_code": "14288140966", "status": "active" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "name": { "type": "string", "example": "TRUE SOLUTIONS S.R.L." }, "vat_number": { "type": "string", "example": "14288140966" }, "fiscal_code": { "type": "string", "example": "14288140966" }, "status": { "type": "string", "example": "active" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 1 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "Aziende" ] } }, "/v1/accounts/{id}": { "get": { "summary": "Dettaglio account", "operationId": "dettaglioAccount", "description": "", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "id": "12", "name": "TRUE SOLUTIONS S.R.L.", "vat_number": "14288140966", "fiscal_code": "14288140966", "status": "active" } }, "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "name": { "type": "string", "example": "TRUE SOLUTIONS S.R.L." }, "vat_number": { "type": "string", "example": "14288140966" }, "fiscal_code": { "type": "string", "example": "14288140966" }, "status": { "type": "string", "example": "active" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "not_found", "message": "Account not found" } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Account not found" } } } } } } } } }, "tags": [ "Aziende" ] }, "parameters": [ { "in": "path", "name": "id", "description": "ID account.", "example": "12", "required": true, "schema": { "type": "string" } } ] }, "/clients": { "get": { "summary": "Lista clienti", "operationId": "listaClienti", "description": "Elenca i clienti dell'azienda in forma paginata, con ricerca opzionale su\nnome e Partita IVA (`q`). Restituisce l'anagrafica completa (indirizzo,\ncodice SDI, PEC): i dati sono pronti per compilare il blocco `cliente`\ndella creazione fattura senza ulteriori richieste.", "parameters": [ { "in": "query", "name": "q", "description": "Ricerca su nome o P.IVA.", "example": "acme", "required": false, "schema": { "type": "string", "description": "Ricerca su nome o P.IVA.", "example": "acme", "nullable": false } }, { "in": "query", "name": "page", "description": "Pagina (default 1).", "example": 1, "required": false, "schema": { "type": "integer", "description": "Pagina (default 1).", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Elementi per pagina, max 100 (default 50).", "example": 50, "required": false, "schema": { "type": "integer", "description": "Elementi per pagina, max 100 (default 50).", "example": 50, "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": [ { "id": 1, "name": "ACME Srl", "piva": "01234567890", "codice_fiscale": null, "sdi": "ABCDEFG", "pec": "acme@pec.it", "address": "Via Roma 1", "cap": "20121", "city": "Milano", "province": "MI", "country": "IT", "created_at": "2026-01-15" } ], "meta": { "page": 1, "per_page": 50, "total": 1, "next_page": null } }, "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "example": [ { "id": 1, "name": "ACME Srl", "piva": "01234567890", "codice_fiscale": null, "sdi": "ABCDEFG", "pec": "acme@pec.it", "address": "Via Roma 1", "cap": "20121", "city": "Milano", "province": "MI", "country": "IT", "created_at": "2026-01-15" } ], "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "ACME Srl" }, "piva": { "type": "string", "example": "01234567890" }, "codice_fiscale": { "type": "string", "example": null }, "sdi": { "type": "string", "example": "ABCDEFG" }, "pec": { "type": "string", "example": "acme@pec.it" }, "address": { "type": "string", "example": "Via Roma 1" }, "cap": { "type": "string", "example": "20121" }, "city": { "type": "string", "example": "Milano" }, "province": { "type": "string", "example": "MI" }, "country": { "type": "string", "example": "IT" }, "created_at": { "type": "string", "example": "2026-01-15" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 1 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "Clienti" ] } }, "/clients/store/manual": { "post": { "summary": "Crea cliente (manuale)", "operationId": "creaClientemanuale", "description": "Crea un nuovo cliente specificando manualmente i dati anagrafici. Utile\nper clienti esteri o senza Partita IVA italiana. Se la P.IVA indicata è\ngià presente in anagrafica risponde 409 con il cliente esistente.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "id": 1, "name": "Mario Rossi", "email": "mario@example.com" } }, "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Mario Rossi" }, "email": { "type": "string", "example": "mario@example.com" } } } } } } } } }, "tags": [ "Clienti" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Nome del cliente.", "example": "architecto", "nullable": false }, "domain": { "type": "string", "description": "Il campo value non può superare 255 caratteri.", "example": "n", "nullable": true }, "email": { "type": "string", "description": "Email del cliente.", "example": "gbailey@example.net", "nullable": true }, "phone": { "type": "string", "description": "Telefono.", "example": "architecto", "nullable": true }, "address": { "type": "string", "description": "Indirizzo.", "example": "architecto", "nullable": true }, "cap": { "type": "string", "description": "CAP.", "example": "architecto", "nullable": true }, "city": { "type": "string", "description": "Città.", "example": "architecto", "nullable": true }, "province": { "type": "string", "description": "Provincia.", "example": "architecto", "nullable": true }, "country": { "type": "string", "description": "default: IT.", "example": "architecto", "nullable": true }, "piva": { "type": "string", "description": "Partita IVA.", "example": "architecto", "nullable": true }, "sdi": { "type": "string", "description": "Codice SDI.", "example": "architecto", "nullable": true }, "pec": { "type": "string", "description": "PEC.", "example": "architecto", "nullable": true } }, "required": [ "name" ] } } } } } }, "/clients/store/automatic": { "post": { "summary": "Crea cliente da P.IVA", "operationId": "creaClienteDaPIVA", "description": "Crea un nuovo cliente recuperando automaticamente i dati anagrafici\n(ragione sociale, indirizzo, comune) dal registro imprese a partire dalla\nPartita IVA italiana. Basta la sola P.IVA, a tutto il resto pensa Onesto.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "name": "Azienda SRL", "piva": "01234567890", "city": "Roma" } }, "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "name": { "type": "string", "example": "Azienda SRL" }, "piva": { "type": "string", "example": "01234567890" }, "city": { "type": "string", "example": "Roma" } } } } } } } } }, "tags": [ "Clienti" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piva": { "type": "string", "description": "Partita IVA valida italiana.", "example": "architecto", "nullable": true } }, "required": [ "piva" ] } } } } } }, "/fatture/nuova/manuale": { "post": { "summary": "Crea fattura (manuale)", "operationId": "creaFatturamanuale", "description": "Crea una nuova fattura elettronica specificando tutti i dati via API:\ncliente, numerazione, articoli, eventuali scadenze di pagamento e invio a SDI\n(`invia_sdi`, default attivo). I valori di `numerazione` e `metodo_pagamento`\nsono i NOMI restituiti da `GET /fatture/numerazioni` e\n`GET /fatture/metodi-pagamento`. Valorizzando `paid` viene registrato\nsubito un incasso pari all'importo indicato.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "id": 123, "url": "https://fatture.onesto.it/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pdf" }, "properties": { "id": { "type": "integer", "example": 123 }, "url": { "type": "string", "example": "https://fatture.onesto.it/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pdf" } } } } } } }, "tags": [ "Fatture" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cliente": { "type": "object", "description": "", "nullable": false, "properties": { "name": { "type": "string", "description": "Nome del cliente.", "example": "architecto", "nullable": false }, "piva": { "type": "string", "description": "Partita IVA del cliente.", "example": "architecto", "nullable": false }, "address": { "type": "string", "description": "Indirizzo del cliente.", "example": "architecto", "nullable": false }, "cap": { "type": "string", "description": "CAP del cliente.", "example": "architecto", "nullable": false }, "city": { "type": "string", "description": "Città del cliente.", "example": "architecto", "nullable": false }, "province": { "type": "string", "description": "Provincia del cliente.", "example": "architecto", "nullable": true }, "country": { "type": "string", "description": "default: IT Paese del cliente.", "example": "architecto", "nullable": false }, "sdi": { "type": "string", "description": "nullable Codice SDI del cliente.", "example": "architecto", "nullable": true }, "pec": { "type": "string", "description": "nullable PEC del cliente.", "example": "architecto", "nullable": true }, "email": { "type": "string", "description": "nullable Email del cliente.", "example": "gbailey@example.net", "nullable": true }, "phone": { "type": "string", "description": "nullable Telefono del cliente.", "example": "architecto", "nullable": true } }, "required": [ "name", "piva", "address", "cap", "city" ] }, "numerazione": { "type": "string", "description": "Nome della numerazione da usare.", "example": "architecto", "nullable": false }, "issue_date": { "type": "string", "description": "Data di emissione fattura (YYYY-MM-DD).", "example": "architecto", "nullable": false, "format": "date" }, "tipo_documento": { "type": "string", "description": "in:TD01,TD01_ACC,TD24,TD25 Tipo di documento.", "example": "architecto", "nullable": true }, "sconto": { "type": "number", "description": "nullable Sconto globale (importo).", "example": 4326.41688, "nullable": true }, "intestazione": { "type": "string", "description": "nullable Testo da inserire nelle note di intestazione.", "example": "architecto", "nullable": true }, "note": { "type": "string", "description": "nullable Note aggiuntive.", "example": "architecto", "nullable": true }, "metodo_pagamento": { "type": "string", "description": "Nome del metodo di pagamento.", "example": "architecto", "nullable": false }, "paid": { "type": "number", "description": "nullable Importo già incassato (se presente, viene creato un pagamento).", "example": 4326.41688, "nullable": true }, "articoli": { "type": "array", "description": "Elenco degli articoli.", "example": [ "architecto" ], "items": { "type": "string" } }, "natura": { "type": "string", "description": "nullable Codice natura IVA globale per la fattura. Se omesso, viene determinata automaticamente in base al cliente e regime fiscale.", "example": "architecto", "nullable": true }, "scadenze": { "type": "array", "description": "nullable Scadenze di pagamento (se omesso, 30gg da issue_date).", "example": [ "architecto" ], "items": { "type": "string", "nullable": true } }, "invia_sdi": { "type": "boolean", "description": "default:true Se inviare la fattura al SDI.", "example": false, "nullable": true }, "emails": { "type": "array", "description": "nullable Altre email a cui inviare la fattura.", "example": [ "info@azienda.it", "contabilita@azienda.it" ], "items": { "type": "string" } }, "pa": { "type": "object", "description": "nullable Riferimenti Pubblica Amministrazione: SOLO CIG e CUP. Obbligatori (se la PA li richiede) per fatture verso Pubblica Amministrazione su progetti finanziati, appalti pubblici, PNRR. Finiscono nei `` della FatturaPA al momento dell'invio SDI.", "nullable": true, "properties": { "cig": { "type": "string", "description": "nullable Codice Identificativo Gara (max 15 chars).", "example": "ZF3392A8B7", "nullable": true }, "cup": { "type": "string", "description": "nullable Codice Unico Progetto singolo (max 15 chars). Per fatture con più CUP usa `pa.cups`.", "example": "J53D23000170006", "nullable": true }, "cups": { "type": "array", "description": "nullable Lista di Codici Unico Progetto (max 15 chars ciascuno). Se passato, prevale su `pa.cup`.", "example": [ "J53D23000170006", "K12C24000050001" ], "items": { "type": "string" } } } }, "ordine": { "type": "object", "description": "nullable Riferimenti all'ordine d'acquisto. Validi anche fuori dalla PA (B2B), ma vanno comunque nei `` della FatturaPA insieme a CIG/CUP. Tutti opzionali.", "nullable": true, "properties": { "numero": { "type": "string", "description": "nullable Numero ordine (max 20 chars).", "example": "ORD-2025-001", "nullable": true }, "data": { "type": "string", "description": "nullable Data dell'ordine (YYYY-MM-DD).", "example": "2025-04-15", "nullable": true, "format": "date" }, "impegno": { "type": "string", "description": "nullable Impegno di spesa (max 100 chars).", "example": "IMP-123", "nullable": true }, "determina": { "type": "string", "description": "nullable Determina / commessa (max 100 chars).", "example": "DET-456", "nullable": true }, "codice_commessa": { "type": "string", "description": "nullable Codice commessa / convenzione (max 100 chars).", "example": "COMM-789", "nullable": true } } } }, "required": [ "numerazione", "issue_date", "metodo_pagamento", "articoli" ] } } } } } }, "/fatture/nuova/piva": { "post": { "summary": "Crea fattura da P.IVA", "operationId": "creaFatturaDaPIVA", "description": "Crea una nuova fattura elettronica recuperando automaticamente i dati del\ncliente dalla Partita IVA (lookup sul registro imprese). Numerazione, data\ne metodo di pagamento sono opzionali: se omessi vengono usati i default\ndell'azienda. Ideale per emettere una fattura conoscendo solo la P.IVA\ndel cliente e gli articoli.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": { "id": 124, "url": "https://fatture.onesto.it/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pdf" } }, "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "integer", "example": 124 }, "url": { "type": "string", "example": "https://fatture.onesto.it/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pdf" } } } } } } } } }, "tags": [ "Fatture" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "piva": { "type": "string", "description": "Partita IVA (con o senza prefisso \"IT\").", "example": "03666510791", "nullable": false }, "numerazione": { "type": "string", "description": "nullable Nome della numerazione da usare. Default: Standard.", "example": "Standard", "nullable": true }, "issue_date": { "type": "string", "description": "nullable Data di emissione fattura (YYYY-MM-DD). Default: oggi.", "example": "2025-04-29", "nullable": true, "format": "date" }, "tipo_documento": { "type": "string", "description": "in:TD01,TD01_ACC,TD24,TD25 nullable Tipo di documento. Default: TD01.", "example": "TD01", "nullable": true }, "metodo_pagamento": { "type": "string", "description": "nullable Nome del metodo di pagamento. Default: ultimo usato.", "example": "Revolut Pro", "nullable": true }, "sconto": { "type": "number", "description": "nullable Sconto globale (importo in Euro).", "example": 20.5, "nullable": true }, "intestazione": { "type": "string", "description": "nullable Testo di intestazione.", "example": "Intestazione personalizzata", "nullable": true }, "note": { "type": "string", "description": "nullable Note aggiuntive.", "example": "Grazie per averci scelto", "nullable": true }, "invia_sdi": { "type": "boolean", "description": "default:true Se inviare la fattura allo SDI.", "example": true, "nullable": true }, "emails": { "type": "array", "description": "nullable Altre email a cui inviare la fattura.", "example": [ "info@azienda.it", "contabilita@azienda.it" ], "items": { "type": "string" } }, "articoli": { "type": "array", "description": "Elenco degli articoli.", "example": [ { "nome": "Consulenza informatica", "quantita": 22, "prezzo": 150, "iva": 0, "descrizione": "Consulenza Maggio 2025" } ], "items": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome articolo.", "example": "Consulenza informatica", "nullable": false }, "quantita": { "type": "number", "description": "Quantità.", "example": 22, "nullable": false }, "prezzo": { "type": "number", "description": "Prezzo unitario.", "example": 150, "nullable": false }, "iva": { "type": "number", "description": "Aliquota IVA (%).", "example": 0, "nullable": false }, "descrizione": { "type": "string", "description": "nullable Descrizione articolo.", "example": "Consulenza Maggio 2025", "nullable": false } }, "required": [ "nome", "quantita", "prezzo", "iva" ] } }, "scadenze": { "type": "array", "description": "nullable Scadenze di pagamento (se omesso, 30gg da issue_date).", "example": [ { "date": "2025-05-30", "value": 50, "type": "percent" }, { "date": "2025-06-30", "value": 50, "type": "percent" } ], "items": { "type": "object", "nullable": true, "properties": { "date": { "type": "string", "description": "Data scadenza (YYYY-MM-DD).", "example": "2025-05-30", "nullable": false, "format": "date" }, "value": { "type": "number", "description": "Importo (o percentuale se type = percent).", "example": 50, "nullable": false }, "type": { "type": "string", "description": "in:percent,amount required Tipo di valore.", "example": "percent", "nullable": false } }, "required": [ "date", "value" ] } }, "pa": { "type": "object", "description": "nullable Riferimenti Pubblica Amministrazione: SOLO CIG e CUP. Obbligatori (se la PA li richiede) per fatture verso Pubblica Amministrazione su progetti finanziati, appalti pubblici, PNRR. Finiscono nei `` della FatturaPA al momento dell'invio SDI.", "nullable": true, "properties": { "cig": { "type": "string", "description": "nullable Codice Identificativo Gara (max 15 chars).", "example": "ZF3392A8B7", "nullable": true }, "cup": { "type": "string", "description": "nullable Codice Unico Progetto singolo (max 15 chars). Per fatture con più CUP usa `pa.cups`.", "example": "J53D23000170006", "nullable": true }, "cups": { "type": "array", "description": "nullable Lista di Codici Unico Progetto (max 15 chars ciascuno). Se passato, prevale su `pa.cup`.", "example": [ "J53D23000170006", "K12C24000050001" ], "items": { "type": "string" } } } }, "ordine": { "type": "object", "description": "nullable Riferimenti all'ordine d'acquisto. Validi anche fuori dalla PA (B2B), ma vanno comunque nei `` della FatturaPA insieme a CIG/CUP. Tutti opzionali.", "nullable": true, "properties": { "numero": { "type": "string", "description": "nullable Numero ordine (max 20 chars).", "example": "ORD-2025-001", "nullable": true }, "data": { "type": "string", "description": "nullable Data dell'ordine (YYYY-MM-DD).", "example": "2025-04-15", "nullable": true, "format": "date" }, "impegno": { "type": "string", "description": "nullable Impegno di spesa (max 100 chars).", "example": "IMP-123", "nullable": true }, "determina": { "type": "string", "description": "nullable Determina / commessa (max 100 chars).", "example": "DET-456", "nullable": true }, "codice_commessa": { "type": "string", "description": "nullable Codice commessa / convenzione (max 100 chars).", "example": "COMM-789", "nullable": true } } } }, "required": [ "piva", "articoli" ] } } } } } }, "/fatture/numerazioni": { "get": { "summary": "Lista numerazioni", "operationId": "listaNumerazioni", "description": "Elenca le numerazioni attive dell'azienda, con l'eventuale metodo di\npagamento di default di ciascuna. I nomi restituiti sono i valori accettati\ndal campo `numerazione` degli endpoint di creazione fattura: usa questo\nendpoint per popolare i selettori nei client esterni invece di chiedere\nall'utente di digitare il nome a memoria.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": [ { "id": 1, "name": "Principale", "type": "standard", "default_payment_method": "Bonifico bancario" } ] }, "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "example": [ { "id": 1, "name": "Principale", "type": "standard", "default_payment_method": "Bonifico bancario" } ], "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Principale" }, "type": { "type": "string", "example": "standard" }, "default_payment_method": { "type": "string", "example": "Bonifico bancario" } } } } } } } } } }, "tags": [ "Fatture" ] } }, "/fatture/metodi-pagamento": { "get": { "summary": "Lista metodi di pagamento", "operationId": "listaMetodiDiPagamento", "description": "Elenca i metodi di pagamento utilizzabili in fattura, con IBAN e codice SDI.\nI nomi restituiti sono i valori accettati dal campo `metodo_pagamento` degli\nendpoint di creazione fattura e di registrazione incassi. I conti interni\n(pocket/sotto-conti) non compaiono: non sono metodi di incasso.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "data": [ { "id": 3, "name": "Bonifico bancario", "type": "Bonifico", "iban": "IT60X0542811101000000123456", "sdi_code": "MP05" } ] }, "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "example": [ { "id": 3, "name": "Bonifico bancario", "type": "Bonifico", "iban": "IT60X0542811101000000123456", "sdi_code": "MP05" } ], "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Bonifico bancario" }, "type": { "type": "string", "example": "Bonifico" }, "iban": { "type": "string", "example": "IT60X0542811101000000123456" }, "sdi_code": { "type": "string", "example": "MP05" } } } } } } } } } }, "tags": [ "Fatture" ] } }, "/fatture/{uuid}/pagamenti": { "post": { "summary": "Registra incasso", "operationId": "registraIncasso", "description": "Registra un pagamento ricevuto su una fattura esistente, identificata dallo\n`uuid` (restituito dalla creazione e da `GET /v1/invoices`). L'importo non\npuò superare il residuo da incassare; la risposta include il nuovo stato\n(`paid`/`partial`/`unpaid`) e il residuo aggiornato. Note di credito (TD04)\ne documenti fiscalmente nulli (bozze/scartate/errore) non accettano incassi.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": true, "payment": { "id": 77, "amount": 500, "payment_date": "2026-07-21" }, "invoice": { "uuid": "9f8b6c1e-0000-0000-0000-000000000000", "number": "2026/145", "total": 1220, "amount_paid": 500, "amount_due": 720, "payment_status": "partial" } }, "properties": { "success": { "type": "boolean", "example": true }, "payment": { "type": "object", "properties": { "id": { "type": "integer", "example": 77 }, "amount": { "type": "number", "example": 500 }, "payment_date": { "type": "string", "example": "2026-07-21" } } }, "invoice": { "type": "object", "properties": { "uuid": { "type": "string", "example": "9f8b6c1e-0000-0000-0000-000000000000" }, "number": { "type": "string", "example": "2026/145" }, "total": { "type": "number", "example": 1220 }, "amount_paid": { "type": "number", "example": 500 }, "amount_due": { "type": "number", "example": 720 }, "payment_status": { "type": "string", "example": "partial" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": false, "errors": [ { "message": "Fattura non trovata" } ] }, "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "example": [ { "message": "Fattura non trovata" } ], "items": { "type": "object", "properties": { "message": { "type": "string", "example": "Fattura non trovata" } } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "success": false, "errors": [ { "message": "L'importo supera il residuo da incassare (720.00)" } ] }, "properties": { "success": { "type": "boolean", "example": false }, "errors": { "type": "array", "example": [ { "message": "L'importo supera il residuo da incassare (720.00)" } ], "items": { "type": "object", "properties": { "message": { "type": "string", "example": "L'importo supera il residuo da incassare (720.00)" } } } } } } } } } }, "tags": [ "Fatture" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "number", "description": "Importo incassato (max: residuo).", "example": 500, "nullable": false }, "payment_date": { "type": "string", "description": "Data incasso (YYYY-MM-DD, default oggi).", "example": "2026-07-21", "nullable": true }, "metodo_pagamento": { "type": "string", "description": "Nome del metodo di pagamento (vedi GET /fatture/metodi-pagamento).", "example": "Bonifico bancario", "nullable": true }, "note": { "type": "string", "description": "Nota libera (max 500 caratteri).", "example": "Bonifico ricevuto", "nullable": true } }, "required": [ "amount" ] } } } } }, "parameters": [ { "in": "path", "name": "uuid", "description": "UUID della fattura.", "example": "9f8b6c1e-0000-0000-0000-000000000000", "required": true, "schema": { "type": "string" } } ] }, "/v1/invoices": { "get": { "summary": "Lista fatture", "operationId": "listaFatture", "description": "Oltre allo stato SdI, ogni fattura espone lo stato di incasso: `payment_status`\n(`paid`/`partial`/`unpaid`, `null` per note di credito e documenti fiscalmente\nnulli), `amount_paid`, `amount_due`, `due_date` (ultima scadenza di pagamento)\ne `overdue`. Per le fatture attive sono inclusi anche `uuid` e `pdf_url`.", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per account.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per account.", "example": "12", "nullable": false } }, { "in": "query", "name": "direction", "description": "`outbound` (attive, default) o `inbound` (passive).", "example": "outbound", "required": false, "schema": { "type": "string", "description": "`outbound` (attive, default) o `inbound` (passive).", "example": "outbound", "nullable": false } }, { "in": "query", "name": "sdi_status", "description": "Lista separata da virgole (spec): queued,sent,delivered,accepted,rejected,error,failed_delivery.", "example": "rejected,error", "required": false, "schema": { "type": "string", "description": "Lista separata da virgole (spec): queued,sent,delivered,accepted,rejected,error,failed_delivery.", "example": "rejected,error", "nullable": false } }, { "in": "query", "name": "payment_status", "description": "Lista separata da virgole: paid,partial,unpaid,overdue (overdue = non saldata con ultima scadenza passata, solo outbound). Il filtro esclude automaticamente note di credito e di debito (TD04/TD05) e documenti fiscalmente nulli.", "example": "unpaid,partial", "required": false, "schema": { "type": "string", "description": "Lista separata da virgole: paid,partial,unpaid,overdue (overdue = non saldata con ultima scadenza passata, solo outbound). Il filtro esclude automaticamente note di credito e di debito (TD04/TD05) e documenti fiscalmente nulli.", "example": "unpaid,partial", "nullable": false } }, { "in": "query", "name": "updated_since", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "required": false, "schema": { "type": "string", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "nullable": false } }, { "in": "query", "name": "page", "description": "", "example": 1, "required": false, "schema": { "type": "integer", "description": "", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Max 100.", "example": 100, "required": false, "schema": { "type": "integer", "description": "Max 100.", "example": 100, "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "id": "123", "account_id": "12", "direction": "outbound", "number": "2026/145", "issue_date": "2026-07-02", "counterpart": { "name": "ACME Srl", "vat_number": "01234567890" }, "total_amount": 1220, "payment_status": "unpaid", "amount_paid": 0, "amount_due": 1220, "due_date": "2026-07-31", "overdue": false, "sdi_status": "delivered", "sdi_error": null, "last_sdi_update": "2026-07-02T10:12:00+02:00", "uuid": "9f8b6c1e-0000-0000-0000-000000000000", "pdf_url": "https://fatture.onesto.it/9f8b6c1e-0000-0000-0000-000000000000/pdf", "url": "https://app.onesto.it/fatture" } ], "meta": { "page": 1, "per_page": 100, "total": 1, "next_page": null } }, "properties": { "data": { "type": "array", "example": [ { "id": "123", "account_id": "12", "direction": "outbound", "number": "2026/145", "issue_date": "2026-07-02", "counterpart": { "name": "ACME Srl", "vat_number": "01234567890" }, "total_amount": 1220, "payment_status": "unpaid", "amount_paid": 0, "amount_due": 1220, "due_date": "2026-07-31", "overdue": false, "sdi_status": "delivered", "sdi_error": null, "last_sdi_update": "2026-07-02T10:12:00+02:00", "uuid": "9f8b6c1e-0000-0000-0000-000000000000", "pdf_url": "https://fatture.onesto.it/9f8b6c1e-0000-0000-0000-000000000000/pdf", "url": "https://app.onesto.it/fatture" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "123" }, "account_id": { "type": "string", "example": "12" }, "direction": { "type": "string", "example": "outbound" }, "number": { "type": "string", "example": "2026/145" }, "issue_date": { "type": "string", "example": "2026-07-02" }, "counterpart": { "type": "object", "properties": { "name": { "type": "string", "example": "ACME Srl" }, "vat_number": { "type": "string", "example": "01234567890" } } }, "total_amount": { "type": "number", "example": 1220 }, "payment_status": { "type": "string", "example": "unpaid" }, "amount_paid": { "type": "integer", "example": 0 }, "amount_due": { "type": "number", "example": 1220 }, "due_date": { "type": "string", "example": "2026-07-31" }, "overdue": { "type": "boolean", "example": false }, "sdi_status": { "type": "string", "example": "delivered" }, "sdi_error": { "type": "string", "example": null }, "last_sdi_update": { "type": "string", "example": "2026-07-02T10:12:00+02:00" }, "uuid": { "type": "string", "example": "9f8b6c1e-0000-0000-0000-000000000000" }, "pdf_url": { "type": "string", "example": "https://fatture.onesto.it/9f8b6c1e-0000-0000-0000-000000000000/pdf" }, "url": { "type": "string", "example": "https://app.onesto.it/fatture" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 1 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "Fatture" ] } }, "/v1/cost-centers": { "get": { "summary": "Lista centri di costo", "operationId": "listaCentriDiCosto", "description": "Di default include anche i centri disattivati, perché possono avere\nmovimenti storici da interpretare: filtra con `?attivo=1` per i soli\ncentri utilizzabili oggi.", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per azienda.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per azienda.", "example": "12", "nullable": false } }, { "in": "query", "name": "attivo", "description": "Solo i centri attivi.", "example": true, "required": false, "schema": { "type": "boolean", "description": "Solo i centri attivi.", "example": true, "nullable": false } }, { "in": "query", "name": "tipo", "description": "cliente, prodotto, commessa, sede.", "example": "cliente", "required": false, "schema": { "type": "string", "description": "cliente, prodotto, commessa, sede.", "example": "cliente", "nullable": false } }, { "in": "query", "name": "page", "description": "", "example": 1, "required": false, "schema": { "type": "integer", "description": "", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Max 100.", "example": 100, "required": false, "schema": { "type": "integer", "description": "Max 100.", "example": 100, "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "id": "7", "account_id": "12", "code": "GLOVE", "nome": "Glove ICT", "tipo": "cliente", "client_id": "42", "attivo": true, "created_at": "2026-08-30T10:00:00+02:00" } ], "meta": { "page": 1, "per_page": 100, "total": 1, "next_page": null } }, "properties": { "data": { "type": "array", "example": [ { "id": "7", "account_id": "12", "code": "GLOVE", "nome": "Glove ICT", "tipo": "cliente", "client_id": "42", "attivo": true, "created_at": "2026-08-30T10:00:00+02:00" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "7" }, "account_id": { "type": "string", "example": "12" }, "code": { "type": "string", "example": "GLOVE" }, "nome": { "type": "string", "example": "Glove ICT" }, "tipo": { "type": "string", "example": "cliente" }, "client_id": { "type": "string", "example": "42" }, "attivo": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2026-08-30T10:00:00+02:00" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 1 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "Spese" ] } }, "/v1/expenses": { "get": { "summary": "Lista spese classificate", "operationId": "listaSpeseClassificate", "description": "`allocation_method`: `diretto` (attribuibile a un centro), `personale`\n(retribuzioni e oneri), `struttura` (spese generali), `escluso` (fuori\ndall'attività). Una spesa senza metodo vale `struttura`.\n\n`cost_center_code` è sempre presente accanto all'id: mappa su quello, non\nsugli id numerici. Vale `UNASSIGNED` con `needs_review: true` quando la\nspesa è marcata `diretto` ma il centro non è stato indicato — così quei\ncosti si vedono invece di finire silenziosamente in un altro totale.", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per azienda.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per azienda.", "example": "12", "nullable": false } }, { "in": "query", "name": "periodo", "description": "Mese di competenza YYYY-MM.", "example": "2026-09", "required": false, "schema": { "type": "string", "description": "Mese di competenza YYYY-MM.", "example": "2026-09", "nullable": false } }, { "in": "query", "name": "periodo_da", "description": "Da (YYYY-MM).", "example": "2026-01", "required": false, "schema": { "type": "string", "description": "Da (YYYY-MM).", "example": "2026-01", "nullable": false } }, { "in": "query", "name": "periodo_a", "description": "A (YYYY-MM).", "example": "2026-12", "required": false, "schema": { "type": "string", "description": "A (YYYY-MM).", "example": "2026-12", "nullable": false } }, { "in": "query", "name": "method", "description": "diretto, personale, struttura, escluso.", "example": "diretto", "required": false, "schema": { "type": "string", "description": "diretto, personale, struttura, escluso.", "example": "diretto", "nullable": false } }, { "in": "query", "name": "cost_center", "description": "Codice (o id) del centro.", "example": "GLOVE", "required": false, "schema": { "type": "string", "description": "Codice (o id) del centro.", "example": "GLOVE", "nullable": false } }, { "in": "query", "name": "page", "description": "", "example": 1, "required": false, "schema": { "type": "integer", "description": "", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Max 100.", "example": 100, "required": false, "schema": { "type": "integer", "description": "Max 100.", "example": 100, "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "source": "expense", "id": "2210", "account_id": "12", "document_number": "FT 118", "document_date": "2026-08-20", "periodo_competenza": "2026-09", "allocation_method": "diretto", "cost_center_id": "7", "cost_center_code": "GLOVE", "needs_review": false, "employee_ref": null, "supplier": { "id": "77", "name": "Acme Energia S.p.A." }, "subtotal": "100.00", "vat": "22.00", "total": "122.00", "is_paid": false }, { "source": "payslip", "id": "41", "account_id": "12", "document_number": "Cedolino 2026-09", "document_date": "2026-09-01", "periodo_competenza": "2026-09", "allocation_method": "personale", "cost_center_id": null, "cost_center_code": null, "needs_review": false, "employee_ref": "RSSMRA80A01H501U", "supplier": null, "subtotal": "3480.00", "vat": "0.00", "total": "3480.00", "is_paid": true } ], "meta": { "page": 1, "per_page": 100, "total": 2, "next_page": null } }, "properties": { "data": { "type": "array", "example": [ { "source": "expense", "id": "2210", "account_id": "12", "document_number": "FT 118", "document_date": "2026-08-20", "periodo_competenza": "2026-09", "allocation_method": "diretto", "cost_center_id": "7", "cost_center_code": "GLOVE", "needs_review": false, "employee_ref": null, "supplier": { "id": "77", "name": "Acme Energia S.p.A." }, "subtotal": "100.00", "vat": "22.00", "total": "122.00", "is_paid": false }, { "source": "payslip", "id": "41", "account_id": "12", "document_number": "Cedolino 2026-09", "document_date": "2026-09-01", "periodo_competenza": "2026-09", "allocation_method": "personale", "cost_center_id": null, "cost_center_code": null, "needs_review": false, "employee_ref": "RSSMRA80A01H501U", "supplier": null, "subtotal": "3480.00", "vat": "0.00", "total": "3480.00", "is_paid": true } ], "items": { "type": "object", "properties": { "source": { "type": "string", "example": "expense" }, "id": { "type": "string", "example": "2210" }, "account_id": { "type": "string", "example": "12" }, "document_number": { "type": "string", "example": "FT 118" }, "document_date": { "type": "string", "example": "2026-08-20" }, "periodo_competenza": { "type": "string", "example": "2026-09" }, "allocation_method": { "type": "string", "example": "diretto" }, "cost_center_id": { "type": "string", "example": "7" }, "cost_center_code": { "type": "string", "example": "GLOVE" }, "needs_review": { "type": "boolean", "example": false }, "employee_ref": { "type": "string", "example": null }, "supplier": { "type": "object", "properties": { "id": { "type": "string", "example": "77" }, "name": { "type": "string", "example": "Acme Energia S.p.A." } } }, "subtotal": { "type": "string", "example": "100.00" }, "vat": { "type": "string", "example": "22.00" }, "total": { "type": "string", "example": "122.00" }, "is_paid": { "type": "boolean", "example": false } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 2 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "Spese" ] } }, "/v1/expenses/summary": { "get": { "summary": "Totali per metodo e per centro", "operationId": "totaliPerMetodoEPerCentro", "description": "I NON ASSEGNATI stanno in un blocco a parte e **non** entrano nei totali:\nchi consuma vede quanto è in sospeso invece di riceverlo dentro un altro\nnumero. Regola per chi fa il riparto: le non assegnate restano fuori dalla\nbase di costo finché non vengono classificate — meglio un importo in meno\nche un importo attribuito a caso.", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per azienda.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per azienda.", "example": "12", "nullable": false } }, { "in": "query", "name": "periodo", "description": "Mese di competenza YYYY-MM.", "example": "2026-09", "required": false, "schema": { "type": "string", "description": "Mese di competenza YYYY-MM.", "example": "2026-09", "nullable": false } }, { "in": "query", "name": "periodo_da", "description": "Da (YYYY-MM).", "example": "2026-01", "required": false, "schema": { "type": "string", "description": "Da (YYYY-MM).", "example": "2026-01", "nullable": false } }, { "in": "query", "name": "periodo_a", "description": "A (YYYY-MM).", "example": "2026-12", "required": false, "schema": { "type": "string", "description": "A (YYYY-MM).", "example": "2026-12", "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "periodo": "2026-09", "totali": { "diretto": "987.00", "personale": "15500.00", "struttura": "1500.00", "escluso": "0.00" }, "per_centro": [ { "cost_center_id": "7", "cost_center_code": "GLOVE", "nome": "Glove ICT", "totale": "987.00", "documenti": 3 } ], "non_assegnate": { "conteggio": 3, "importo": "420.00" } }, "properties": { "periodo": { "type": "string", "example": "2026-09" }, "totali": { "type": "object", "properties": { "diretto": { "type": "string", "example": "987.00" }, "personale": { "type": "string", "example": "15500.00" }, "struttura": { "type": "string", "example": "1500.00" }, "escluso": { "type": "string", "example": "0.00" } } }, "per_centro": { "type": "array", "example": [ { "cost_center_id": "7", "cost_center_code": "GLOVE", "nome": "Glove ICT", "totale": "987.00", "documenti": 3 } ], "items": { "type": "object", "properties": { "cost_center_id": { "type": "string", "example": "7" }, "cost_center_code": { "type": "string", "example": "GLOVE" }, "nome": { "type": "string", "example": "Glove ICT" }, "totale": { "type": "string", "example": "987.00" }, "documenti": { "type": "integer", "example": 3 } } } }, "non_assegnate": { "type": "object", "properties": { "conteggio": { "type": "integer", "example": 3 }, "importo": { "type": "string", "example": "420.00" } } } } } } } } }, "tags": [ "Spese" ] } }, "/v1/f24s": { "get": { "summary": "Lista F24", "operationId": "listaF24", "description": "Stato (`status`): `ready` = da pagare (pronto per il bonifico), `paid` = pagato,\n`expired` = scaduto non pagato, `cancelled` = annullato, `draft` = bozza da completare.", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per account.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per account.", "example": "12", "nullable": false } }, { "in": "query", "name": "status", "description": "Stato: draft, ready, paid, expired, cancelled.", "example": "ready", "required": false, "schema": { "type": "string", "description": "Stato: draft, ready, paid, expired, cancelled.", "example": "ready", "nullable": false } }, { "in": "query", "name": "due_date_from", "description": "date Scadenza da (YYYY-MM-DD).", "example": "2026-07-01", "required": false, "schema": { "type": "string", "description": "date Scadenza da (YYYY-MM-DD).", "example": "2026-07-01", "nullable": false } }, { "in": "query", "name": "due_date_to", "description": "date Scadenza a (YYYY-MM-DD).", "example": "2026-12-31", "required": false, "schema": { "type": "string", "description": "date Scadenza a (YYYY-MM-DD).", "example": "2026-12-31", "nullable": false } }, { "in": "query", "name": "updated_since", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "required": false, "schema": { "type": "string", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "nullable": false } }, { "in": "query", "name": "page", "description": "", "example": 1, "required": false, "schema": { "type": "integer", "description": "", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Max 100.", "example": 100, "required": false, "schema": { "type": "integer", "description": "Max 100.", "example": 100, "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "id": "9f8a...", "account_id": "12", "taxpayer": { "name": "TRUE SOLUTIONS S.R.L.", "vat_number": "14288140966", "fiscal_code": "14288140966" }, "description": "IVA Trimestrale 2026-Q2", "period": "2026-Q2", "due_date": "2026-08-20", "amount": 12554.23, "total_amount": 12554.23, "currency": "EUR", "status": "ready", "native_status": "PENDING", "payment_date": null, "payment_reference": null, "receipt_available": false, "file_url": "https://onesto-it.s3.eu-south-1.amazonaws.com/f24/...pdf?X-Amz-Signature=...", "url": "https://app.onesto.it/tasse" } ], "meta": { "page": 1, "per_page": 100, "total": 1, "next_page": null } }, "properties": { "data": { "type": "array", "example": [ { "id": "9f8a...", "account_id": "12", "taxpayer": { "name": "TRUE SOLUTIONS S.R.L.", "vat_number": "14288140966", "fiscal_code": "14288140966" }, "description": "IVA Trimestrale 2026-Q2", "period": "2026-Q2", "due_date": "2026-08-20", "amount": 12554.23, "total_amount": 12554.23, "currency": "EUR", "status": "ready", "native_status": "PENDING", "payment_date": null, "payment_reference": null, "receipt_available": false, "file_url": "https://onesto-it.s3.eu-south-1.amazonaws.com/f24/...pdf?X-Amz-Signature=...", "url": "https://app.onesto.it/tasse" } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "9f8a..." }, "account_id": { "type": "string", "example": "12" }, "taxpayer": { "type": "object", "properties": { "name": { "type": "string", "example": "TRUE SOLUTIONS S.R.L." }, "vat_number": { "type": "string", "example": "14288140966" }, "fiscal_code": { "type": "string", "example": "14288140966" } } }, "description": { "type": "string", "example": "IVA Trimestrale 2026-Q2" }, "period": { "type": "string", "example": "2026-Q2" }, "due_date": { "type": "string", "example": "2026-08-20" }, "amount": { "type": "number", "example": 12554.23 }, "total_amount": { "type": "number", "example": 12554.23 }, "currency": { "type": "string", "example": "EUR" }, "status": { "type": "string", "example": "ready" }, "native_status": { "type": "string", "example": "PENDING" }, "payment_date": { "type": "string", "example": null }, "payment_reference": { "type": "string", "example": null }, "receipt_available": { "type": "boolean", "example": false }, "file_url": { "type": "string", "example": "https://onesto-it.s3.eu-south-1.amazonaws.com/f24/...pdf?X-Amz-Signature=..." }, "url": { "type": "string", "example": "https://app.onesto.it/tasse" } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 1 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "F24" ] } }, "/v1/f24s/{id}": { "get": { "summary": "Dettaglio F24 (con sezioni tributi)", "operationId": "dettaglioF24conSezioniTributi", "description": "", "parameters": [], "responses": { "401": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "unauthorized", "message": "Invalid or expired token" } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "unauthorized" }, "message": { "type": "string", "example": "Invalid or expired token" } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "not_found", "message": "F24 not found" } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "F24 not found" } } } } } } } } }, "tags": [ "F24" ] }, "parameters": [ { "in": "path", "name": "id", "description": "UUID dell'F24.", "example": "9f8a...", "required": true, "schema": { "type": "string" } } ] }, "/v1/tax-deadlines": { "get": { "summary": "Lista scadenze fiscali", "operationId": "listaScadenzeFiscali", "description": "", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per account.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per account.", "example": "12", "nullable": false } }, { "in": "query", "name": "type", "description": "f24, lipe, iva, dichiarazione, inps, other.", "example": "iva", "required": false, "schema": { "type": "string", "description": "f24, lipe, iva, dichiarazione, inps, other.", "example": "iva", "nullable": false } }, { "in": "query", "name": "status", "description": "upcoming, due_today, overdue, done.", "example": "overdue", "required": false, "schema": { "type": "string", "description": "upcoming, due_today, overdue, done.", "example": "overdue", "nullable": false } }, { "in": "query", "name": "due_date_from", "description": "date YYYY-MM-DD.", "example": "2026-07-01", "required": false, "schema": { "type": "string", "description": "date YYYY-MM-DD.", "example": "2026-07-01", "nullable": false } }, { "in": "query", "name": "due_date_to", "description": "date YYYY-MM-DD.", "example": "2026-12-31", "required": false, "schema": { "type": "string", "description": "date YYYY-MM-DD.", "example": "2026-12-31", "nullable": false } }, { "in": "query", "name": "updated_since", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "required": false, "schema": { "type": "string", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "nullable": false } }, { "in": "query", "name": "page", "description": "", "example": 1, "required": false, "schema": { "type": "integer", "description": "", "example": 1, "nullable": false } }, { "in": "query", "name": "per_page", "description": "Max 100.", "example": 100, "required": false, "schema": { "type": "integer", "description": "Max 100.", "example": 100, "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "id": "55", "account_id": "12", "type": "iva", "title": "IVA Trimestrale 2026-Q2", "due_date": "2026-08-20", "amount": 12554.23, "status": "upcoming", "related_resource": { "type": "f24", "id": "9f8a..." } } ], "meta": { "page": 1, "per_page": 100, "total": 1, "next_page": null } }, "properties": { "data": { "type": "array", "example": [ { "id": "55", "account_id": "12", "type": "iva", "title": "IVA Trimestrale 2026-Q2", "due_date": "2026-08-20", "amount": 12554.23, "status": "upcoming", "related_resource": { "type": "f24", "id": "9f8a..." } } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "55" }, "account_id": { "type": "string", "example": "12" }, "type": { "type": "string", "example": "iva" }, "title": { "type": "string", "example": "IVA Trimestrale 2026-Q2" }, "due_date": { "type": "string", "example": "2026-08-20" }, "amount": { "type": "number", "example": 12554.23 }, "status": { "type": "string", "example": "upcoming" }, "related_resource": { "type": "object", "properties": { "type": { "type": "string", "example": "f24" }, "id": { "type": "string", "example": "9f8a..." } } } } } }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 1 }, "next_page": { "type": "string", "example": null } } } } } } } } }, "tags": [ "Scadenze fiscali" ] } }, "/v1/receipts-uploads": { "get": { "summary": "Stato corrispettivi", "operationId": "statoCorrispettivi", "description": "", "parameters": [ { "in": "query", "name": "account_id", "description": "Filtra per account.", "example": "12", "required": false, "schema": { "type": "string", "description": "Filtra per account.", "example": "12", "nullable": false } }, { "in": "query", "name": "updated_since", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "required": false, "schema": { "type": "string", "description": "ISO8601 incrementale.", "example": "2026-07-01T00:00:00+02:00", "nullable": false } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [], "meta": { "page": 1, "per_page": 100, "total": 0, "next_page": null, "supported": false, "note": "Corrispettivi non gestiti da Onesto" } }, "properties": { "data": { "type": "array", "example": [] }, "meta": { "type": "object", "properties": { "page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 0 }, "next_page": { "type": "string", "example": null }, "supported": { "type": "boolean", "example": false }, "note": { "type": "string", "example": "Corrispettivi non gestiti da Onesto" } } } } } } } } }, "tags": [ "Corrispettivi" ] } }, "/v1/me": { "get": { "summary": "Prova credenziali", "operationId": "provaCredenziali", "description": "Dice a chi possiede la chiave quale azienda vede, cosa può fare e se\nquesta installazione consegna webhook. Zapier e n8n lo chiamano appena\nl'utente incolla la chiave, per dare subito un errore comprensibile\ninvece di fallire più tardi su un endpoint qualsiasi.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "token_type": "api_token", "company": { "id": "12", "name": "TRUE SOLUTIONS S.R.L.", "vat_number": "14288140966" }, "accounts_count": 1, "abilities": [ "invoices:read", "webhooks:manage" ], "full_access": false, "webhooks_supported": true, "webhooks_ready": true } }, "properties": { "data": { "type": "object", "properties": { "token_type": { "type": "string", "example": "api_token" }, "company": { "type": "object", "properties": { "id": { "type": "string", "example": "12" }, "name": { "type": "string", "example": "TRUE SOLUTIONS S.R.L." }, "vat_number": { "type": "string", "example": "14288140966" } } }, "accounts_count": { "type": "integer", "example": 1 }, "abilities": { "type": "array", "example": [ "invoices:read", "webhooks:manage" ], "items": { "type": "string" } }, "full_access": { "type": "boolean", "example": false }, "webhooks_supported": { "type": "boolean", "example": true }, "webhooks_ready": { "type": "boolean", "example": true } } } } } } } } }, "tags": [ "Automazioni e webhook" ] } }, "/v1/events": { "get": { "summary": "Catalogo eventi", "operationId": "catalogoEventi", "description": "Elenco degli eventi a cui ci si può sottoscrivere. Zapier e n8n lo usano\nper popolare il menu dei trigger: la chiave è il valore da passare in\n`events`, l'etichetta è quella da mostrare all'utente.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "key": "invoice.created", "label": "Fattura emessa", "description": "Una nuova fattura è stata creata (bozze escluse).", "category": "Fatture" } ] }, "properties": { "data": { "type": "array", "example": [ { "key": "invoice.created", "label": "Fattura emessa", "description": "Una nuova fattura è stata creata (bozze escluse).", "category": "Fatture" } ], "items": { "type": "object", "properties": { "key": { "type": "string", "example": "invoice.created" }, "label": { "type": "string", "example": "Fattura emessa" }, "description": { "type": "string", "example": "Una nuova fattura è stata creata (bozze escluse)." }, "category": { "type": "string", "example": "Fatture" } } } } } } } } } }, "tags": [ "Automazioni e webhook" ] } }, "/v1/events/{event}/sample": { "get": { "summary": "Esempio di evento", "operationId": "esempioDiEvento", "description": "Restituisce un evento di esempio nella STESSA forma di una consegna vera\n(stesso involucro `event/delivery_id/occurred_at/data`).\n\n⚠️ Serve a Zapier e n8n per far mappare i campi PRIMA che sia mai arrivato\nun evento vero: senza, l'utente dovrebbe emettere una fattura finta per\npoter configurare il passo successivo.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "event": "invoice.created", "delivery_id": "00000000-0000-4000-8000-000000000000", "occurred_at": "2026-08-24T10:00:00+02:00", "data": { "invoice_id": 4821 } } }, "properties": { "data": { "type": "object", "properties": { "event": { "type": "string", "example": "invoice.created" }, "delivery_id": { "type": "string", "example": "00000000-0000-4000-8000-000000000000" }, "occurred_at": { "type": "string", "example": "2026-08-24T10:00:00+02:00" }, "data": { "type": "object", "properties": { "invoice_id": { "type": "integer", "example": 4821 } } } } } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "not_found", "message": "Evento sconosciuto: pippo.creato. Eventi validi: invoice.created, invoice.sent, ..." } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Evento sconosciuto: pippo.creato. Eventi validi: invoice.created, invoice.sent, ..." } } } } } } } } }, "tags": [ "Automazioni e webhook" ] }, "parameters": [ { "in": "path", "name": "event", "description": "Chiave dell'evento.", "example": "invoice.created", "required": true, "schema": { "type": "string" } } ] }, "/v1/hooks": { "get": { "summary": "Lista sottoscrizioni", "operationId": "listaSottoscrizioni", "description": "Le sottoscrizioni webhook dell'azienda. Il segreto non compare MAI: si\nvede solo alla creazione.", "parameters": [], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": [ { "id": "7", "name": "Zap: nuova fattura", "target_url": "https://hooks.zapier.com/hooks/standard/123/abc/", "events": [ "invoice.created" ], "source": "zapier", "is_active": true } ] }, "properties": { "data": { "type": "array", "example": [ { "id": "7", "name": "Zap: nuova fattura", "target_url": "https://hooks.zapier.com/hooks/standard/123/abc/", "events": [ "invoice.created" ], "source": "zapier", "is_active": true } ], "items": { "type": "object", "properties": { "id": { "type": "string", "example": "7" }, "name": { "type": "string", "example": "Zap: nuova fattura" }, "target_url": { "type": "string", "example": "https://hooks.zapier.com/hooks/standard/123/abc/" }, "events": { "type": "array", "example": [ "invoice.created" ], "items": { "type": "string" } }, "source": { "type": "string", "example": "zapier" }, "is_active": { "type": "boolean", "example": true } } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "ambiguous_account", "message": "Questa chiave vede più aziende..." } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "ambiguous_account" }, "message": { "type": "string", "example": "Questa chiave vede più aziende..." } } } } } } } } }, "tags": [ "Automazioni e webhook" ] }, "post": { "summary": "Crea sottoscrizione", "operationId": "creaSottoscrizione", "description": "Registra una destinazione a cui consegnare gli eventi indicati.\n\nSe esiste già una sottoscrizione ATTIVA con lo stesso URL e la stessa\nprovenienza, viene aggiornata invece di duplicata: Zapier ripete la\nsubscribe ogni volta che lo Zap viene riacceso, e senza questa regola\nogni riaccensione lascerebbe dietro un doppione che consegna due volte.", "parameters": [], "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "data": { "id": "7", "target_url": "https://hooks.zapier.com/hooks/standard/123/abc/", "events": [ "invoice.created" ], "source": "zapier", "secret": "...", "secret_note": "Conservalo ora: non verrà mostrato di nuovo." } }, "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "example": "7" }, "target_url": { "type": "string", "example": "https://hooks.zapier.com/hooks/standard/123/abc/" }, "events": { "type": "array", "example": [ "invoice.created" ], "items": { "type": "string" } }, "source": { "type": "string", "example": "zapier" }, "secret": { "type": "string", "example": "..." }, "secret_note": { "type": "string", "example": "Conservalo ora: non verrà mostrato di nuovo." } } } } } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "invalid_events", "message": "Nessun evento valido. Eventi validi: invoice.created, ..." } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "invalid_events" }, "message": { "type": "string", "example": "Nessun evento valido. Eventi validi: invoice.created, ..." } } } } } } } } }, "tags": [ "Automazioni e webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "description": "Dove consegnare gli eventi. Solo https.", "example": "https://hooks.zapier.com/hooks/standard/123/abc/", "nullable": false }, "events": { "type": "array", "description": "Chiavi degli eventi (vedi GET /v1/events).", "example": [ "invoice.created" ], "items": { "type": "string" } }, "name": { "type": "string", "description": "Etichetta leggibile della sottoscrizione.", "example": "Zap: nuova fattura → Google Sheets", "nullable": false }, "source": { "type": "string", "description": "zapier, n8n o custom (default custom).", "example": "zapier", "nullable": false } }, "required": [ "target_url", "events" ] } } } } } }, "/v1/hooks/{id}": { "delete": { "summary": "Elimina sottoscrizione", "operationId": "eliminaSottoscrizione", "description": "Zapier la chiama da solo quando l'utente spegne lo Zap.", "parameters": [], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "example": { "error": { "code": "not_found", "message": "Sottoscrizione non trovata" } }, "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Sottoscrizione non trovata" } } } } } } } } }, "tags": [ "Automazioni e webhook" ] }, "parameters": [ { "in": "path", "name": "id", "description": "ID della sottoscrizione.", "example": 7, "required": true, "schema": { "type": "integer" } } ] } }, "x-tagGroups": [ { "name": "SDK", "tags": [ "Laravel SDK (PHP)" ] }, { "name": "API", "tags": [ "Aziende", "Clienti", "Fatture", "Spese", "F24", "Scadenze fiscali", "Corrispettivi", "Automazioni e webhook" ] } ] }