Types de documents & de factures

Chaque document que vous envoyez passe par un seul endpoint — POST /v1/documents/send — et un unique champ type indique à Flowie de quoi il s'agit. Cette page est le référentiel complet : les huit types de documents, les quatre sous-types de facture (dont les factures autofacturées), et en quoi les deux sens du mot autofacture — l'autofacturation et l'autofacture en autoliquidation — diffèrent, avec la manière d'émettre chacun.

Tester n'importe quel cas d'usage

Chaque scénario de cette page dispose d'un corps d'exemple prêt à envoyer pour POST /v1/documents/send. Dépliez-en un et cliquez sur Essayer dans le Playground — il ouvre le constructeur de requête prérempli avec le payload, et le Playground charge automatiquement votre clé sandbox — ou copiez le JSON ou une commande curl prête à l'emploi. Chaque exemple utilise les identifiants de test du sandbox, il s'exécute donc tel quel.

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

Deux axes : type de document & sous-type de facture

Il est utile de distinguer deux notions :

• Type de document (type) — quelle sorte de document : une facture, un avoir, une commande, un devis. C'est une énumération fixe qui pilote le routage Peppol (quel type de document le destinataire doit pouvoir recevoir).
• Sous-type de facture (documentSubtype) — quelle sorte de facture, lorsque type: "invoice". Il est rendu comme l'InvoiceTypeCode UBL (BT-3) via la liste de codes UNCL1001 — 380 pour une facture commerciale ordinaire, 386/384/389 pour acompte / rectificative / autofacturée.

Un avoir porte son propre code UNCL1001 (381) dérivé de type: "credit-note" ; vous ne renseignez pas documentSubtype dans ce cas. L'axe des sous-types ne sert qu'à distinguer les sous-genres d'une facture.

Types de documents (type)

L'énumération type sur POST /v1/documents/send. Les six premiers sont des documents commerciaux routés via Peppol et exigent un to ; event est un simple enregistrement d'observabilité, sans destinataire.

Un envoi de facture minimal :

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 }
      ]
    }
  }'

Sous-types de facture (documentSubtype)

Lorsque type: "invoice", le champ optionnel documentSubtype choisit l'InvoiceTypeCode UNCL1001 (BT-3) rendu sur l'UBL. Il accepte le nom en CAPITAL_SNAKE_CASE ou le code numérique brut (p. ex. "386"). Il n'est valide que pour type: "invoice" — l'envoyer sur tout autre type renvoie un 400. Les quatre ci-dessous sont les sous-genres nommés et modélisés ; comme le champ est un pass-through UNCL1001, tout autre code BT-3 valide que vous envoyez est étiqueté et rendu tel quel.

Avoirs & notes de débit

Un avoir (type: "credit-note", UNCL1001 381) réduit ou annule une facture antérieure ; une note de débit (type: "debit-note", 383) l'augmente. Les deux sont des documents à part entière qui suivent le même cycle de vie qu'une facture — un avoir n'est pas un statut du cycle de vie de la facture d'origine.

Dans la réforme française, tous deux doivent référencer la facture qu'ils corrigent via document.billingReference (BT-25, l'BillingReference/InvoiceDocumentReference/ID UBL) et, si elle est connue, document.billingReferenceDate (BT-26). Omettre la référence sur un avoir/une note de débit FR échoue à la validation (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 }
      ]
    }
  }'

Factures d'acompte (facture d'acompte)

Une facture d'acompte — ou facture d'avance / de premier versement — facture un montant avant que les biens soient livrés ou la prestation achevée. C'est une véritable facture à part entière, soumise à la TVA (avec son propre numéro et, lorsque l'acompte est taxable, la TVA due sur l'acompte) — ni une proforma ni un devis. Étiquetez-la avec le sous-type UNCL1001 386 via 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 }
      ]
    }
  }'

Vous pouvez envoyer le code numérique au lieu du nom ("documentSubtype": "386") — les deux rendent le même InvoiceTypeCode UBL (BT-3). Comme tout sous-type, il n'est valide que pour type: "invoice".

