Sviluppatori

L'API di Fatturando.online

Collega gestionali, e-commerce e software dello studio: crea ed emetti fatture elettroniche con XML FatturaPA validato, inviale allo SDI, sincronizza scadenze e documenti, ricevi gli eventi in tempo reale con webhook firmati.

Crea un account Specifica OpenAPI

bash

curl https://fatturando.online/api/v1/me \
  -H "Authorization: Bearer fo_live_…"

{
  "object": "account",
  "organization": { "name": "Studio Bianchi", "kind": "studio" },
  "key": { "scopes": ["invoices:read", "invoices:write"] },
  "rate_limit_per_minute": 120
}

01Guida rapida

La prima fattura in quattro chiamate

1. Crea una chiave in Impostazioni → Sviluppatori e API, con gli scope parties:write, invoices:write e invoices:issue. La vedi una sola volta.

2. Crea il cliente

bash

curl -X POST https://fatturando.online/api/v1/parties \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" -H "Content-Type: application/json" \
  -d '{ "company_id": "<azienda>", "name": "Meccanica Bresciana S.p.A.", "vat_number": "03867330981",
        "sdi_code": "W7YVJK9", "address": { "street": "Via Industriale 4", "zip": "25100", "city": "Brescia", "province": "BS" } }'

3. Crea la bozza (con Idempotency-Key non rischi doppioni se ripeti la richiesta)

bash

curl -X POST https://fatturando.online/api/v1/invoices \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: ordine-2026-0042" \
  -d '{ "company_id": "<azienda>", "party_id": "<cliente>", "issue_date": "2026-10-15",
        "lines": [{ "description": "Lavorazione CNC", "quantity": "12", "unit_price": "85.50", "vat_rate": "22" }] }'

4. Emetti e invia allo SDI: numero definitivo, XML FatturaPA validato sullo schema ufficiale, trasmissione tramite l'intermediario accreditato. L'esito arriva con il webhook invoice.sdi_updated.

bash

curl -X POST https://fatturando.online/api/v1/invoices/<id>/issue -H "Authorization: Bearer $FATTURANDO_API_KEY"
curl -X POST https://fatturando.online/api/v1/invoices/<id>/send  -H "Authorization: Bearer $FATTURANDO_API_KEY"
curl -o fattura.pdf https://fatturando.online/api/v1/invoices/<id>/pdf -H "Authorization: Bearer $FATTURANDO_API_KEY"

02Autenticazione e permessi

Una chiave, i permessi che scegli

Ogni richiesta porta l'header Authorization: Bearer fo_live_…. La chiave appartiene allo studio o all'impresa e agisce con i permessi attuali di chi l'ha creata, limitati agli scope scelti: se quella persona perde l'accesso, la chiave smette di funzionare. Si può limitare a singole aziende, impostare una scadenza e revocare in qualsiasi momento. Salviamo solo l'impronta della chiave, mai la chiave in chiaro.

Scope	Consente
companies:read	Leggere aziende e anagrafiche
companies:write	Creare e modificare aziende
parties:read	Leggere clienti e fornitori
parties:write	Creare e modificare clienti e fornitori
invoices:read	Leggere fatture, PDF e XML
invoices:write	Creare bozze, registrare incassi
invoices:issue	Emettere e inviare allo SDI
deadlines:read	Leggere scadenze
deadlines:write	Creare scadenze e cambiarne lo stato
documents:read	Leggere e scaricare documenti
documents:write	Caricare documenti
requests:read	Leggere richieste documentali
requests:write	Creare richieste documentali
accounting:read	Leggere contabilità: piano dei conti, giornale, bilanci

03Convenzioni

Prevedibile, come deve essere un'API contabile

JSON e snake_case
Richieste e risposte in JSON UTF-8, campi in snake_case.
Importi in centesimi
Tutti gli importi sono interi in centesimi di euro (total_cents: 118900). Prezzi unitari e quantità come stringhe decimali fino a 6 cifre ("85.50").
Date
Date in formato YYYY-MM-DD, istanti in ISO 8601 UTC.
Paginazione a cursore
Liste con limit (1–100) e cursor; la risposta ha has_more e next_cursor.
Idempotenza
Su POST e PATCH l'header Idempotency-Key fa sì che una richiesta ripetuta restituisca la stessa risposta, senza duplicati.
Versioni
La versione è nel percorso (/v1). Aggiungiamo campi senza preavviso; rimuovere o cambiare un campo richiede una nuova versione.

04Errori e limiti

Errori leggibili, limiti dichiarati

json

HTTP/1.1 422 Unprocessable Entity
X-Request-Id: req_8f2c1a9b0d3e4f5a6b7c

{
  "error": {
    "code": "validation_error",
    "message": "Dati non validi.",
    "details": [{ "field": "lines.0.vat_rate", "message": "Aliquota non valida" }]
  },
  "request_id": "req_8f2c1a9b0d3e4f5a6b7c"
}

Codici principali: 401 unauthenticated / invalid_key, 403 insufficient_scope / forbidden / plan_required, 404 not_found (anche per risorse di altri: non riveliamo cosa esiste), 409 idempotency_conflict, 422 validation_error, 429 rate_limited.

Limite di richieste al minuto per chiave: 60 di base, 120 con professional, 300 con studio plus, 1200 con enterprise, 120 con impresa pro, 300 con impresa premium. Ogni risposta ha X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset; il 429 include Retry-After.

05Webhook

Gli eventi arrivano da soli

Registra un URL https in Impostazioni → Sviluppatori e API. Ogni evento è una POST JSON con { id, type, created_at, company_id, data: { object } } firmata con HMAC-SHA256 nell'header Fatturando-Signature: t=…,v1=…. Rispondi 2xx entro 8 secondi; altrimenti ritentiamo dopo 1, 5, 30 minuti, 2, 6, 12 e 24 ore. Lo stesso evento può arrivare più di una volta: usa id per scartare i doppioni.

Evento	Quando
invoice.issued	Fattura emessa (numero assegnato, XML generato)
invoice.sdi_updated	Nuovo esito SDI su una fattura emessa
invoice.received	Fattura passiva ricevuta
invoice.payment_recorded	Incasso o pagamento registrato
deadline.created	Nuova scadenza
deadline.status_changed	Cambio di stato di una scadenza
document.uploaded	Documento caricato
document_request.created	Nuova richiesta documentale

node.js

import crypto from "node:crypto";

// header: Fatturando-Signature: t=1760000000,v1=<hex>
export function verify(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const ts = Number(parts.t);
  if (!ts || Math.abs(Date.now() / 1000 - ts) > toleranceSec) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}

php

<?php
function fatturando_verify(string $raw, string $header, string $secret, int $tol = 300): bool {
  parse_str(str_replace(',', '&', $header), $p);
  if (!isset($p['t'], $p['v1']) || abs(time() - (int)$p['t']) > $tol) return false;
  $expected = hash_hmac('sha256', $p['t'] . '.' . $raw, $secret);
  return hash_equals($expected, $p['v1']);
}

python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts = int(parts.get("t", 0))
    if abs(time.time() - ts) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

