Onesto.it API

Onesto (onesto.it) è il gestionale fiscale italiano per freelance e piccole imprese: fatture elettroniche con invio allo SdI, spese, tasse e F24, documenti, incassi. Questa è la documentazione per integrarsi via API REST, SDK e webhook.

In breve

Quale strada scegliere

Regole che un agente deve conoscere

Documentazione

Endpoint

Eventi webhook

Esempio di payload per ogni evento: GET /v1/events/{evento}/sample.

Pagine

Introduzione

Benvenuto nella documentazione ufficiale delle API di Onesto.it — il fisco, ma intelligente.

Queste 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.

URL base: https://api.onesto.it

Mentre 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).

Per 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.

Autenticazione

Puoi creare e gestire i tuoi token API accedendo a https://app.onesto.it/company/integrations (https://app.onesto.it/company/integrations).

Ogni richiesta alle API deve includere un'intestazione:

Authorization: Bearer {YOUR_API_TOKEN}

I 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.

Laravel SDK (PHP)

Pacchetto Composer ufficiale per progetti Laravel.

Installazione

composer require onesto-it/laravel-sdk

Service provider e alias Onesto registrati automaticamente da Laravel package discovery. Nessun setup manuale richiesto.

Opzionale — pubblica il file di configurazione:

php artisan vendor:publish --tag=onesto-config

Configurazione .env

ONESTO_TOKEN=il_tuo_api_token
# opzionale, default https://api.onesto.it
ONESTO_URL=https://api.onesto.it
# opzionale, default 30s
ONESTO_TIMEOUT=30

Il token si genera da Impostazioni → Integrazioni (app.onesto.it/company/integrations) nel tuo pannello Onesto.

Esempi

Creazione fattura da Partita IVA

I dati anagrafici vengono recuperati automaticamente da Onesto:

use Onesto;

Onesto::createInvoiceFromPIVA([
    'piva'             => '01234567890',
    'numerazione'      => 'Standard',
    'issue_date'       => '2026-05-20',
    'tipo_documento'   => 'TD01',
    'metodo_pagamento' => 'Bonifico',
    'articoli'         => [/* ... */],
    'scadenze'         => [/* ... */],
    'invia_sdi'        => true,
]);

Creazione fattura manuale

Onesto::createInvoiceManually([
    'cliente'  => [
        'ragione_sociale' => 'Acme SRL',
        'piva'            => '01234567890',
        'indirizzo'       => 'Via Roma 1',
        'cap'             => '20121',
        'citta'           => 'Milano',
        'provincia'       => 'MI',
        'nazione'         => 'IT',
        'pec'             => '[email protected]',
    ],
    'articoli' => [
        ['descrizione' => 'Consulenza', 'quantita' => 1, 'prezzo' => 1000, 'iva' => 22],
    ],
    'scadenze' => [
        ['data' => '2026-06-30', 'importo' => 1220],
    ],
    'invia_sdi' => true,
]);

Riferimenti Pubblica Amministrazione (CIG, CUP, ordine, determina…)

Per 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 <DatiOrdineAcquisto> della FatturaPA al momento dell'invio SDI.

Onesto::createInvoiceManually([
    // ... cliente, articoli, scadenze ...

    'pa' => [
        'cig'             => 'ZF3392A8B7',
        'cups'            => ['J53D23000170006', 'K12C24000050001'],
        'numero_ordine'   => 'ORD-2025-001',
        'data_ordine'     => '2025-04-15',
        'impegno'         => 'IMP-123',
        'determina'       => 'DET-456',
        'codice_commessa' => 'COMM-789',
    ],
]);

Senza Facade (dependency injection)

use OnestoIt\Sdk\Onesto;

class FattureController
{
    public function __construct(private Onesto $onesto) {}

    public function store()
    {
        return $this->onesto->createInvoiceManually([/* ... */]);
    }
}

