Déposer un avoir

POST

/v1/credit-notes

const url = 'http://localhost:4000/v1/credit-notes';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"id":"cn_0001","number":"AV-2026-0001","invoice_id":"in_0001","reason":"Erreur de facturation","status":"issued","currency":"EUR","created_at":"2026-10-05T09:30:00Z","total_excl_tax":5000,"tax_total":1000,"total":6000,"lines":[{"id":"li_1","description":"Remise commerciale","quantity":1,"unit_amount":5000,"amount":5000,"taxes":[{"name":"TVA","percentage":20,"inclusive":false,"amount":1000}]}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:4000/v1/credit-notes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: example' \
  --data '{ "id": "cn_0001", "number": "AV-2026-0001", "invoice_id": "in_0001", "reason": "Erreur de facturation", "status": "issued", "currency": "EUR", "created_at": "2026-10-05T09:30:00Z", "total_excl_tax": 5000, "tax_total": 1000, "total": 6000, "lines": [ { "id": "li_1", "description": "Remise commerciale", "quantity": 1, "unit_amount": 5000, "amount": 5000, "taxes": [ { "name": "TVA", "percentage": 20, "inclusive": false, "amount": 1000 } ] } ] }'

L’avoir référence la facture d’origine (invoice_id, son identifiant côté SaaS), qui doit déjà avoir été déposée auprès de la passerelle : sinon 422 sur /invoice_id. Le lien est conservé pour l’audit (origin_submission_id) et fournit le numéro (BT-25) et la date (BT-26) de la facture précédente. Une facture rejetée par la PA ne se renvoie pas : une nouvelle facture ou un avoir est requis.

Authorizations

bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 255 characters

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

Request Body^required

application/json

Avoir au format SaaS (référentiel 01 §9).

object

required

string

number

required

string

invoice_id

required

Facture d’origine (id côté SaaS). Doit avoir été déposée avant l’avoir.

string

reason

required

string

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}$/

lines

required

Array<object>

object

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

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

refund_amount

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

integer format: int64

credit_amount

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

integer format: int64

status

required

string

Allowed values: issued void

created_at

string format: date-time

Examples

remise

Avoir partiel sur une facture

{
  "id": "cn_0001",
  "number": "AV-2026-0001",
  "invoice_id": "in_0001",
  "reason": "Erreur de facturation",
  "status": "issued",
  "currency": "EUR",
  "created_at": "2026-10-05T09:30:00Z",
  "total_excl_tax": 5000,
  "tax_total": 1000,
  "total": 6000,
  "lines": [
    {
      "id": "li_1",
      "description": "Remise commerciale",
      "quantity": 1,
      "unit_amount": 5000,
      "amount": 5000,
      "taxes": [
        {
          "name": "TVA",
          "percentage": 20,
          "inclusive": false,
          "amount": 1000
        }
      ]
    }
  ]
}

Responses

202

Avoir reçu, traitement asynchrone.

application/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

Location

string

URL de la ressource créée.

400

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

application/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

Jeton absent ou invalide.

application/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

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.

application/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

Corps supérieur à 1 Mio.

application/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

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.

application/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

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

application/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"
}

Déposer un avoir

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Examples

Responses

202

Example

Headers

400

Example generated

401

Example generated

409

Example generated

413

Example generated

422

Example

500

Example generated

Request Body^required

Example ^generated

Example ^generated

Example ^generated

Example ^generated

Example ^generated