06Riferimento

Account

Chiave in uso e organizzazione.

get/meChiave in uso e organizzazione

bash

curl -X GET "https://fatturando.online/api/v1/me" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "account",
  "organization": {
    "id": "cmv…",
    "name": "Studio Bianchi & Associati",
    "kind": "studio"
  },
  "key": {
    "prefix": "fo_live_3f9a12bc",
    "name": "Gestionale interno",
    "scopes": [
      "invoices:read"
    ],
    "company_ids": []
  },
  "plan": "Professional",
  "rate_limit_per_minute": 120
}

07Riferimento

Aziende

Aziende visibili alla chiave (per gli studi: i clienti; per le imprese: la propria).

get/companiesElenco aziendecompanies:read

Aziende visibili alla chiave: per uno studio le aziende clienti attive (solo quelle assegnate, se il creatore della chiave non vede tutto lo studio), per un'impresa la propria. Le chiavi limitate a specifiche aziende vedono solo quelle.

Parametri

q — Cerca per ragione sociale, partita IVA o codice fiscale.
status — Filtra per stato.
limit — Elementi per pagina (1–100, predefinito 25).
cursor — Valore di next_cursor della pagina precedente.

bash

curl -X GET "https://fatturando.online/api/v1/companies" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "data": [
    {
      "object": "company",
      "id": "cmb3k2v0q0001s6p8a1b2c3d4",
      "name": "Rossi Arredamenti S.r.l.",
      "vat_number": "01234567897",
      "tax_code": "01234567897",
      "legal_form": "SRL",
      "tax_regime": "ORDINARIO",
      "vat_periodicity": "TRIMESTRALE",
      "has_employees": true,
      "ateco_code": "31.09.10",
      "pec": "rossiarredamenti@pec.it",
      "sdi_code": "M5UXCR1",
      "email": "amministrazione@rossiarredamenti.it",
      "phone": "+39 030 1234567",
      "address": {
        "street": "Via Milano 12",
        "zip": "25126",
        "city": "Brescia",
        "province": "BS",
        "country": "IT"
      },
      "status": "ATTIVA",
      "created_at": "2026-03-02T09:14:00.000Z",
      "updated_at": "2026-09-18T15:40:12.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

get/companies/{id}Dettaglio azienda con soci e carichecompanies:read

bash

curl -X GET "https://fatturando.online/api/v1/companies/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "company",
  "id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "name": "Rossi Arredamenti S.r.l.",
  "vat_number": "01234567897",
  "tax_code": "01234567897",
  "legal_form": "SRL",
  "tax_regime": "ORDINARIO",
  "vat_periodicity": "TRIMESTRALE",
  "has_employees": true,
  "ateco_code": "31.09.10",
  "pec": "rossiarredamenti@pec.it",
  "sdi_code": "M5UXCR1",
  "email": "amministrazione@rossiarredamenti.it",
  "phone": "+39 030 1234567",
  "address": {
    "street": "Via Milano 12",
    "zip": "25126",
    "city": "Brescia",
    "province": "BS",
    "country": "IT"
  },
  "status": "ATTIVA",
  "created_at": "2026-03-02T09:14:00.000Z",
  "updated_at": "2026-09-18T15:40:12.000Z",
  "ateco_description": "Fabbricazione di mobili per arredo domestico",
  "rea_number": "BS-123456",
  "share_capital_cents": 1000000,
  "notes": null,
  "officers": [
    {
      "id": "cmb3k2v0q0002s6p8x9y8z7w6",
      "name": "Mario Rossi",
      "tax_code": "RSSMRA70A01B157Y",
      "role": "LEGALE_RAPPRESENTANTE",
      "share_percent": "60",
      "email": "mario@rossiarredamenti.it",
      "phone": null,
      "since": "2015-04-01",
      "until": null
    }
  ]
}

post/companiesCrea un'azienda clientecompanies:write

Solo per gli studi. Rispetta il limite di aziende del piano (402 `plan_limit` se raggiunto). Una partita IVA già presente tra le aziende dello studio dà 409 `duplicate_company` con l'id esistente. Le chiavi limitate a specifiche aziende non possono crearne di nuove.

Corpo

name * string
vat_number string | null
tax_code string | null
legal_form DITTA_INDIVIDUALE | LIBERO_PROFESSIONISTA | SNC | SAS | SRL | SRLS | SPA | SAPA | COOPERATIVA | ASSOCIAZIONE | FONDAZIONE | ALTRO
tax_regime ORDINARIO | SEMPLIFICATO | FORFETTARIO | AGRICOLO | ALTRO
vat_periodicity MENSILE | TRIMESTRALE | NON_SOGGETTO
has_employees boolean
ateco_code string | null
ateco_description string | null
rea_number string | null
share_capital_cents integer | null — Capitale sociale in centesimi
pec string | null
sdi_code string | null
email string | null
phone string | null
address object
notes string | null

bash

curl -X POST "https://fatturando.online/api/v1/companies" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Rossi Arredamenti S.r.l.",
    "vat_number": "01234567897",
    "legal_form": "SRL",
    "tax_regime": "ORDINARIO",
    "vat_periodicity": "TRIMESTRALE",
    "has_employees": true,
    "pec": "rossiarredamenti@pec.it",
    "sdi_code": "M5UXCR1",
    "address": {
      "street": "Via Milano 12",
      "zip": "25126",
      "city": "Brescia",
      "province": "BS"
    }
  }'

risposta

{
  "object": "company",
  "id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "name": "Rossi Arredamenti S.r.l.",
  "vat_number": "01234567897",
  "tax_code": "01234567897",
  "legal_form": "SRL",
  "tax_regime": "ORDINARIO",
  "vat_periodicity": "TRIMESTRALE",
  "has_employees": true,
  "ateco_code": "31.09.10",
  "pec": "rossiarredamenti@pec.it",
  "sdi_code": "M5UXCR1",
  "email": "amministrazione@rossiarredamenti.it",
  "phone": "+39 030 1234567",
  "address": {
    "street": "Via Milano 12",
    "zip": "25126",
    "city": "Brescia",
    "province": "BS",
    "country": "IT"
  },
  "status": "ATTIVA",
  "created_at": "2026-03-02T09:14:00.000Z",
  "updated_at": "2026-09-18T15:40:12.000Z",
  "ateco_description": null,
  "rea_number": null,
  "share_capital_cents": null,
  "notes": null,
  "officers": []
}

patch/companies/{id}Modifica anagrafica o statocompanies:write

Aggiorna solo i campi presenti; `null` svuota un campo. Per uno studio serve l'autorizzazione dell'azienda sull'area anagrafica.

Corpo

name string
vat_number string | null
tax_code string | null
legal_form DITTA_INDIVIDUALE | LIBERO_PROFESSIONISTA | SNC | SAS | SRL | SRLS | SPA | SAPA | COOPERATIVA | ASSOCIAZIONE | FONDAZIONE | ALTRO
tax_regime ORDINARIO | SEMPLIFICATO | FORFETTARIO | AGRICOLO | ALTRO
vat_periodicity MENSILE | TRIMESTRALE | NON_SOGGETTO
has_employees boolean
ateco_code string | null
ateco_description string | null
rea_number string | null
share_capital_cents integer | null — Capitale sociale in centesimi
pec string | null
sdi_code string | null
email string | null
phone string | null
address object
notes string | null
status ATTIVA | SOSPESA | CESSATA