Solder l'acompte. Une fois la prestation réalisée, vous émettez la facture finale (de solde) comme une facture type: "invoice" ordinaire (sous-type 380) et déduisez le montant déjà facturé sur l'acompte, afin que le client ne soit facturé que du solde restant — portez la déduction en ligne négative (ou, avec format=ubl-xml, en remise au niveau du document) et citez le numéro de l'acompte dans document.note ou document.orderReference pour la piste d'audit. L'acompte et la facture de solde additionnés couvrent la valeur totale de la commande.

Facture rectificative (facture rectificative)

Une facture rectificative réémet une facture au contenu erroné — un montant mal saisi, la mauvaise ligne, un taux de TVA incorrect — sous la forme d'une nouvelle facture autonome qui remplace l'originale au lieu de l'ajuster. Étiquetez-la avec le sous-type UNCL1001 384 via documentSubtype, et pointez-la vers la facture qu'elle remplace avec document.billingReference (BT-25) pour que la chaîne reste traçable :

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 }
      ]
    }
  }'

Envoyez le code numérique si vous préférez ("documentSubtype": "384") ; comme tout sous-type, elle n'est valide que pour type: "invoice".

Facture rectificative vs. avoir. Une facture rectificative (384) remplace l'originale avec les bons chiffres. Un avoir au contraire annule ou réduit l'originale en la laissant en place — souvent suivi d'une facture toute neuve. Dans la réforme française, la voie de l'avoir est la manière habituelle de corriger une facture déjà transmise ; optez pour 384 lorsqu'une seule facture rectificative référençant l'originale constitue l'enregistrement le plus propre. Dans tous les cas, portez le lien dans document.billingReference.

Autofacturation (autofacturation)

L'autofacturation est le dispositif où le client émet la facture pour le compte du fournisseur — courant en agriculture, sur les marketplaces et pour les redevances, et permis lorsque les deux parties en ont convenu. Cela reste une vente à deux parties entre un vendeur et un acheteur distincts ; seule change la partie qui émet le document.

Activez-le avec le drapeau de haut niveau selfBilled: true. Flowie alors :

• traite l'organisation qui agit (from) comme l'Acheteur / initiateur ;
• traite to comme le Vendeur (le fournisseur facturé) ;
• étiquette le document avec le sous-type UNCL1001 389 (Self-Billed Invoice).

C'est un raccourci pour documentSubtype: "SELF_BILLED_INVOICE" qui inverse aussi les rôles, et il n'est valide que pour type: "invoice" — les avoirs autofacturés (UNCL1001 261) ne sont pas encore modélisés en aval, donc selfBilled sur tout autre type renvoie 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",     # vous — le client, qui émet pour le compte du fournisseur
    "to":   "0009:BE0123456789",       # le fournisseur — devient le Vendeur
    "document": {
      "number": "SB-2026-0100",
      "issueDate": "2026-04-15",
      "currency": "EUR",
      "lines": [
        { "description": "Grain delivery — March", "quantity": 12, "unitPrice": 210.00, "vatRate": 0.0 }
      ]
    }
  }'

Autoliquidation & autofacture (autofattura)

