` della FatturaPA al momento dell'invio SDI.
```php
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)
```php
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.
components:
securitySchemes:
default:
type: http
scheme: bearer
description: |-
Puoi creare e gestire i tuoi token API accedendo a 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.
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
singola 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
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.
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
per clienti esteri o senza Partita IVA italiana. Se la P.IVA indicata è
già 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
(ragione sociale, indirizzo, comune) dal registro imprese a partire dalla
Partita 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:
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.
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
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.
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.0
nullable: false
prezzo:
type: number
description: 'Prezzo unitario.'
example: 150.0
nullable: false
iva:
type: number
description: 'Aliquota IVA (%).'
example: 0.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.0
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
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.
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.
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.
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
`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.
parameters: []
responses:
201:
description: ''
content:
application/json:
schema:
type: object
example:
success: true
payment:
id: 77
amount: 500.0
payment_date: '2026-07-21'
invoice:
uuid: 9f8b6c1e-0000-0000-0000-000000000000
number: 2026/145
total: 1220.0
amount_paid: 500.0
amount_due: 720.0
payment_status: partial
properties:
success:
type: boolean
example: true
payment:
type: object
properties:
id:
type: integer
example: 77
amount:
type: number
example: 500.0
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.0
amount_paid:
type: number
example: 500.0
amount_due:
type: number
example: 720.0
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.0
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`
(`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`.
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.0
payment_status: unpaid
amount_paid: 0
amount_due: 1220.0
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.0
payment_status:
type: string
example: unpaid
amount_paid:
type: integer
example: 0
amount_due:
type: number
example: 1220.0
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
movimenti storici da interpretare: filtra con `?attivo=1` per i soli
centri 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`
(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.
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:
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.
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,
`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
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.
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
per popolare il menu dei trigger: la chiave è il valore da passare in
`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
(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.
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
vede 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.
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.
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'