Tipi di documento & di fattura

Ogni documento che invii passa per un unico endpoint — POST /v1/documents/send — e un solo campo type dice a Flowie di cosa si tratta. Questa pagina è il referenziale completo: gli otto tipi di documento, i quattro sottotipi di fattura (comprese le fatture autofatturate) e in cosa differiscono i due significati di autofattura — l'autofatturazione e l'autofattura in inversione contabile — con il modo di emettere ciascuno.

Prova qualsiasi caso d'uso

Ogni scenario di questa pagina ha un corpo d'esempio pronto da inviare per POST /v1/documents/send. Espandine uno e premi Prova nel Playground — apre il costruttore di richieste precompilato con il payload, e il Playground carica automaticamente la tua chiave sandbox — oppure copia il JSON o un comando curl pronto. Ogni esempio usa gli identificativi di test del sandbox, quindi funziona così com'è.

{
  "type": "invoice",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "INV-2026-0042",
    "issueDate": "2026-04-15",
    "currency": "EUR",
    "lines": [
      { "description": "Consulting services", "quantity": 10, "unitPrice": 150.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "invoice",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "INV-2026-0500",
    "issueDate": "2026-04-15",
    "currency": "EUR",
    "lines": [
      { "description": "Consulting (standard rate)", "quantity": 10, "unit": "HUR", "unitPrice": 150.00, "vatRate": 21.0, "vatCategory": "S" },
      { "description": "E-book (reduced rate)", "quantity": 3, "unit": "C62", "unitPrice": 40.00, "vatRate": 6.0, "vatCategory": "S" },
      { "description": "Support plan (per month)", "quantity": 12, "unit": "MON", "unitPrice": 99.00, "vatRate": 21.0, "vatCategory": "S" },
      { "description": "Intra-EU goods (exempt)", "quantity": 1, "unit": "C62", "unitPrice": 500.00, "vatRate": 0.0, "vatCategory": "K", "vatExemptionReason": "Intra-Community supply, art. 138 Directive 2006/112/EC", "vatExemptionCode": "VATEX-EU-IC" }
    ]
  }
}

{
  "type": "invoice",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "INV-2026-0501",
    "issueDate": "2026-04-30",
    "currency": "EUR",
    "orderReference": "PO-2026-0042",
    "lines": [
      { "description": "Managed hosting", "quantity": 1, "unit": "MON", "unitPrice": 1200.00, "vatRate": 21.0, "vatCategory": "S", "itemCode": "SKU-HOST-PRO" },
      { "description": "Steel bar", "quantity": 250, "unit": "KGM", "unitPrice": 3.20, "vatRate": 21.0, "vatCategory": "S", "itemCode": "SKU-STEEL-16" }
    ]
  }
}

