Aller au contenu
Passerelle e-invoicing

La recherche est disponible uniquement en mode production. Essayez de construire puis de prévisualiser votre site pour tester la recherche localement.

Déposer une facture

POST
/v1/invoices
curl --request POST \
  --url http://localhost:4000/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "id": "in_0001", "number": "F-2026-0001", "status": "open", "customer_id": "cus_042", "created_at": "2026-10-01T08:00:00Z", "finalized_at": "2026-10-01T08:00:05Z", "due_date": "2026-10-31", "period_start": "2026-10-01", "period_end": "2026-10-31", "currency": "EUR", "subtotal": 10000, "total_excl_tax": 10000, "tax_total": 2000, "total": 12000, "amount_paid": 0, "amount_due": 12000, "lines": [ { "id": "li_1", "description": "Abonnement Pro - octobre 2026", "type": "subscription", "quantity": 1, "unit_amount": 10000, "amount": 10000, "taxes": [ { "name": "TVA", "percentage": 20, "inclusive": false, "amount": 2000 } ] } ], "customer_snapshot": { "id": "cus_042", "type": "company", "name": "Exemple SAS", "email": "compta@exemple.fr", "billing_address": { "line1": "1 rue de la Paix", "postal_code": "75002", "city": "Paris", "country": "FR" }, "tax_ids": [ { "type": "siren", "value": "552100554" } ] } }'

Accepte une facture au format SaaS (non conforme par défaut). La réponse 202 signifie « reçue », pas « acceptée par la PA » : suivre le statut via GET /v1/invoices/{id} ou les webhooks.

Le même Idempotency-Key renvoie la soumission d’origine sans retraitement.

Authorizations

Section intitulée « Authorizations »

Parameters

Section intitulée « Parameters »

Header Parameters

Section intitulée « Header Parameters »
Idempotency-Key
required
string
>= 1 characters <= 255 characters

Clé d’idempotence choisie par le SaaS (unique par dépôt).

Request Bodyrequired

Section intitulée « Request Bodyrequired »
Media typeapplication/json

Facture au format SaaS (référentiel 01 §6), non conforme par défaut.

object
id
required

Identifiant côté SaaS.

string
number
required
string
status
required
string
Allowed values: draft open paid void uncollectible
customer_id
required
string
subscription_id
string
created_at
string format: date-time
finalized_at
string format: date-time
paid_at
string format: date-time
voided_at
string format: date-time
due_date
string format: date
period_start
string format: date
period_end
string format: date
currency
required

ISO 4217. Devises prises en charge : EUR, USD, GBP, CHF, CAD, AUD, JPY, KRW, XOF, XAF, BHD, KWD, TND. Toute autre devise est refusée en 422.

string
/^[A-Z]{3}$/
subtotal

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
discount_total

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
total_excl_tax
required

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
tax_total
required

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
total
required

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
amount_paid

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
amount_due

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
lines
required
Array<object>
object
id
required
string
description
required
string
product_id
string
price_id
string
type
string
Allowed values: subscription one_off usage setup_fee proration
quantity
required
number
unit_amount
required

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
amount
required

Montant HT de la ligne.

integer format: int64
taxes
Array<object>
object
name
string
percentage
required

Taux en %, 0 à 100.

number
inclusive
required

Vrai si le prix est TTC.

boolean
taxable_amount

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
amount
required

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
jurisdiction
string
period_start
string format: date
period_end
string format: date
taxes
Array<object>
object
name
string
percentage
required

Taux en %, 0 à 100.

number
inclusive
required

Vrai si le prix est TTC.

boolean
taxable_amount

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
amount
required

Montant en plus petite unité monétaire (centimes pour l’EUR).

integer format: int64
jurisdiction
string
customer_snapshot
object
id
required
string
type
required
string
Allowed values: company individual
name
required
string
email
string format: email
billing_address
object
line1
required
string
line2
string
postal_code
required
string
city
required
string
state
string
country
required

ISO 3166-1 alpha-2.

string
/^[A-Z]{2}$/
shipping_address
object
line1
required
string
line2
string
postal_code
required
string
city
required
string
state
string
country
required

ISO 3166-1 alpha-2.

string
/^[A-Z]{2}$/
tax_ids
Array<object>
object
type
required

Ex. eu_vat, siren.

string
value
required
string
verification_status
string
tax_exempt
string
Allowed values: none exempt reverse
currency

ISO 4217. Devises prises en charge : EUR, USD, GBP, CHF, CAD, AUD, JPY, KRW, XOF, XAF, BHD, KWD, TND. Toute autre devise est refusée en 422.

string
/^[A-Z]{3}$/
locale
string
metadata
object
key
additional properties
string
created_at
string format: date-time
purchase_order_ref
string
payment_terms
string
footer
string
notes
string
metadata
object
key
additional properties
string

Examples

Exampleabonnement

Facture d'abonnement mensuel