bash

curl -X PATCH "https://fatturando.online/api/v1/companies/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "pec": "nuovapec@pec.it",
    "address": {
      "street": "Via Brescia 4"
    },
    "status": "SOSPESA"
  }'

08Riferimento

Clienti e fornitori

Anagrafiche usate in fattura.

get/partiesElenco clienti e fornitoriparties:read

Anagrafiche delle aziende visibili alla chiave, ordinate per nome. Senza `company_id` restituisce quelle di tutte le aziende che hanno autorizzato l'area fatture.

Parametri

company_id — Filtra per azienda
kind — CLIENTE (include ENTRAMBI), FORNITORE (include ENTRAMBI) o ENTRAMBI
q — Cerca per nome, partita IVA o codice fiscale
archived — true = solo archiviate; predefinito: solo attive
limit — Elementi per pagina (1–100, predefinito 25)
cursor — Valore di next_cursor della pagina precedente

bash

curl -X GET "https://fatturando.online/api/v1/parties" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "data": [
    {
      "object": "party",
      "id": "cmparty01",
      "company_id": "cmcomp01",
      "kind": "CLIENTE",
      "is_person": false,
      "is_public_administration": false,
      "name": "Rossi Forniture S.r.l.",
      "first_name": null,
      "last_name": null,
      "vat_number": "03867330981",
      "tax_code": null,
      "sdi_code": "W7YVJK9",
      "pec": null,
      "email": "amministrazione@rossiforniture.it",
      "phone": null,
      "payment_terms_days": 30,
      "address": {
        "street": "Via Milano",
        "street_number": "2",
        "zip": "20100",
        "city": "Milano",
        "province": "MI",
        "country": "IT"
      },
      "archived": false,
      "created_at": "2026-10-15T08:00:00.000Z",
      "updated_at": "2026-10-15T08:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

post/partiesCrea un cliente o fornitoreparties:write

Per i soggetti italiani serve partita IVA o codice fiscale (verificati con il carattere di controllo). Se esiste già un'anagrafica attiva con la stessa partita IVA risponde 409 `duplicate_party` con l'id esistente.

Corpo

company_id * string
kind CLIENTE | FORNITORE | ENTRAMBI — CLIENTE, FORNITORE o ENTRAMBI
is_person boolean — Persona fisica: si usano first_name e last_name
is_public_administration boolean — Pubblica Amministrazione: sdi_code è il codice ufficio a 6 caratteri
name string — Denominazione (aziende)
first_name string | null
last_name string | null
vat_number string | null — Partita IVA, anche con prefisso paese
tax_code string | null
sdi_code string | null — Codice destinatario (7) o codice ufficio PA (6)
pec string | null
email string | null
phone string | null
payment_terms_days integer | null — Giorni di pagamento; null = predefinito dell'azienda
notes string | null
address object

bash

curl -X POST "https://fatturando.online/api/v1/parties" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "company_id": "cmcomp01",
    "kind": "CLIENTE",
    "name": "Rossi Forniture S.r.l.",
    "vat_number": "IT03867330981",
    "sdi_code": "W7YVJK9",
    "email": "amministrazione@rossiforniture.it",
    "payment_terms_days": 30,
    "address": {
      "street": "Via Milano",
      "street_number": "2",
      "zip": "20100",
      "city": "Milano",
      "province": "MI",
      "country": "IT"
    }
  }'

risposta

{
  "object": "party",
  "id": "cmparty01",
  "company_id": "cmcomp01",
  "kind": "CLIENTE",
  "is_person": false,
  "is_public_administration": false,
  "name": "Rossi Forniture S.r.l.",
  "first_name": null,
  "last_name": null,
  "vat_number": "03867330981",
  "tax_code": null,
  "sdi_code": "W7YVJK9",
  "pec": null,
  "email": "amministrazione@rossiforniture.it",
  "phone": null,
  "payment_terms_days": 30,
  "address": {
    "street": "Via Milano",
    "street_number": "2",
    "zip": "20100",
    "city": "Milano",
    "province": "MI",
    "country": "IT"
  },
  "archived": false,
  "created_at": "2026-10-15T08:00:00.000Z",
  "updated_at": "2026-10-15T08:00:00.000Z"
}

get/parties/{id}Dettaglio anagraficaparties:read

bash

curl -X GET "https://fatturando.online/api/v1/parties/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "party",
  "id": "cmparty01",
  "company_id": "cmcomp01",
  "kind": "CLIENTE",
  "is_person": false,
  "is_public_administration": false,
  "name": "Rossi Forniture S.r.l.",
  "first_name": null,
  "last_name": null,
  "vat_number": "03867330981",
  "tax_code": null,
  "sdi_code": "W7YVJK9",
  "pec": null,
  "email": "amministrazione@rossiforniture.it",
  "phone": null,
  "payment_terms_days": 30,
  "address": {
    "street": "Via Milano",
    "street_number": "2",
    "zip": "20100",
    "city": "Milano",
    "province": "MI",
    "country": "IT"
  },
  "archived": false,
  "created_at": "2026-10-15T08:00:00.000Z",
  "updated_at": "2026-10-15T08:00:00.000Z"
}

patch/parties/{id}Modifica un'anagraficaparties:write

Aggiornamento parziale: i campi assenti restano invariati, `null` svuota un campo. Le fatture già emesse non cambiano (hanno i dati congelati all'emissione). `archived` archivia o ripristina.

Corpo

kind CLIENTE | FORNITORE | ENTRAMBI — CLIENTE, FORNITORE o ENTRAMBI
is_person boolean — Persona fisica: si usano first_name e last_name
is_public_administration boolean — Pubblica Amministrazione: sdi_code è il codice ufficio a 6 caratteri
name string — Denominazione (aziende)
first_name string | null
last_name string | null
vat_number string | null — Partita IVA, anche con prefisso paese
tax_code string | null
sdi_code string | null — Codice destinatario (7) o codice ufficio PA (6)
pec string | null
email string | null
phone string | null
payment_terms_days integer | null — Giorni di pagamento; null = predefinito dell'azienda
notes string | null
address object
archived boolean — true archivia l'anagrafica, false la ripristina

bash

curl -X PATCH "https://fatturando.online/api/v1/parties/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "fatture@rossiforniture.it",
    "payment_terms_days": 60
  }'

risposta

{
  "object": "party",
  "id": "cmparty01",
  "company_id": "cmcomp01",
  "kind": "CLIENTE",
  "is_person": false,
  "is_public_administration": false,
  "name": "Rossi Forniture S.r.l.",
  "first_name": null,
  "last_name": null,
  "vat_number": "03867330981",
  "tax_code": null,
  "sdi_code": "W7YVJK9",
  "pec": null,
  "email": "fatture@rossiforniture.it",
  "phone": null,
  "payment_terms_days": 60,
  "address": {
    "street": "Via Milano",
    "street_number": "2",
    "zip": "20100",
    "city": "Milano",
    "province": "MI",
    "country": "IT"
  },
  "archived": false,
  "created_at": "2026-10-15T08:00:00.000Z",
  "updated_at": "2026-10-15T08:00:00.000Z"
}