L'SDK è un thin wrapper sulle stesse API REST documentate nella sezione API: tutto ciò che puoi inviare via HTTP puoi inviarlo via SDK.

Riferimento endpoint

Aziende

Anagrafica delle aziende (account) visibili al token. Serve a mappare le aziende Onesto sui clienti del consumer (match su P.IVA / codice fiscale).

GET /v1/accounts — Lista account

Ritorna gli account gestiti dal token (tutti i clienti dello studio, o la singola company). Paginato.

Parametri:

Esempio di risposta:

{
    "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
    }
}

GET /v1/accounts/{id} — Dettaglio account

Esempio di risposta:

{
    "data": {
        "id": "12",
        "name": "TRUE SOLUTIONS S.R.L.",
        "vat_number": "14288140966",
        "fiscal_code": "14288140966",
        "status": "active"
    }
}

Clienti

GET /clients — Lista clienti

Elenca i clienti dell'azienda in forma paginata, con ricerca opzionale su nome e Partita IVA (q). Restituisce l'anagrafica completa (indirizzo, codice SDI, PEC): i dati sono pronti per compilare il blocco cliente della creazione fattura senza ulteriori richieste.

Parametri:

Esempio di risposta:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "ACME Srl",
            "piva": "01234567890",
            "codice_fiscale": null,
            "sdi": "ABCDEFG",
            "pec": "[email protected]",
            "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
    }
}

POST /clients/store/automatic — Crea cliente da P.IVA

Crea un nuovo cliente recuperando automaticamente i dati anagrafici (ragione sociale, indirizzo, comune) dal registro imprese a partire dalla Partita IVA italiana. Basta la sola P.IVA, a tutto il resto pensa Onesto.

Parametri:

Esempio di risposta:

{
    "success": true,
    "data": {
        "name": "Azienda SRL",
        "piva": "01234567890",
        "city": "Roma"
    }
}

POST /clients/store/manual — Crea cliente (manuale)

Crea un nuovo cliente specificando manualmente i dati anagrafici. Utile per clienti esteri o senza Partita IVA italiana. Se la P.IVA indicata è già presente in anagrafica risponde 409 con il cliente esistente.

Parametri:

Esempio di risposta:

{
    "success": true,
    "data": {
        "id": 1,
        "name": "Mario Rossi",
        "email": "[email protected]"
    }
}

Fatture

Lista delle fatture elettroniche (attive e passive) degli account gestiti, con stato SdI normalizzato e stato di incasso (payment_status). Usi tipici: intercettare le fatture scartate/in errore e monitorare le fatture non incassate.

GET /fatture/metodi-pagamento — Lista metodi di pagamento

Elenca i metodi di pagamento utilizzabili in fattura, con IBAN e codice SDI. I nomi restituiti sono i valori accettati dal campo metodo_pagamento degli endpoint di creazione fattura e di registrazione incassi. I conti interni (pocket/sotto-conti) non compaiono: non sono metodi di incasso.

Esempio di risposta:

{
    "success": true,
    "data": [
        {
            "id": 3,
            "name": "Bonifico bancario",
            "type": "Bonifico",
            "iban": "IT60X0542811101000000123456",
            "sdi_code": "MP05"
        }
    ]
}

GET /fatture/numerazioni — Lista numerazioni

Elenca le numerazioni attive dell'azienda, con l'eventuale metodo di pagamento di default di ciascuna. I nomi restituiti sono i valori accettati dal campo numerazione degli endpoint di creazione fattura: usa questo endpoint per popolare i selettori nei client esterni invece di chiedere all'utente di digitare il nome a memoria.

Esempio di risposta:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Principale",
            "type": "standard",
            "default_payment_method": "Bonifico bancario"
        }
    ]
}

POST /fatture/nuova/manuale — Crea fattura (manuale)