{
  "id": "in_0001",
  "number": "F-2026-0001",
  "status": "open",
  "customer_id": "cus_042",
  "created_at": "2026-10-01T08:00:00Z",
  "finalized_at": "2026-10-01T08:00:05Z",
  "due_date": "2026-10-31",
  "period_start": "2026-10-01",
  "period_end": "2026-10-31",
  "currency": "EUR",
  "subtotal": 10000,
  "total_excl_tax": 10000,
  "tax_total": 2000,
  "total": 12000,
  "amount_paid": 0,
  "amount_due": 12000,
  "lines": [
    {
      "id": "li_1",
      "description": "Abonnement Pro - octobre 2026",
      "type": "subscription",
      "quantity": 1,
      "unit_amount": 10000,
      "amount": 10000,
      "taxes": [
        {
          "name": "TVA",
          "percentage": 20,
          "inclusive": false,
          "amount": 2000
        }
      ]
    }
  ],
  "customer_snapshot": {
    "id": "cus_042",
    "type": "company",
    "name": "Exemple SAS",
    "email": "compta@exemple.fr",
    "billing_address": {
      "line1": "1 rue de la Paix",
      "postal_code": "75002",
      "city": "Paris",
      "country": "FR"
    },
    "tax_ids": [
      {
        "type": "siren",
        "value": "552100554"
      }
    ]
  }
}

Responses

Section intitulée « Responses »

202

Section intitulée « 202 »

Facture reçue, traitement asynchrone.

Media typeapplication/json
object
submission_id
required

Identifiant attribué par la passerelle.

string
saas_id
required

Identifiant côté SaaS (id fourni au dépôt).

string
number
string
processing_state
required

État de traitement dans la passerelle, indépendant des statuts PA 200 à 214. received → validated → sent ; rejected si la validation ou la PA refuse définitivement. Seul received est produit aujourd’hui.

string
Allowed values: received validated sent rejected
lifecycle_status

Dernier statut PA connu ; absent tant que la PA n’a rien renvoyé.

object
code
required

Statut du cycle de vie (référentiel 02 §17) : 200 Déposée, 201 Émise, 202 Reçue, 203 Mise à disposition, 204 Prise en charge, 205 Approuvée, 206 Approuvée partiellement, 207 En litige, 208 Suspendue, 209 Complétée, 210 Refusée, 211 Paiement transmis, 212 Encaissée, 213 Rejetée, 214 Visée (à vérifier : absent du référentiel 02).

integer
>= 200 <= 214
label
string
occurred_at
required
string format: date-time
reason

Motif, notamment pour 210 et 213.

string
origin_submission_id

Avoirs uniquement. Dépôt de la facture d’origine (piste d’audit).

string
created_at
required
string format: date-time

Example 

{
  "processing_state": "received"
}

Headers

Section intitulée « Headers »
Location
string

URL de la ressource créée.

400

Section intitulée « 400 »

Requête mal formée (JSON invalide, champ requis absent).

Media typeapplication/problem+json

Erreur au format RFC 9457.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
submission_id

Dépôt existant, pour un doublon (409).

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "submission_id": "example"
}

401

Section intitulée « 401 »

Jeton absent ou invalide.

Media typeapplication/problem+json

Erreur au format RFC 9457.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
submission_id

Dépôt existant, pour un doublon (409).

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "submission_id": "example"
}

409

Section intitulée « 409 »

Conflit, de deux natures (champ type) :

  • urn:einvoicing:problem:idempotency-conflict : même Idempotency-Key avec un corps différent.
  • urn:einvoicing:problem:duplicate-submission : ce numéro ou cet identifiant SaaS a déjà été déposé pour ce type de document (facture ou avoir), même sous une autre clé. submission_id désigne le dépôt existant. Une facture rejetée ne se renvoie pas : il faut une nouvelle facture ou un avoir, avec un nouveau numéro.
Media typeapplication/problem+json

Erreur au format RFC 9457.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
submission_id

Dépôt existant, pour un doublon (409).

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "submission_id": "example"
}

413

Section intitulée « 413 »

Corps supérieur à 1 Mio.

Media typeapplication/problem+json

Erreur au format RFC 9457.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
submission_id

Dépôt existant, pour un doublon (409).

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "submission_id": "example"
}

422

Section intitulée « 422 »

Valeur impossible à convertir (rejet définitif) : devise non prise en charge, SIREN, SIRET ou n° de TVA malformé, pays invalide, taux hors de 0 à 100, plusieurs TVA sur une ligne, devise de l’avoir absente, facture d’origine d’un avoir inconnue (/invoice_id). Chaque erreur porte le chemin JSON du champ. Les règles EN 16931 complètes (BR-CO-*) ne sont pas encore appliquées. Corriger puis redéposer ; la même Idempotency-Key reste utilisable, un rejet ne la consomme pas.

Media typeapplication/problem+json
object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
submission_id

Dépôt existant, pour un doublon (409).

string
errors
required
Array<object>
object
path
required

Pointeur JSON vers le champ fautif.

string
rule

Règle enfreinte, ex. BR-CO-10.

string
message
required
string

Example 

{
  "errors": [
    {
      "path": "/lines/0/taxes/0/percentage"
    }
  ]
}

500

Section intitulée « 500 »

Erreur interne (message générique, détail dans les logs du serveur).

Media typeapplication/problem+json

Erreur au format RFC 9457.

object
type
required
string format: uri-reference
title
required
string
status
required
integer
detail
string
submission_id

Dépôt existant, pour un doublon (409).

string

Example generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "submission_id": "example"
}