09Riferimento

Fatture

Preventivi, fatture, note di credito: bozze, emissione con XML FatturaPA validato, invio SDI, PDF, incassi.

get/invoicesElenco documentiinvoices:read

Documenti delle aziende visibili alla chiave, dal più recente. Gli elenchi non includono righe e scadenze: per quelle usa il dettaglio.

Parametri

company_id — Filtra per azienda
direction — outgoing = emesse, incoming = ricevute dai fornitori
kind — Tipo di documento
status — Stato del documento o esito SDI
paid_status — Stato di incasso
from — Data documento dal (YYYY-MM-DD, inclusa)
to — Data documento al (YYYY-MM-DD, inclusa)
party_id — Filtra per cliente o fornitore
limit — Elementi per pagina (1–100, predefinito 25)
cursor — Valore di next_cursor della pagina precedente

bash

curl -X GET "https://fatturando.online/api/v1/invoices" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "cminv01",
      "company_id": "cmcomp01",
      "direction": "outgoing",
      "kind": "invoice",
      "document_type": "TD01",
      "series": null,
      "number": 42,
      "number_label": "42",
      "issue_date": "2026-10-15",
      "party_id": "cmparty01",
      "status": "emessa",
      "sdi": {
        "status": null,
        "message": null,
        "id": null,
        "sent_at": null,
        "updated_at": null
      },
      "currency": "EUR",
      "causale": null,
      "notes": null,
      "vat_exigibility": "I",
      "withholding": null,
      "pension_fund": null,
      "stamp_duty": false,
      "pa_reference": null,
      "payment": {
        "method": "MP05",
        "terms": "TP02",
        "iban": "IT60X0542811101000000123456"
      },
      "totals": {
        "taxable_cents": 50000,
        "vat_cents": 11000,
        "pension_fund_cents": 0,
        "withholding_cents": 0,
        "total_cents": 61000,
        "net_to_pay_cents": 61000,
        "paid_cents": 0
      },
      "paid_status": "non_pagata",
      "related_invoice_id": null,
      "has_xml": true,
      "xml_file_name": "IT01234567897_A3K9P.xml",
      "issued_at": "2026-10-15T09:15:00.000Z",
      "created_at": "2026-10-15T09:12:00.000Z",
      "updated_at": "2026-10-15T09:12:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cminv01"
}

get/invoices/{id}Dettaglio documentoinvoices:read

Con righe (`lines`) e scadenze di pagamento con gli incassi (`payments`).

bash

curl -X GET "https://fatturando.online/api/v1/invoices/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "invoice",
  "document_type": "TD01",
  "series": null,
  "number": 42,
  "number_label": "42",
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "emessa",
  "sdi": {
    "status": null,
    "message": null,
    "id": null,
    "sent_at": null,
    "updated_at": null
  },
  "currency": "EUR",
  "causale": null,
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 0
  },
  "paid_status": "non_pagata",
  "related_invoice_id": null,
  "has_xml": true,
  "xml_file_name": "IT01234567897_A3K9P.xml",
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "1",
      "unit": null,
      "unit_price": "500",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [
    {
      "due_date": "2026-11-14",
      "amount_cents": 61000,
      "paid_cents": 0,
      "paid_at": null,
      "method": null
    }
  ],
  "issued_at": "2026-10-15T09:15:00.000Z",
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

post/invoicesCrea una bozzainvoices:write

Crea un documento in stato `bozza` con le sue righe e ne calcola i totali. Righe, nature IVA, ritenuta e cassa sono controllate subito (422 `invalid_invoice` con l'elenco dei problemi). La numerazione si assegna solo con `POST /invoices/{id}/issue`.

Corpo

company_id * string
kind invoice | credit_note | debit_note | quote | proforma — Tipo di documento
document_type string — Predefinito: TD01 fattura, TD04 nota di credito, TD05 nota di debito
party_id string | null — Cliente (obbligatorio per emettere)
issue_date string — Data del documento; predefinita oggi
series string — Sezionale di numerazione; vuoto = principale
causale string | null
notes string | null
internal_notes string | null — Non stampate sul documento
vat_exigibility I | D | S — I immediata, D differita, S split payment
withholding object | null — Ritenuta d'acconto, es. { type: "RT01", rate: "20", reason: "A" }
pension_fund object | null — Cassa previdenziale, es. { type: "TC22", rate: "4", vat_rate: "22" }
stamp_duty boolean — Marca da bollo virtuale da 2 €
payment_method string — ModalitaPagamento (MP05 bonifico, MP08 carta…)
payment_terms TP01 | TP02 | TP03 — TP02 pagamento completo, TP01 a rate, TP03 anticipo
iban string | null — Predefinito: IBAN delle impostazioni di fatturazione
related_invoice_id string | null — Fattura di riferimento (note di credito/debito)
pa_reference object | null — Riferimenti obbligatori per le fatture alla Pubblica Amministrazione
lines * array

bash

curl -X POST "https://fatturando.online/api/v1/invoices" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "company_id": "cmcomp01",
    "kind": "invoice",
    "party_id": "cmparty01",
    "issue_date": "2026-10-15",
    "payment_method": "MP05",
    "iban": "IT60X0542811101000000123456",
    "lines": [
      {
        "description": "Consulenza fiscale ottobre 2026",
        "quantity": "1",
        "unit_price": "500",
        "vat_rate": "22"
      }
    ]
  }'

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "invoice",
  "document_type": "TD01",
  "series": null,
  "number": null,
  "number_label": null,
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "bozza",
  "sdi": {
    "status": null,
    "message": null,
    "id": null,
    "sent_at": null,
    "updated_at": null
  },
  "currency": "EUR",
  "causale": null,
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 0
  },
  "paid_status": "non_pagata",
  "related_invoice_id": null,
  "has_xml": false,
  "xml_file_name": null,
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "1",
      "unit": null,
      "unit_price": "500",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [],
  "issued_at": null,
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

patch/invoices/{id}Modifica una bozzainvoices:write

Solo per le bozze (altrimenti 409 `invoice_not_draft`). I campi assenti restano invariati; `lines`, se presente, sostituisce tutte le righe. I totali vengono ricalcolati.

Corpo