Crea una nuova fattura elettronica specificando tutti i dati via API: cliente, numerazione, articoli, eventuali scadenze di pagamento e invio a SDI (invia_sdi, default attivo). I valori di numerazione e metodo_pagamento sono i NOMI restituiti da GET /fatture/numerazioni e GET /fatture/metodi-pagamento. Valorizzando paid viene registrato subito un incasso pari all'importo indicato.

Parametri:

Esempio di risposta:

{
    "id": 123,
    "url": "https://fatture.onesto.it/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pdf"
}

POST /fatture/nuova/piva — Crea fattura da P.IVA

Crea una nuova fattura elettronica recuperando automaticamente i dati del cliente dalla Partita IVA (lookup sul registro imprese). Numerazione, data e metodo di pagamento sono opzionali: se omessi vengono usati i default dell'azienda. Ideale per emettere una fattura conoscendo solo la P.IVA del cliente e gli articoli.

Parametri:

Esempio di risposta:

{
    "success": true,
    "data": {
        "id": 124,
        "url": "https://fatture.onesto.it/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/pdf"
    }
}

POST /fatture/{uuid}/pagamenti — Registra incasso

Registra un pagamento ricevuto su una fattura esistente, identificata dallo uuid (restituito dalla creazione e da GET /v1/invoices). L'importo non può superare il residuo da incassare; la risposta include il nuovo stato (paid/partial/unpaid) e il residuo aggiornato. Note di credito (TD04) e documenti fiscalmente nulli (bozze/scartate/errore) non accettano incassi.

Parametri:

Esempio di risposta:

{
    "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"
    }
}

GET /v1/invoices — Lista fatture

Oltre allo stato SdI, ogni fattura espone lo stato di incasso: payment_status (paid/partial/unpaid, null per note di credito e documenti fiscalmente nulli), amount_paid, amount_due, due_date (ultima scadenza di pagamento) e overdue. Per le fatture attive sono inclusi anche uuid e pdf_url.

Parametri:

Esempio di risposta:

{
    "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
    }
}

Spese

Centri di costo delle aziende gestite: la dimensione ANALITICA con cui le spese vengono attribuite a un cliente, un prodotto, una commessa o una sede.

Il riferimento stabile è code, non id: è quello che i sistemi esterni devono mappare. È univoco per azienda e non cambia quando il centro viene rinominato.

GET /v1/cost-centers — Lista centri di costo

Di default include anche i centri disattivati, perché possono avere movimenti storici da interpretare: filtra con ?attivo=1 per i soli centri utilizzabili oggi.

Parametri:

Esempio di risposta:

{
    "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
    }
}

GET /v1/expenses — Lista spese classificate

allocation_method: diretto (attribuibile a un centro), personale (retribuzioni e oneri), struttura (spese generali), escluso (fuori dall'attività). Una spesa senza metodo vale struttura.

cost_center_code è sempre presente accanto all'id: mappa su quello, non sugli id numerici. Vale UNASSIGNED con needs_review: true quando la spesa è marcata diretto ma il centro non è stato indicato — così quei costi si vedono invece di finire silenziosamente in un altro totale.

Parametri:

Esempio di risposta:

{
    "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
    }
}

GET /v1/expenses/summary — Totali per metodo e per centro

I NON ASSEGNATI stanno in un blocco a parte e non entrano nei totali: chi consuma vede quanto è in sospeso invece di riceverlo dentro un altro numero. Regola per chi fa il riparto: le non assegnate restano fuori dalla base di costo finché non vengono classificate — meglio un importo in meno che un importo attribuito a caso.

Parametri:

Esempio di risposta:

{
    "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"
    }
}

F24

F24 degli account gestiti: scadenze, importi, stato pagamento, link al PDF e quietanze. È il cuore della supervisione fiscale (alert su scaduti / in scadenza).

GET /v1/f24s — Lista F24

Stato (status): ready = da pagare (pronto per il bonifico), paid = pagato, expired = scaduto non pagato, cancelled = annullato, draft = bozza da completare.

Parametri:

Esempio di risposta:

{
    "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
    }
}

