# 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

- Base URL produzione: `https://api.onesto.it` — Sandbox (dati di prova, token separati): `https://api.sandbox.onesto.it`
- Autenticazione: header `Authorization: Bearer <token>`; il token si crea su `https://app.onesto.it/company/integrations` (Impostazioni → Integrazioni). Un token è legato a UNA azienda e a UN ambiente: usato sull'host sbagliato riceve 403 con l'host giusto.
- Rate limit: 120 richieste/minuto per token.
- Spec OpenAPI 3 completo: `https://docs.onesto.it/openapi.yaml` (testo) o `https://docs.onesto.it/openapi.json` (aggiungi `?ambiente=sandbox` per gli esempi sulla Sandbox). Postman: `https://docs.onesto.it/postman`.
- Tutta la documentazione in un solo file: `https://docs.onesto.it/llms-full.txt` (o `https://docs.onesto.it/llms-full.html` come pagina web).

## Quale strada scegliere

- Codice che chiama Onesto da un altro sistema (emettere fatture, leggere incassi, creare clienti) → **API REST** (spec OpenAPI) o **SDK Laravel**.
- Reagire a qualcosa che succede in Onesto (fattura emessa, incasso, tassa in scadenza) → **webhook** (`POST /v1/hooks`), Zapier o n8n.
- L'utente vuole usare Claude in chat sui propri dati, senza codice → non è materia di queste API: si attiva dall'app in Impostazioni → Integrazioni → Claude (MCP).

## Regole che un agente deve conoscere

- Gli importi nei payload sono **stringhe decimali** (`"1220.00"`), le date `AAAA-MM-GG`, gli istanti ISO-8601, un dato assente è `null` esplicito. Non convertire gli importi in float per confrontarli.
- Una fattura emessa in Italia passa dallo **SdI**: `invia_sdi: true` la trasmette davvero all'Agenzia delle Entrate. È irreversibile: in dubbio crea una bozza (`invia_sdi: false`) e lascia che sia l'utente a emetterla.
- `sdi_status` `draft`/`rejected`/`error` = fattura fiscalmente nulla; `delivery_failed` invece è VALIDA (consegnata nel cassetto fiscale).
- Note di credito (TD04) e note di debito (TD05) **non si incassano**: `payment_status` è `null` e `POST /fatture/{uuid}/pagamenti` risponde 422.
- Per creare una fattura da P.IVA usa `POST /fatture/nuova/piva`: Onesto recupera l'anagrafica dal Registro Imprese. La numerazione (`numerazione`) e il metodo di pagamento (`metodo_pagamento`) si leggono da `GET /fatture/numerazioni` e `GET /fatture/metodi-pagamento`, non si inventano.
- Webhook: la sottoscrizione vuole `target_url` (non `url`). Ogni consegna porta `X-Onesto-Signature: sha256=HMAC_SHA256(timestamp + "." + corpo)` col segreto della sottoscrizione e `X-Onesto-Timestamp`: verificala. Rispondi 2xx entro pochi secondi; 410 Gone cancella la sottoscrizione; dopo 20 fallimenti consecutivi viene spenta. `DELETE /v1/hooks/{id}` spegne, non elimina.
- I token con ambiti limitati (`abilities`) ricevono 403 sulle rotte fuori ambito; un token di studio/partner vede più aziende e su alcune scritture deve dire quale (`422 ambiguous_account`).
- Gli endpoint `/v1/*` sono di sola lettura salvo `hooks`; `/fatture/*` e `/clients/*` sono quelli operativi.

## Documentazione