kind invoice | credit_note | debit_note | quote | proforma — Tipo di documento
document_type string — Predefinito: TD01 fattura, TD04 nota di credito, TD05 nota di debito
party_id string | null — Cliente (obbligatorio per emettere)
issue_date string — Data del documento; predefinita oggi
series string — Sezionale di numerazione; vuoto = principale
causale string | null
notes string | null
internal_notes string | null — Non stampate sul documento
vat_exigibility I | D | S — I immediata, D differita, S split payment
withholding object | null — Ritenuta d'acconto, es. { type: "RT01", rate: "20", reason: "A" }
pension_fund object | null — Cassa previdenziale, es. { type: "TC22", rate: "4", vat_rate: "22" }
stamp_duty boolean — Marca da bollo virtuale da 2 €
payment_method string — ModalitaPagamento (MP05 bonifico, MP08 carta…)
payment_terms TP01 | TP02 | TP03 — TP02 pagamento completo, TP01 a rate, TP03 anticipo
iban string | null — Predefinito: IBAN delle impostazioni di fatturazione
related_invoice_id string | null — Fattura di riferimento (note di credito/debito)
pa_reference object | null — Riferimenti obbligatori per le fatture alla Pubblica Amministrazione
lines array — Se presente sostituisce tutte le righe

bash

curl -X PATCH "https://fatturando.online/api/v1/invoices/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "causale": "Contratto di assistenza 2026",
    "lines": [
      {
        "description": "Consulenza fiscale ottobre 2026",
        "quantity": "2",
        "unit_price": "250",
        "vat_rate": "22"
      }
    ]
  }'

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "invoice",
  "document_type": "TD01",
  "series": null,
  "number": null,
  "number_label": null,
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "bozza",
  "sdi": {
    "status": null,
    "message": null,
    "id": null,
    "sent_at": null,
    "updated_at": null
  },
  "currency": "EUR",
  "causale": "Contratto di assistenza 2026",
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 0
  },
  "paid_status": "non_pagata",
  "related_invoice_id": null,
  "has_xml": false,
  "xml_file_name": null,
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "2",
      "unit": null,
      "unit_price": "250",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [],
  "issued_at": null,
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

delete/invoices/{id}Elimina una bozzainvoices:write

Solo bozze: i documenti emessi non si eliminano (409 `invoice_not_draft`).

bash

curl -X DELETE "https://fatturando.online/api/v1/invoices/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "deleted": true
}

post/invoices/{id}/issueEmetti il documentoinvoices:issue

Assegna il numero definitivo (progressivo per tipo, sezionale e anno, senza buchi), congela le anagrafiche, genera l'XML FatturaPA e lo valida contro lo schema ufficiale. Se qualcosa non va risponde 422 `issue_failed` e il numero resta libero. Non invia allo SDI: per quello usa `/send`. Genera l'evento webhook `invoice.issued`.

bash

curl -X POST "https://fatturando.online/api/v1/invoices/<id>/issue" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "invoice",
  "document_type": "TD01",
  "series": null,
  "number": 42,
  "number_label": "42",
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "emessa",
  "sdi": {
    "status": null,
    "message": null,
    "id": null,
    "sent_at": null,
    "updated_at": null
  },
  "currency": "EUR",
  "causale": null,
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 0
  },
  "paid_status": "non_pagata",
  "related_invoice_id": null,
  "has_xml": true,
  "xml_file_name": "IT01234567897_A3K9P.xml",
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "1",
      "unit": null,
      "unit_price": "500",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [
    {
      "due_date": "2026-11-14",
      "amount_cents": 61000,
      "paid_cents": 0,
      "paid_at": null,
      "method": null
    }
  ],
  "issued_at": "2026-10-15T09:15:00.000Z",
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

post/invoices/{id}/sendInvia allo SDIinvoices:issue

Trasmette l'XML di una fattura emessa all'intermediario accreditato. Richiede il collegamento SDI attivo per l'azienda (409 `sdi_not_active` altrimenti). L'esito dello SDI arriva in seguito: seguilo con l'evento webhook `invoice.sdi_updated` o rileggendo il documento (`sdi.status`). Una seconda chiamata su una fattura già trasmessa non la reinvia.

bash

curl -X POST "https://fatturando.online/api/v1/invoices/<id>/send" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "invoice",
  "document_type": "TD01",
  "series": null,
  "number": 42,
  "number_label": "42",
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "inviata",
  "sdi": {
    "status": "SENT",
    "message": null,
    "id": null,
    "sent_at": "2026-10-15T09:16:00.000Z",
    "updated_at": "2026-10-15T09:16:00.000Z"
  },
  "currency": "EUR",
  "causale": null,
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 0
  },
  "paid_status": "non_pagata",
  "related_invoice_id": null,
  "has_xml": true,
  "xml_file_name": "IT01234567897_A3K9P.xml",
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "1",
      "unit": null,
      "unit_price": "500",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [
    {
      "due_date": "2026-11-14",
      "amount_cents": 61000,
      "paid_cents": 0,
      "paid_at": null,
      "method": null
    }
  ],
  "issued_at": "2026-10-15T09:15:00.000Z",
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

post/invoices/{id}/paymentsRegistra un incassoinvoices:write

Registra un incasso (o un pagamento, per le fatture ricevute) e lo distribuisce sulle scadenze in ordine di data; l'eventuale eccedenza diventa una riga a sé. Aggiorna `paid_status`. Usa sempre `Idempotency-Key`: ripetere la chiamata senza registrerebbe l'incasso due volte. Genera l'evento webhook `invoice.payment_recorded`.

Corpo

amount_cents * integer — Importo incassato in centesimi
paid_at string — Data dell'incasso; predefinita oggi
method string
note string

bash

curl -X POST "https://fatturando.online/api/v1/invoices/<id>/payments" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_cents": 61000,
    "paid_at": "2026-11-10",
    "method": "MP05",
    "note": "Bonifico CRO 1234"
  }'

risposta

{
  "object": "invoice",
  "id": "cminv01",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "invoice",
  "document_type": "TD01",
  "series": null,
  "number": 42,
  "number_label": "42",
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "emessa",
  "sdi": {
    "status": null,
    "message": null,
    "id": null,
    "sent_at": null,
    "updated_at": null
  },
  "currency": "EUR",
  "causale": null,
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 61000
  },
  "paid_status": "pagata",
  "related_invoice_id": null,
  "has_xml": true,
  "xml_file_name": "IT01234567897_A3K9P.xml",
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "1",
      "unit": null,
      "unit_price": "500",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [
    {
      "due_date": "2026-11-14",
      "amount_cents": 61000,
      "paid_cents": 61000,
      "paid_at": "2026-11-10",
      "method": "MP05"
    }
  ],
  "issued_at": "2026-10-15T09:15:00.000Z",
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

post/invoices/{id}/credit-noteCrea una nota di creditoinvoices:write

Crea una bozza di nota di credito (TD04) che storna la fattura indicata, con le stesse righe e lo stesso cliente. Modificala con PATCH se lo storno è parziale, poi emettila. La fattura deve essere già numerata.

bash