{
  "type": "invoice",
  "documentSubtype": "PREPAYMENT_INVOICE",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "ACPT-2026-0042",
    "issueDate": "2026-04-15",
    "currency": "EUR",
    "orderReference": "PO-2026-0042",
    "note": "Acompte 30 percent - commande PO-2026-0042",
    "lines": [
      { "description": "Advance - 30 percent of project fee", "quantity": 1, "unitPrice": 3000.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "invoice",
  "documentSubtype": "CORRECTED_INVOICE",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "INV-2026-0042-R1",
    "issueDate": "2026-04-20",
    "currency": "EUR",
    "billingReference": "INV-2026-0042",
    "billingReferenceDate": "2026-04-15",
    "lines": [
      { "description": "Consulting services (corrected quantity)", "quantity": 8, "unitPrice": 150.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "credit-note",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "CN-2026-0007",
    "issueDate": "2026-05-02",
    "currency": "EUR",
    "billingReference": "INV-2026-0042",
    "billingReferenceDate": "2026-04-15",
    "lines": [
      { "description": "Refund - consulting services", "quantity": 2, "unitPrice": 150.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "debit-note",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "DN-2026-0003",
    "issueDate": "2026-05-05",
    "currency": "EUR",
    "billingReference": "INV-2026-0042",
    "billingReferenceDate": "2026-04-15",
    "lines": [
      { "description": "Late-delivery surcharge", "quantity": 1, "unitPrice": 90.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "invoice",
  "selfBilled": true,
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "SB-2026-0100",
    "issueDate": "2026-04-15",
    "currency": "EUR",
    "lines": [
      { "description": "Grain delivery - March", "quantity": 12, "unitPrice": 210.00, "vatRate": 6.0 }
    ]
  }
}

{
  "type": "invoice",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "RC-2026-0055",
    "issueDate": "2026-04-15",
    "currency": "EUR",
    "note": "Reverse charge - VAT to be accounted for by the customer",
    "lines": [
      {
        "description": "Cross-border consulting (reverse charge)",
        "quantity": 5,
        "unitPrice": 200.00,
        "vatRate": 0.0,
        "vatCategory": "AE",
        "vatExemptionReason": "Reverse charge, art. 196 Directive 2006/112/EC",
        "vatExemptionCode": "VATEX-EU-AE"
      }
    ]
  }
}

{
  "type": "invoice",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "INV-2026-0200",
    "issueDate": "2026-04-15",
    "currency": "EUR",
    "parties": [
      { "role": "seller", "id": "0009:FR86797978996", "name": "ACME FRANCE", "initiator": true },
      { "role": "buyer", "id": "0009:BE0123456789", "name": "MEGACORP BE" },
      { "role": "payee", "vatNumber": "FR90123456789", "name": "ACME FACTORING SAS" }
    ],
    "lines": [
      { "description": "Consulting services", "quantity": 10, "unitPrice": 150.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "purchase-request",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "PR-2026-0042",
    "issueDate": "2026-04-08",
    "currency": "EUR",
    "lines": [
      { "description": "Office chairs (requisition)", "quantity": 20, "unitPrice": 120.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "purchase-order",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "PO-2026-0042",
    "issueDate": "2026-04-10",
    "currency": "EUR",
    "lines": [
      { "description": "Office chairs", "quantity": 20, "unitPrice": 120.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "sales-order",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "SO-2026-0042",
    "issueDate": "2026-04-11",
    "currency": "EUR",
    "orderReference": "PO-2026-0042",
    "lines": [
      { "description": "Office chairs", "quantity": 20, "unitPrice": 120.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "quote",
  "from": "0009:FR86797978996",
  "to": "0009:BE0123456789",
  "document": {
    "number": "Q-2026-0042",
    "issueDate": "2026-04-01",
    "currency": "EUR",
    "lines": [
      { "description": "Annual support plan", "quantity": 1, "unitPrice": 5000.00, "vatRate": 21.0 }
    ]
  }
}

{
  "type": "event",
  "from": "0009:FR86797978996",
  "document": {
    "number": "INV-2026-0042"
  }
}

Due assi: tipo di documento & sottotipo di fattura

Conviene tenere distinti due concetti:

• Tipo di documento (type) — che genere di documento è: una fattura, una nota di credito, un ordine, un preventivo. È un'enumerazione fissa e guida l'instradamento Peppol (quale tipo di documento il destinatario deve poter ricevere).
• Sottotipo di fattura (documentSubtype) — che genere di fattura, quando type: "invoice". Viene reso come l'InvoiceTypeCode UBL (BT-3) tramite la lista di codici UNCL1001 — 380 per una normale fattura commerciale, 386/384/389 per acconto / rettificativa / autofatturata.

Una nota di credito porta un proprio codice UNCL1001 (381) derivato da type: "credit-note"; per essa non si imposta documentSubtype. L'asse dei sottotipi serve solo a distinguere i sottogeneri di una fattura.

Tipi di documento (type)

L'enumerazione type su POST /v1/documents/send. I primi sei sono documenti commerciali instradati via Peppol e richiedono un to; event è un semplice record di osservabilità, senza destinatario.

Un invio di fattura minimo:

curl -X POST https://api.flowie.ink/v1/documents/send \
  -H "Authorization: Bearer $FLOWIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "from": "0009:FR86797978996",
    "to":   "0009:BE0123456789",
    "document": {
      "number": "INV-2026-0042",
      "issueDate": "2026-04-15",
      "currency": "EUR",
      "lines": [
        { "description": "Consulting services", "quantity": 10, "unitPrice": 150.00, "vatRate": 21.0 }
      ]
    }
  }'

Sottotipi di fattura (documentSubtype)

Quando type: "invoice", il campo opzionale documentSubtype seleziona l'InvoiceTypeCode UNCL1001 (BT-3) reso sull'UBL. Accetta il nome in CAPITAL_SNAKE_CASE o il codice numerico grezzo (es. "386"). È valido solo per type: "invoice" — inviarlo su qualsiasi altro tipo restituisce un 400. I quattro qui sotto sono i sottogeneri nominati e modellati; poiché il campo è un pass-through UNCL1001, qualsiasi altro codice BT-3 valido che invii viene etichettato e reso così com'è.

Note di credito & di debito

Una nota di credito (type: "credit-note", UNCL1001 381) riduce o annulla una fattura precedente; una nota di debito (type: "debit-note", 383) la aumenta. Entrambe sono documenti a pieno titolo che seguono lo stesso ciclo di vita di una fattura — una nota di credito non è uno stato del ciclo di vita della fattura originale.

Nella riforma francese, entrambe devono riferirsi alla fattura che rettificano tramite document.billingReference (BT-25, l'BillingReference/InvoiceDocumentReference/ID UBL) e, se nota, document.billingReferenceDate (BT-26). Omettere il riferimento su una nota di credito/debito FR fallisce la validazione (BR-FR-CO-04/BR-FR-CO-05).

curl -X POST https://api.flowie.ink/v1/documents/send \
  -H "Authorization: Bearer $FLOWIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "credit-note",
    "from": "0009:FR86797978996",
    "to":   "0009:BE0123456789",
    "document": {
      "number": "CN-2026-0007",
      "issueDate": "2026-05-02",
      "currency": "EUR",
      "billingReference": "INV-2026-0042",
      "billingReferenceDate": "2026-04-15",
      "lines": [
        { "description": "Refund — consulting services", "quantity": 2, "unitPrice": 150.00, "vatRate": 21.0 }
      ]
    }
  }'

Fatture di acconto (facture d'acompte)

Una fattura di acconto — fattura di anticipo / primo versamento — fattura un importo prima che i beni siano consegnati o il servizio completato. È una vera fattura a pieno titolo, soggetta a IVA (con un proprio numero e, quando l'acconto è imponibile, IVA dovuta sull'acconto) — non una proforma né un preventivo. Etichettala con il sottotipo UNCL1001 386 tramite documentSubtype:

curl -X POST https://api.flowie.ink/v1/documents/send \
  -H "Authorization: Bearer $FLOWIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "documentSubtype": "PREPAYMENT_INVOICE",
    "from": "0009:FR86797978996",
    "to":   "0009:BE0123456789",
    "document": {
      "number": "ACPT-2026-0042",
      "issueDate": "2026-04-15",
      "currency": "EUR",
      "orderReference": "PO-2026-0042",
      "note": "Acompte 30% — commande PO-2026-0042",
      "lines": [
        { "description": "Advance — 30% of project fee", "quantity": 1, "unitPrice": 3000.00, "vatRate": 21.0 }
      ]
    }
  }'

Puoi inviare il codice numerico anziché il nome ("documentSubtype": "386") — entrambi rendono lo stesso InvoiceTypeCode UBL (BT-3). Come ogni sottotipo, è valido solo per type: "invoice".

Conguagliare l'acconto. A lavoro concluso emetti la fattura finale (a saldo) come una normale type: "invoice" (sottotipo 380) e detrai l'importo già fatturato con l'acconto, così al cliente viene addebitato solo il saldo residuo — riporta la detrazione come riga negativa (oppure, con format=ubl-xml, uno sconto a livello di documento) e cita il numero dell'acconto in document.note o document.orderReference per la tracciabilità. L'acconto e la fattura a saldo, sommati, coprono il valore totale dell'ordine.

Fattura rettificativa (facture rectificative)

Una fattura rettificativa riemette una fattura dal contenuto errato — un importo digitato male, la riga sbagliata, un'aliquota IVA errata — come nuova fattura autonoma che sostituisce l'originale invece di rettificarla. Etichettala con il sottotipo UNCL1001 384 via documentSubtype e collegala alla fattura che sostituisce con document.billingReference (BT-25) affinché la catena resti tracciabile:

curl -X POST https://api.flowie.ink/v1/documents/send \
  -H "Authorization: Bearer $FLOWIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "documentSubtype": "CORRECTED_INVOICE",
    "from": "0009:FR86797978996",
    "to":   "0009:BE0123456789",
    "document": {
      "number": "INV-2026-0042-R1",
      "issueDate": "2026-04-20",
      "currency": "EUR",
      "billingReference": "INV-2026-0042",
      "billingReferenceDate": "2026-04-15",
      "lines": [
        { "description": "Consulting services (corrected quantity)", "quantity": 8, "unitPrice": 150.00, "vatRate": 21.0 }
      ]
    }
  }'

Invia il codice numerico se preferisci ("documentSubtype": "384"); come ogni sottotipo è valida solo per type: "invoice".

Fattura rettificativa vs. nota di credito. Una fattura rettificativa (384) sostituisce l'originale con i valori corretti. Una nota di credito invece annulla o riduce l'originale lasciandola in essere — spesso seguita da una fattura nuova. Nella riforma francese la via della nota di credito è il modo abituale di correggere una fattura già trasmessa; usa 384 quando un'unica fattura rettificativa che riferisce l'originale è il record più pulito. In ogni caso, porta il collegamento in document.billingReference.

Autofatturazione (autofacturation)

L'autofatturazione è l'accordo in cui il cliente emette la fattura per conto del fornitore — comune in agricoltura, sui marketplace e per le royalty, e consentito quando le due parti l'hanno concordato. Resta una vendita a due parti tra un venditore e un acquirente distinti; cambia solo la parte che emette il documento.

Impostalo con il flag di alto livello selfBilled: true. Flowie quindi:

• tratta l'organizzazione che agisce (from) come Acquirente / iniziatore;
• tratta to come Venditore (il fornitore fatturato);
• etichetta il documento con il sottotipo UNCL1001 389 (Self-Billed Invoice).

È una scorciatoia per documentSubtype: "SELF_BILLED_INVOICE" che inoltre inverte i ruoli, ed è valida solo per type: "invoice" — le note di credito autofatturate (UNCL1001 261) non sono ancora modellate a valle, quindi selfBilled su qualsiasi altro tipo restituisce un 400.

curl -X POST https://api.flowie.ink/v1/documents/send \
  -H "Authorization: Bearer $FLOWIE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "invoice",
    "selfBilled": true,
    "from": "0009:FR86797978996",     # tu — il cliente, che emette per conto del fornitore
    "to":   "0009:BE0123456789",       # il fornitore — diventa il Venditore
    "document": {
      "number": "SB-2026-0100",
      "issueDate": "2026-04-15",
      "currency": "EUR",
      "lines": [
        { "description": "Grain delivery — March", "quantity": 12, "unitPrice": 210.00, "vatRate": 0.0 }
      ]
    }
  }'

Inversione contabile & autofattura (autofattura)

«Autofattura» indica anche un caso diverso, guidato dall'IVA: in inversione contabile (reverse charge) o su un acquisto transfrontaliero, l'acquirente emette un documento per assolvere lui stesso l'IVA, perché il fornitore non l'ha (o non ha potuto) addebitarla. Qui la stessa parte è di fatto sia venditore sia acquirente di riferimento — non è l'autofatturazione a due parti vista sopra.

Come si esprime dipende dalla giurisdizione:

• 🇮🇹 Italia (SDI). Autofatture e integrazioni portano un TipoDocumento dedicato — TD16–TD19 per l'inversione contabile e gli acquisti dall'estero, TD20/TD21/TD27/TD29 per le autofatture dove venditore = acquirente. Imposta il codice via document.note; Flowie valida le regole venditore/acquirente e di paese prima della trasmissione. Vedi la tabella completa in Tipi di documento italiani (TD01–TD29).
• Transfrontaliero / EN 16931. Sulla fattura strutturata, un'operazione in inversione contabile o esente è portata per riga con il giusto vatCategory (AE inversione contabile, K intracomunitaria, G export, E esente, O fuori campo) più un motivo di esenzione dichiarato — vedi Esenzione IVA & aliquota zero. Flowie genera la relativa ripartizione IVA BG-23, così la categoria a IVA nulla è dichiarata anziché una falsa aliquota ordinaria allo 0 %.

Ordini, preventivi & richieste d'acquisto

Non ogni documento è una fattura. Flowie trasporta anche i documenti a monte della fattura della catena procure-to-pay — quelli che portano alla fattura. Passano per lo stesso pipeline POST /v1/documents/send; cambia solo il type.

• Richiesta d'acquisto (type: "purchase-request") — una richiesta d'acquisto: la richiesta interna dell'acquirente per autorizzare un acquisto, primo passo della catena. Prova l'esempio Richiesta d'acquisto.
• Preventivo (type: "quote") — un preventivo / una proposta che il venditore invia. Nessun effetto fiscale. Prova l'esempio Preventivo.
• Ordine d'acquisto (type: "purchase-order") — l'ordine dell'acquirente al venditore. Prova l'esempio Ordine d'acquisto.
• Conferma d'ordine (type: "sales-order") — la conferma del venditore restituita all'acquirente, in coppia con l'ordine d'acquisto.

Sono documenti a monte della fattura, non fatture fiscali. Concatena l'intero filo — richiesta → preventivo → ordine → fattura — riportando document.orderReference (e document.buyerReference) da un documento al successivo, così resta collegabile da un capo all'altro.

Spese (rimborsi dipendenti & carte)

Non esiste alcun tipo di documento expense — una spesa non è qualcosa che si invia, è un costo che si contabilizza, e si mappa sul modello qui sopra in uno dei due modi seguenti, a seconda che esista o meno una fattura del fornitore:

• Spesa supportata da una fattura del fornitore (un hotel, un abbonamento SaaS, un fornitore che emette una vera fattura). È semplicemente una type: "invoice" ordinaria che ricevi — la tua azienda è l'acquirente e arriva in entrata come qualsiasi altra fattura (vedi Documento · direzione). Nulla di specifico per le spese: viene acquisita, riconciliata e registrata come fattura ricevuta. È il cas d'usage 5 della riforma francese.
• Spesa senza fattura — uno scontrino di ristorante, un biglietto di pedaggio, un taxi, un acquisto con carta aziendale. Non c'è alcuna fattura strutturata da scambiare via Peppol/PA, quindi l'importo è dichiarato all'autorità fiscale tramite e-reporting (dati di transazione / pagamento), non inviato come e-fattura. Sono i cas d'usage francesi 6 (spese senza fattura), 27 (biglietti di pedaggio), 28 (scontrini di ristorante) e 7 (carta aziendale).

Quale uso?

• Vendita ordinaria → type: "invoice" (sottotipo 380 per impostazione predefinita).
• Fatturare un anticipo prima della consegna (acconto) → type: "invoice" + documentSubtype: "PREPAYMENT_INVOICE".
• Sostituire il contenuto di una fattura → type: "invoice" + documentSubtype: "CORRECTED_INVOICE".
• Ridurre / annullare una fattura → type: "credit-note" con billingReference.
• Addebitare un importo aggiuntivo a posteriori → type: "debit-note" con billingReference.
• Sei il cliente che emette per il fornitore → type: "invoice" + selfBilled: true.
• Assolvere autonomamente l'IVA in inversione contabile (IT) → type: "invoice" + il giusto codice TD in document.note.
• Emettere una richiesta d'acquisto (richiesta interna) → type: "purchase-request".
• Ordinare / preventivare → type: "purchase-order", "sales-order" o "quote".
• Registrare un evento, senza destinatario → type: "event".
• Contabilizzare una spesa → non è un tipo da inviare: ricevi la invoice del fornitore, oppure dichiarala in e-reporting quando non c'è fattura.

Riferimenti

• Inviare un documento — l'endpoint, tutti i campi inclusi type, documentSubtype e selfBilled.
• Parti multiple — parti esplicite etichettate per ruolo per l'autofatturazione con un terzo.
• Esenzione IVA & aliquota zero — categorie IVA e motivi di esenzione per operazioni in inversione contabile ed esenti.
• Modello dati · Documento — i tre campi di stato ortogonali di ogni documento.
• Italia · Tipi di documento (TD01–TD29) — il referenziale completo dei TipoDocumento, comprese le autofatture.