- [Laravel SDK (PHP)](https://docs.onesto.it/#tag/laravel-sdk-php): Pacchetto Composer ufficiale per progetti Laravel.
- [Aziende](https://docs.onesto.it/#tag/aziende): Anagrafica delle aziende (account) visibili al token.
- [Clienti](https://docs.onesto.it/#tag/clienti)
- [Fatture](https://docs.onesto.it/#tag/fatture): Lista delle fatture elettroniche (attive e passive) degli account gestiti, con stato SdI normalizzato e stato di incasso (`payment_status`).
- [Spese](https://docs.onesto.it/#tag/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.
- [F24](https://docs.onesto.it/#tag/f24): F24 degli account gestiti: scadenze, importi, stato pagamento, link al PDF e quietanze.
- [Scadenze fiscali](https://docs.onesto.it/#tag/scadenze-fiscali): Scadenzario fiscale generico degli account (F24, IVA, INPS, dichiarazioni…).
- [Corrispettivi](https://docs.onesto.it/#tag/corrispettivi): Stato del caricamento corrispettivi telematici.
- [Automazioni e webhook](https://docs.onesto.it/#tag/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 
- [OpenAPI YAML](https://docs.onesto.it/openapi.yaml) / [JSON](https://docs.onesto.it/openapi.json): lo spec macchina, la fonte di tutto.
- [SDK e repository](https://github.com/Onesto-it): SDK Laravel, estensione Raycast, app Zapier.

## Endpoint

- `GET /v1/accounts` — Lista account
- `GET /v1/accounts/{id}` — Dettaglio account
- `GET /clients` — Lista clienti
- `POST /clients/store/automatic` — Crea cliente da P.IVA
- `POST /clients/store/manual` — Crea cliente (manuale)
- `GET /fatture/metodi-pagamento` — Lista metodi di pagamento
- `GET /fatture/numerazioni` — Lista numerazioni
- `POST /fatture/nuova/manuale` — Crea fattura (manuale)
- `POST /fatture/nuova/piva` — Crea fattura da P.IVA
- `POST /fatture/{uuid}/pagamenti` — Registra incasso
- `GET /v1/invoices` — Lista fatture
- `GET /v1/cost-centers` — Lista centri di costo
- `GET /v1/expenses` — Lista spese classificate
- `GET /v1/expenses/summary` — Totali per metodo e per centro
- `GET /v1/f24s` — Lista F24
- `GET /v1/f24s/{id}` — Dettaglio F24 (con sezioni tributi)
- `GET /v1/tax-deadlines` — Lista scadenze fiscali
- `GET /v1/receipts-uploads` — Stato corrispettivi
- `GET /v1/events` — Catalogo eventi
- `GET /v1/events/{event}/sample` — Esempio di evento
- `GET /v1/hooks` — Lista sottoscrizioni
- `POST /v1/hooks` — Crea sottoscrizione
- `DELETE /v1/hooks/{id}` — Elimina sottoscrizione
- `GET /v1/me` — Prova credenziali

## Eventi webhook

- `invoice.created` — Fattura emessa: Una nuova fattura è stata creata (bozze escluse).
- `invoice.sent` — Fattura inviata: La fattura è stata trasmessa: al Sistema di Interscambio oppure via email al cliente. Il campo "channel" dice quale dei due.
- `payment.received` — Incasso ricevuto: È stato registrato un pagamento su una fattura emessa. Scatta anche sugli acconti: "is_fully_paid" dice se la fattura è ora saldata.
- `payment.failed` — Pagamento fallito: Il pagamento automatico di un abbonamento di un tuo cliente non è andato a buon fine (addebito rifiutato).
- `payment.overdue` — Fattura scaduta non incassata: Una fattura ha superato la data di scadenza e risulta ancora da incassare, in tutto o in parte. Scatta UNA volta sola per fattura.
- `quote.accepted` — Preventivo accettato: Il cliente ha accettato e firmato il preventivo online.
- `quote.rejected` — Preventivo rifiutato: Il cliente ha rifiutato il preventivo. "reason" contiene il motivo, se lo ha indicato.
- `client.created` — Nuovo cliente: È stato aggiunto un cliente in anagrafica. I FORNITORI non fanno scattare questo evento.
- `expense.created` — Nuova spesa: È stata registrata una spesa. Gli import massivi (Agenzia delle Entrate) NON fanno scattare questo evento: sono travasi di documenti già esistenti, non fatti nuovi.
- `tax.created` — Nuovo bollettino fiscale: È stato generato un bollettino da pagare (F24 o tributo) in scadenza.
- `tax.deadline_approaching` — Bollettino in scadenza: Un bollettino non pagato si avvicina alla scadenza (o l'ha superata: "days_until_due" diventa negativo).
- `subscription.created` — Nuovo abbonamento: Un tuo cliente ha sottoscritto un abbonamento ricorrente.
- `subscription.renewed` — Abbonamento rinnovato: Un abbonamento è entrato in un nuovo periodo di fatturazione.
- `subscription.cancelled` — Abbonamento cancellato: Un abbonamento di un tuo cliente è stato cancellato.

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