curl -X POST "https://fatturando.online/api/v1/invoices/<id>/credit-note" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "invoice",
  "id": "cminv02",
  "company_id": "cmcomp01",
  "direction": "outgoing",
  "kind": "credit_note",
  "document_type": "TD04",
  "series": null,
  "number": null,
  "number_label": null,
  "issue_date": "2026-10-15",
  "party_id": "cmparty01",
  "status": "bozza",
  "sdi": {
    "status": null,
    "message": null,
    "id": null,
    "sent_at": null,
    "updated_at": null
  },
  "currency": "EUR",
  "causale": "Storno fattura n. 42",
  "notes": null,
  "vat_exigibility": "I",
  "withholding": null,
  "pension_fund": null,
  "stamp_duty": false,
  "pa_reference": null,
  "payment": {
    "method": "MP05",
    "terms": "TP02",
    "iban": "IT60X0542811101000000123456"
  },
  "totals": {
    "taxable_cents": 50000,
    "vat_cents": 11000,
    "pension_fund_cents": 0,
    "withholding_cents": 0,
    "total_cents": 61000,
    "net_to_pay_cents": 61000,
    "paid_cents": 0
  },
  "paid_status": "non_pagata",
  "related_invoice_id": "cminv01",
  "has_xml": false,
  "xml_file_name": null,
  "lines": [
    {
      "position": 1,
      "code": null,
      "description": "Consulenza fiscale ottobre 2026",
      "quantity": "1",
      "unit": null,
      "unit_price": "500",
      "discount_percent": null,
      "vat_rate": "22",
      "nature": null,
      "withholding": false,
      "total_cents": 50000
    }
  ],
  "payments": [],
  "issued_at": null,
  "created_at": "2026-10-15T09:12:00.000Z",
  "updated_at": "2026-10-15T09:12:00.000Z"
}

get/invoices/{id}/pdfPDF del documentoinvoices:read

Copia di cortesia in PDF. Per le bozze riporta "BOZZA" al posto del numero. Il documento fiscale resta l'XML.

bash

curl -X GET "https://fatturando.online/api/v1/invoices/<id>/pdf" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

get/invoices/{id}/xmlXML FatturaPAinvoices:read

File XML FatturaPA del documento emesso (o ricevuto dallo SDI). Per le bozze e i documenti non fiscali risponde 409 `xml_not_available`.

bash

curl -X GET "https://fatturando.online/api/v1/invoices/<id>/xml" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

10Riferimento

Scadenze

Scadenziario fiscale e attività con data.

get/deadlinesElenco scadenzedeadlines:read

Scadenze delle aziende visibili alla chiave (per gli studi: solo le aziende che hanno autorizzato l'area scadenze), ordinate per data.

Parametri

company_id — Solo le scadenze di questa azienda.
status — Filtra per stato.
from — Scadenza dal giorno (YYYY-MM-DD, incluso).
to — Scadenza fino al giorno (YYYY-MM-DD, incluso).
category — Categoria dell'adempimento.
assignee_id — Responsabile (id utente).
limit — Elementi per pagina (1–100, predefinito 25).
cursor — Valore di next_cursor della pagina precedente.

bash

curl -X GET "https://fatturando.online/api/v1/deadlines" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "data": [
    {
      "object": "deadline",
      "id": "cmb7q1x2y0003t4u5v6w7x8y9",
      "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
      "title": "Liquidazione IVA 3° trimestre",
      "category": "IVA",
      "description": null,
      "due_date": "2026-11-16",
      "original_due_date": null,
      "status": "da_preparare",
      "priority": "alta",
      "assignee_id": "cmb1a2b3c0000d4e5f6g7h8i9",
      "required_documents": [
        "Registro IVA vendite",
        "Registro IVA acquisti"
      ],
      "notes": null,
      "amount_cents": 1254300,
      "source": "manual",
      "rule": null,
      "completed_at": null,
      "verified_at": null,
      "created_at": "2026-10-01T08:30:00.000Z",
      "updated_at": "2026-10-01T08:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

get/deadlines/{id}Dettaglio scadenza con storicodeadlines:read

bash

curl -X GET "https://fatturando.online/api/v1/deadlines/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "deadline",
  "id": "cmb7q1x2y0003t4u5v6w7x8y9",
  "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "title": "Liquidazione IVA 3° trimestre",
  "category": "IVA",
  "description": null,
  "due_date": "2026-11-16",
  "original_due_date": null,
  "status": "da_preparare",
  "priority": "alta",
  "assignee_id": "cmb1a2b3c0000d4e5f6g7h8i9",
  "required_documents": [
    "Registro IVA vendite",
    "Registro IVA acquisti"
  ],
  "notes": null,
  "amount_cents": 1254300,
  "source": "manual",
  "rule": null,
  "completed_at": null,
  "verified_at": null,
  "created_at": "2026-10-01T08:30:00.000Z",
  "updated_at": "2026-10-01T08:30:00.000Z",
  "events": [
    {
      "id": "cmb7q1x2y0004t4u5v6w7x8y9",
      "kind": "CREATA",
      "from_value": null,
      "to_value": null,
      "note": "Inserita manualmente",
      "actor_id": "cmb1a2b3c0000d4e5f6g7h8i9",
      "created_at": "2026-10-01T08:30:00.000Z"
    }
  ]
}

post/deadlinesCrea una scadenzadeadlines:write

Scadenza manuale, già confermata. Se la data è passata nasce nello stato `scaduta`. Il responsabile deve essere un membro attivo dell'organizzazione. Genera l'evento webhook `deadline.created`.

Corpo

company_id * string
title * string
category * IVA | F24 | IMPOSTE | DICHIARAZIONI | BILANCIO | CAMERALE | CONTRIBUTI | RITENUTE | SOCIETARIO | CONTRATTI | PAGAMENTI | DOCUMENTALE | DELEGHE | ALTRO
due_date * string
priority bassa | media | alta | critica
assignee_id string | null
required_documents array
notes string | null
description string | null
amount_cents integer | null — Importo previsto in centesimi

bash

curl -X POST "https://fatturando.online/api/v1/deadlines" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
    "title": "Liquidazione IVA 3° trimestre",
    "category": "IVA",
    "due_date": "2026-11-16",
    "priority": "alta",
    "assignee_id": "cmb1a2b3c0000d4e5f6g7h8i9",
    "required_documents": [
      "Registro IVA vendite",
      "Registro IVA acquisti"
    ],
    "amount_cents": 1254300
  }'

risposta

{
  "object": "deadline",
  "id": "cmb7q1x2y0003t4u5v6w7x8y9",
  "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "title": "Liquidazione IVA 3° trimestre",
  "category": "IVA",
  "description": null,
  "due_date": "2026-11-16",
  "original_due_date": null,
  "status": "da_preparare",
  "priority": "alta",
  "assignee_id": "cmb1a2b3c0000d4e5f6g7h8i9",
  "required_documents": [
    "Registro IVA vendite",
    "Registro IVA acquisti"
  ],
  "notes": null,
  "amount_cents": 1254300,
  "source": "manual",
  "rule": null,
  "completed_at": null,
  "verified_at": null,
  "created_at": "2026-10-01T08:30:00.000Z",
  "updated_at": "2026-10-01T08:30:00.000Z",
  "events": []
}

patch/deadlines/{id}Modifica priorità, responsabile, note, documenti richiestideadlines:write

Aggiorna solo i campi presenti. Per data e stato usa `/postpone` e `/status`.

Corpo

priority bassa | media | alta | critica
assignee_id string | null — null per togliere il responsabile
notes string | null
required_documents array
reminder_offsets array — Giorni di anticipo dei promemoria

bash

curl -X PATCH "https://fatturando.online/api/v1/deadlines/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "priority": "critica",
    "assignee_id": "cmb1a2b3c0000d4e5f6g7h8i9",
    "notes": "Attendere estratti conto di settembre",
    "reminder_offsets": [
      15,
      7,
      1
    ]
  }'