« Autofacture » désigne aussi un cas différent, dicté par la TVA : sous autoliquidation ou sur un achat transfrontalier, l'acheteur émet un document pour comptabiliser lui-même la TVA, parce que le fournisseur ne l'a pas (ou n'a pas pu la) facturer. Ici la même partie est de fait à la fois vendeur et acheteur de référence — ce n'est pas l'autofacturation à deux parties ci-dessus.

La manière de l'exprimer dépend de la juridiction :

• 🇮🇹 Italie (SDI). Les autofactures et intégrations portent un TipoDocumento dédié — TD16–TD19 pour l'autoliquidation et les achats à l'étranger, TD20/TD21/TD27/TD29 pour les autofatture où vendeur = acheteur. Définissez le code via document.note ; Flowie valide les règles vendeur/acheteur et de pays avant transmission. Voir le tableau complet sur Types de documents italiens (TD01–TD29).
• Transfrontalier / EN 16931. Sur la facture structurée, une opération en autoliquidation ou exonérée est portée par ligne avec le bon vatCategory (AE autoliquidation, K intracommunautaire, G export, E exonéré, O hors champ) plus un motif d'exonération explicite — voir Exonération de TVA & taux zéro. Flowie génère la ventilation de TVA BG-23 correspondante, de sorte que la catégorie à TVA nulle est déclarée plutôt qu'un faux taux standard à 0 %.

Commandes, devis & demandes d'achat

Tout document n'est pas une facture. Flowie transporte aussi les documents en amont de la facture de la chaîne procure-to-pay — ceux qui y mènent. Ils passent par le même pipeline POST /v1/documents/send ; seul le type change.

• Demande d'achat (type: "purchase-request") — une demande d'achat : la requête interne de l'acheteur pour autoriser un achat, première étape de la chaîne. Essayez l'exemple Demande d'achat.
• Devis (type: "quote") — un devis / une proposition que le vendeur envoie. Sans effet fiscal. Essayez l'exemple Devis.
• Bon de commande (type: "purchase-order") — la commande de l'acheteur au vendeur. Essayez l'exemple Bon de commande.
• Accusé de commande (type: "sales-order") — l'accusé du vendeur renvoyé à l'acheteur, en pendant du bon de commande.

Ce sont des documents en amont de la facture, pas des factures fiscales. Chaînez tout le fil — demande d'achat → devis → commande → facture — en reportant document.orderReference (et document.buyerReference) d'un document au suivant, pour qu'il reste reliable de bout en bout.

Frais (dépenses des collaborateurs & cartes)

Il n'existe aucun type de document expense — un frais n'est pas quelque chose que l'on envoie, c'est une dépense que l'on comptabilise, et il se rattache au modèle ci-dessus de l'une des deux façons suivantes selon qu'une facture fournisseur existe ou non :

• Frais adossé à une facture fournisseur (un hôtel, un abonnement SaaS, un fournisseur qui émet une vraie facture). C'est simplement une type: "invoice" ordinaire que vous recevez — votre entreprise est l'acheteur, et elle arrive en entrée comme n'importe quelle autre facture (voir Document · direction). Rien de spécifique aux frais : elle est capturée, rapprochée et comptabilisée comme une facture reçue. C'est le cas d'usage 5 de la réforme française.
• Frais sans facture — un ticket de restaurant, un ticket de péage, un taxi, un achat par carte logée. Il n'y a aucune facture structurée à échanger via Peppol/PA, donc le montant est déclaré à l'administration fiscale par e-reporting (des données de transaction / de paiement), et non envoyé comme e-facture. Ce sont les cas d'usage français 6 (frais sans facture), 27 (tickets de péage), 28 (notes de restaurant) et 7 (carte bancaire logée).

Lequel utiliser ?

• Vente ordinaire → type: "invoice" (sous-type 380 par défaut).
• Facturer une avance avant livraison (acompte) → type: "invoice" + documentSubtype: "PREPAYMENT_INVOICE".
• Remplacer le contenu d'une facture → type: "invoice" + documentSubtype: "CORRECTED_INVOICE".
• Réduire / annuler une facture → type: "credit-note" avec billingReference.
• Facturer un supplément après coup → type: "debit-note" avec billingReference.
• Vous êtes le client qui émet pour le fournisseur → type: "invoice" + selfBilled: true.
• Auto-comptabiliser la TVA en autoliquidation (IT) → type: "invoice" + le bon code TD dans document.note.
• Émettre une demande d'achat (requête interne) → type: "purchase-request".
• Commander / établir un devis → type: "purchase-order", "sales-order" ou "quote".
• Enregistrer un événement, sans destinataire → type: "event".
• Comptabiliser un frais → pas un type d'envoi : recevez la invoice du fournisseur, ou déclarez-le en e-reporting s'il n'y a pas de facture.

Références

• Envoyer un document — l'endpoint, tous les champs dont type, documentSubtype et selfBilled.
• Parties multiples — parties explicites étiquetées par rôle pour l'autofacturation avec un tiers.
• Exonération de TVA & taux zéro — catégories de TVA et motifs d'exonération pour l'autoliquidation et les opérations exonérées.
• Modèle de données · Document — les trois champs de statut orthogonaux de chaque document.
• Italie · Types de documents (TD01–TD29) — le référentiel complet des TipoDocumento, y compris les autofatture.