GET /v1/f24s/{id} — Dettaglio F24 (con sezioni tributi)

Scadenze fiscali

Scadenzario fiscale generico degli account (F24, IVA, INPS, dichiarazioni…). Estende la supervisione oltre i soli F24. Sorgente: record taxes.

GET /v1/tax-deadlines — Lista scadenze fiscali

Parametri:

Esempio di risposta:

{
    "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
    }
}

Corrispettivi

Stato del caricamento corrispettivi telematici. ⚠️ Onesto NON gestisce nativamente i corrispettivi/registratori telematici: l'endpoint esiste per completezza del contratto API ma risponde con supported=false e lista vuota, così il consumer non lo tratta come errore. Verrà popolato se/quando Onesto introdurrà la gestione dei corrispettivi.

GET /v1/receipts-uploads — Stato corrispettivi

Parametri:

Esempio di risposta:

{
    "data": [],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total": 0,
        "next_page": null,
        "supported": false,
        "note": "Corrispettivi non gestiti da Onesto"
    }
}

Automazioni e webhook

Endpoint con cui Zapier, n8n e le integrazioni fatte in casa si sottoscrivono agli eventi di Onesto (REST Hooks): catalogo degli eventi disponibili, dati di esempio per configurare i passi a valle, e gestione delle sottoscrizioni.

⚠️ Una sottoscrizione appartiene a UNA azienda: la chiave usata deve essere quella della singola azienda (creata da /company/integrations), non un token di studio che ne vede molte — indovinare l'azienda manderebbe i dati di un cliente dentro l'automazione di un altro.

GET /v1/events — Catalogo eventi

Elenco degli eventi a cui ci si può sottoscrivere. Zapier e n8n lo usano per popolare il menu dei trigger: la chiave è il valore da passare in events, l'etichetta è quella da mostrare all'utente.

Esempio di risposta:

{
    "data": [
        {
            "key": "invoice.created",
            "label": "Fattura emessa",
            "description": "Una nuova fattura è stata creata (bozze escluse).",
            "category": "Fatture"
        }
    ]
}

GET /v1/events/{event}/sample — Esempio di evento

Restituisce un evento di esempio nella STESSA forma di una consegna vera (stesso involucro event/delivery_id/occurred_at/data).

⚠️ Serve a Zapier e n8n per far mappare i campi PRIMA che sia mai arrivato un evento vero: senza, l'utente dovrebbe emettere una fattura finta per poter configurare il passo successivo.

Esempio di risposta:

{
    "data": {
        "event": "invoice.created",
        "delivery_id": "00000000-0000-4000-8000-000000000000",
        "occurred_at": "2026-08-24T10:00:00+02:00",
        "data": {
            "invoice_id": 4821
        }
    }
}

GET /v1/hooks — Lista sottoscrizioni

Le sottoscrizioni webhook dell'azienda. Il segreto non compare MAI: si vede solo alla creazione.

Esempio di risposta:

{
    "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
        }
    ]
}

POST /v1/hooks — Crea sottoscrizione

Registra una destinazione a cui consegnare gli eventi indicati.

Se esiste già una sottoscrizione ATTIVA con lo stesso URL e la stessa provenienza, viene aggiornata invece di duplicata: Zapier ripete la subscribe ogni volta che lo Zap viene riacceso, e senza questa regola ogni riaccensione lascerebbe dietro un doppione che consegna due volte.

Parametri:

Esempio di risposta:

{
    "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."
    }
}

DELETE /v1/hooks/{id} — Elimina sottoscrizione

Zapier la chiama da solo quando l'utente spegne lo Zap.

GET /v1/me — Prova credenziali

Dice a chi possiede la chiave quale azienda vede, cosa può fare e se questa installazione consegna webhook. Zapier e n8n lo chiamano appena l'utente incolla la chiave, per dare subito un errore comprensibile invece di fallire più tardi su un endpoint qualsiasi.

Esempio di risposta:

{
    "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
    }
}