post/deadlines/{id}/statusCambia lo statodeadlines:write

Stesse regole dell'app: `verificata` solo dopo `eseguita`, da una persona diversa da chi l'ha eseguita (salvo l'amministratore dello studio) e solo se chi ha creato la chiave ha il permesso di verifica; `annullata` richiede `note` con il motivo. Genera l'evento webhook `deadline.status_changed`.

Corpo

status * da_preparare | in_lavorazione | attesa_cliente | da_approvare | eseguita | verificata | annullata
note string | null — Obbligatoria per annullare

bash

curl -X POST "https://fatturando.online/api/v1/deadlines/<id>/status" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "status": "eseguita",
    "note": "F24 trasmesso, protocollo 2026111612345"
  }'

post/deadlines/{id}/postponeProroga la scadenzadeadlines:write

Sposta la data: la prima data resta in `original_due_date` e nello storico. Una scadenza `scaduta` prorogata a una data futura torna `da_preparare`.

Corpo

due_date * string
note * string

bash

curl -X POST "https://fatturando.online/api/v1/deadlines/<id>/postpone" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "due_date": "2026-12-01",
    "note": "Proroga DPCM 28/10/2026"
  }'

11Riferimento

Documenti

Archivio documentale con versioni e conservazione.

get/documentsElenco documentidocuments:read

Ultima versione dei documenti non eliminati delle aziende visibili alla chiave, dai più recenti. Per le imprese sono esclusi i documenti che lo studio ha reso non visibili al cliente.

Parametri

company_id — Solo i documenti di questa azienda.
year — Anno di riferimento.
category — Categoria.
q — Cerca nel nome, nella descrizione e nei tag.
limit — Elementi per pagina (1–100, predefinito 25).
cursor — Valore di next_cursor della pagina precedente.

bash

curl -X GET "https://fatturando.online/api/v1/documents" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "data": [
    {
      "object": "document",
      "id": "cmc2d3e4f0005g6h7i8j9k0l1",
      "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
      "name": "Estratto conto settembre 2026.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 248311,
      "sha256": "9f2c4e0b1d7a5e3f8c6b2a4d0e9f7c1b3a5d8e2f4c6b0a9d7e5f3c1b8a6d4e2f",
      "year": 2026,
      "category": "BANCA",
      "tags": [
        "banca",
        "settembre"
      ],
      "description": "Conto corrente principale",
      "version": 1,
      "lineage_id": "cmc2d3e4f0005g6h7i8j9k0l1",
      "is_latest": true,
      "visible_to_client": true,
      "deadline_id": null,
      "request_id": "cmc9r8q7p0006o5n4m3l2k1j0",
      "retention_until": "2036-12-31",
      "deleted": false,
      "created_at": "2026-10-03T10:12:45.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

get/documents/{id}Dettaglio documentodocuments:read

bash

curl -X GET "https://fatturando.online/api/v1/documents/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "document",
  "id": "cmc2d3e4f0005g6h7i8j9k0l1",
  "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "name": "Estratto conto settembre 2026.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 248311,
  "sha256": "9f2c4e0b1d7a5e3f8c6b2a4d0e9f7c1b3a5d8e2f4c6b0a9d7e5f3c1b8a6d4e2f",
  "year": 2026,
  "category": "BANCA",
  "tags": [
    "banca",
    "settembre"
  ],
  "description": "Conto corrente principale",
  "version": 1,
  "lineage_id": "cmc2d3e4f0005g6h7i8j9k0l1",
  "is_latest": true,
  "visible_to_client": true,
  "deadline_id": null,
  "request_id": "cmc9r8q7p0006o5n4m3l2k1j0",
  "retention_until": "2036-12-31",
  "deleted": false,
  "created_at": "2026-10-03T10:12:45.000Z"
}

get/documents/{id}/downloadScarica il filedocuments:read

Restituisce il file originale con il suo `Content-Type` (es. `application/pdf`) e `Content-Disposition: attachment`. Lo scaricamento resta nello storico del documento.

bash

curl -X GET "https://fatturando.online/api/v1/documents/<id>/download" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

post/documentsCarica un documentodocuments:write

Un file per richiesta, in `multipart/form-data`. Il contenuto è verificato (estensione, MIME, magic bytes): un file non valido dà 422 `invalid_file`. Un file identico già presente per l'azienda dà 409 `duplicate_document` con `details.existing_document_id`. Con `request_id` la richiesta documentale passa a `ricevuta`. Genera l'evento webhook `document.uploaded`.

Corpo

company_id * string
category * FATTURE_ATTIVE | FATTURE_PASSIVE | BANCA | F24 | DICHIARAZIONI | BILANCI | SOCIETARI | CONTRATTI | PAGHE | IDENTITA | DELEGHE | ALTRO | PEC
year * integer
description string
tags string — Tag separati da virgola
deadline_id string
request_id string
visible_to_client true | false — Solo per gli studi: false tiene il documento riservato allo studio
file * string — Il file (max 25 MB; pdf, png, jpg, jpeg, webp, xml, p7m, csv, xlsx, docx, txt, zip)

bash

curl -X POST "https://fatturando.online/api/v1/documents" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -F "file=@fattura.pdf" -F "company_id=<id>" -F "category=FATTURE_PASSIVE"

risposta

{
  "object": "document",
  "id": "cmc2d3e4f0005g6h7i8j9k0l1",
  "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "name": "Estratto conto settembre 2026.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 248311,
  "sha256": "9f2c4e0b1d7a5e3f8c6b2a4d0e9f7c1b3a5d8e2f4c6b0a9d7e5f3c1b8a6d4e2f",
  "year": 2026,
  "category": "BANCA",
  "tags": [
    "banca",
    "settembre"
  ],
  "description": "Conto corrente principale",
  "version": 1,
  "lineage_id": "cmc2d3e4f0005g6h7i8j9k0l1",
  "is_latest": true,
  "visible_to_client": true,
  "deadline_id": null,
  "request_id": "cmc9r8q7p0006o5n4m3l2k1j0",
  "retention_until": "2036-12-31",
  "deleted": false,
  "created_at": "2026-10-03T10:12:45.000Z"
}

12Riferimento

Richieste documentali

Documenti richiesti dallo studio al cliente.

get/document-requestsElenco richiesterequests:read

Per uno studio le richieste che ha inviato; per un'impresa quelle ricevute dai suoi studi. Dalle più recenti.

Parametri

company_id — Solo le richieste per questa azienda.
status — Filtra per stato.
limit — Elementi per pagina (1–100, predefinito 25).
cursor — Valore di next_cursor della pagina precedente.

bash

curl -X GET "https://fatturando.online/api/v1/document-requests" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "data": [
    {
      "object": "document_request",
      "id": "cmc9r8q7p0006o5n4m3l2k1j0",
      "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
      "title": "Estratti conto settembre",
      "description": "Tutti i conti correnti aziendali, in PDF",
      "category": "BANCA",
      "due_date": "2026-10-20",
      "status": "aperta",
      "deadline_id": "cmb7q1x2y0003t4u5v6w7x8y9",
      "fulfilled_at": null,
      "created_at": "2026-10-01T09:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

get/document-requests/{id}Dettaglio richiestarequests:read

Include gli id dei documenti caricati per la richiesta (ultima versione, visibili alla chiave).

bash

curl -X GET "https://fatturando.online/api/v1/document-requests/<id>" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "document_request",
  "id": "cmc9r8q7p0006o5n4m3l2k1j0",
  "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "title": "Estratti conto settembre",
  "description": "Tutti i conti correnti aziendali, in PDF",
  "category": "BANCA",
  "due_date": "2026-10-20",
  "status": "ricevuta",
  "deadline_id": "cmb7q1x2y0003t4u5v6w7x8y9",
  "fulfilled_at": "2026-10-03T10:12:45.000Z",
  "created_at": "2026-10-01T09:00:00.000Z",
  "document_ids": [
    "cmc2d3e4f0005g6h7i8j9k0l1"
  ]
}

post/document-requestsChiedi documenti al clienterequests:write

Solo per gli studi. Se l'impresa usa il portale riceve una notifica e un'email; altrimenti la richiesta è solo registrata. Genera l'evento webhook `document_request.created`.

Corpo

company_id * string
title * string
description string | null
category FATTURE_ATTIVE | FATTURE_PASSIVE | BANCA | F24 | DICHIARAZIONI | BILANCI | SOCIETARI | CONTRATTI | PAGHE | IDENTITA | DELEGHE | ALTRO | PEC
due_date string | null
deadline_id string | null

bash

curl -X POST "https://fatturando.online/api/v1/document-requests" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
    "title": "Estratti conto settembre",
    "description": "Tutti i conti correnti aziendali, in PDF",
    "category": "BANCA",
    "due_date": "2026-10-20",
    "deadline_id": "cmb7q1x2y0003t4u5v6w7x8y9"
  }'

risposta

{
  "object": "document_request",
  "id": "cmc9r8q7p0006o5n4m3l2k1j0",
  "company_id": "cmb3k2v0q0001s6p8a1b2c3d4",
  "title": "Estratti conto settembre",
  "description": "Tutti i conti correnti aziendali, in PDF",
  "category": "BANCA",
  "due_date": "2026-10-20",
  "status": "aperta",
  "deadline_id": "cmb7q1x2y0003t4u5v6w7x8y9",
  "fulfilled_at": null,
  "created_at": "2026-10-01T09:00:00.000Z"
}

13Riferimento

Contabilità

Contabilità generale in partita doppia, in sola lettura: piano dei conti, libro giornale, bilancio di verifica e bilancio CEE.

get/accounting/accountsPiano dei contiaccounting:read

Conti dell'azienda ordinati per codice, con la voce CEE (art. 2424/2425 c.c.) e i sottoconti di clienti e fornitori. 409 `accounting_disabled` se la contabilità non è attiva.

Parametri

company_id * — Azienda (obbligatoria).
limit — Elementi per pagina (1–100, predefinito 25).
cursor — Valore di next_cursor della pagina precedente.

bash

curl -X GET "https://fatturando.online/api/v1/accounting/accounts" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

get/accounting/journalLibro giornaleaccounting:read

Registrazioni del periodo in ordine di data e protocollo, con le righe in dare e avere. Importi in centesimi.

Parametri

company_id * — Azienda (obbligatoria).
year — Esercizio (anno di chiusura). Predefinito: quello in corso.
from — Inizio del periodo, YYYY-MM-DD, dentro l'esercizio.
to — Fine del periodo, YYYY-MM-DD, dentro l'esercizio.
limit — Elementi per pagina (1–100, predefinito 25).
cursor — Valore di next_cursor della pagina precedente.

bash

curl -X GET "https://fatturando.online/api/v1/accounting/journal" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

risposta

{
  "object": "list",
  "has_more": false,
  "next_cursor": null,
  "data": [
    {
      "object": "journal_entry",
      "id": "cmc1j2k3l0001m2n3o4p5q6r7",
      "year": 2026,
      "number": 42,
      "date": "2026-03-05",
      "document_number": "12",
      "document_date": "2026-03-05",
      "causal": "FV",
      "description": "Fattura n. 12 a Rossi Arredamenti S.r.l.",
      "source": "fattura",
      "invoice_id": "cmb9x8y7z0001a2b3c4d5e6f7",
      "party_id": "cmb4p5q6r0001s2t3u4v5w6x7",
      "total_cents": 122000,
      "lines": [
        {
          "account_id": "cmc0a",
          "account_code": "06.01.0001",
          "account_name": "Rossi Arredamenti S.r.l.",
          "debit_cents": 122000,
          "credit_cents": 0,
          "description": null
        },
        {
          "account_id": "cmc0b",
          "account_code": "20.02",
          "account_name": "Ricavi per prestazioni di servizi",
          "debit_cents": 0,
          "credit_cents": 100000,
          "description": null
        },
        {
          "account_id": "cmc0c",
          "account_code": "14.01",
          "account_name": "IVA su vendite",
          "debit_cents": 0,
          "credit_cents": 22000,
          "description": null
        }
      ]
    }
  ]
}

get/accounting/trial-balanceBilancio di verificaaccounting:read

Saldi iniziali, movimenti e saldi finali dei conti movimentati nel periodo, escluse le scritture di chiusura dell'esercizio.

Parametri

company_id * — Azienda (obbligatoria).
year — Esercizio (anno di chiusura). Predefinito: quello in corso.
from — Inizio del periodo, YYYY-MM-DD, dentro l'esercizio.
to — Fine del periodo, YYYY-MM-DD, dentro l'esercizio.

bash

curl -X GET "https://fatturando.online/api/v1/accounting/trial-balance" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

get/accounting/balance-sheetStato patrimoniale e conto economico CEEaccounting:read

Schemi degli artt. 2424 e 2425 c.c. alla fine del periodo, con totali per voce. Codici delle voci: AT (attivo), PA (passivo), CE (conto economico), es. `AT.C.II.1`. I costi del conto economico sono importi positivi; il risultato è in `results.net_result_cents` e in `PA.A.IX`. Prospetto contabile: va verificato dal professionista prima del deposito.

Parametri

company_id * — Azienda (obbligatoria).
year — Esercizio (anno di chiusura). Predefinito: quello in corso.
from — Inizio del periodo, YYYY-MM-DD, dentro l'esercizio.
to — Fine del periodo, YYYY-MM-DD, dentro l'esercizio.

bash

curl -X GET "https://fatturando.online/api/v1/accounting/balance-sheet" \
  -H "Authorization: Bearer $FATTURANDO_API_KEY"

La specifica completa, importabile in Postman, Insomnia o in un generatore di client, è su /api/v1/openapi.json.