Avoirs

L'objet credit_note représente une facture d'avoir — un document opposable permettant de réduire le montant d'une facture émise précédemment (geste commercial, retour de marchandise, erreur de facturation). Conformément à la règle EN16931 BR-55, un avoir doit obligatoirement référencer le numéro de la facture d'origine.

Endpoints

Créer un avoir

$ curl -X POST https://facturino.com/api/v1/credit-notes \
  -H "Authorization: Bearer fac_test_..." \
  -H "Idempotency-Key: credit-note-create-rma-1842" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_8f2k4m9n",
    "relatedInvoiceId": "inv_a1b2c3d4e5f6",
    "creditNoteType": "commercial",
    "reasonCode": "other",
    "reason": "Geste commercial — remise exceptionnelle",
    "items": [
      {
        "description": "Remise commerciale",
        "quantity": "1", "unit": "unit",
        "unitPrice": 20000, "vatRate": 2000, "vatCode": "S"
      }
    ],
    "dates": { "issued": "2026-04-23" }
  }'

Les champs customerId, relatedInvoiceId, creditNoteType et reasonCode sont obligatoires. relatedInvoiceId alimente la balise CII BillingReference (BT-25) requise par CIUS-FR — la facture liée doit être en statut finalized ou ultérieur et appartenir à la même entreprise.

Type d'avoir (creditNoteType)

Motif (reasonCode)

Le code de motif est un enum borné — toute autre valeur entraîne une validation_error. Le texte libre va dans le champ optionnel reason (max 500 caractères).

Avoir partiel

Pour un retour partiel ou une remise sur une ou plusieurs lignes, utilisez creditNoteType: "partial" et listez dans items uniquement les lignes effectivement créditées :

# Avoir de retour partiel — référence la ligne d'origine
{
  "customerId": "cus_8f2k4m9n",
  "relatedInvoiceId": "inv_a1b2c3d4e5f6",
  "creditNoteType": "partial",
  "reasonCode": "defective_goods",
  "reason": "Retour partiel — produits défectueux",
  "items": [
    {
      "description": "Retour 2 unités sur 5 — réf SKU-734",
      "quantity": "2", "unit": "unit",
      "unitPrice": 12500, "vatRate": 2000, "vatCode": "S"
    }
  ],
  "dates": { "issued": "2026-04-23" }
}

Le PDF de l'avoir affiche systématiquement le numéro et la date de la facture d'origine en en-tête, conformément à la pratique comptable française (mention « Avoir sur facture {number} du {date} »).

Numérotation

Les avoirs ont leur propre série de numérotation, paramétrable depuis Paramètres → Facturation → Format des numéros d'avoir. Le format par défaut est AV-{NUM:5} (ex. AV-00001), incrémenté atomiquement à la finalisation.

Par défaut, les avoirs disposent de leur propre série, distincte de celle des factures. Si vous préférez utiliser la même série que les factures (recommandé par certains experts-comptables), activez la « Numérotation unifiée » via creditNoteSettings.numberingMode: "unified" — les avoirs tireront alors le prochain numéro de la série facture, affiché avec le préfixe AV-.

Cycle de vie

Identique aux factures pour les statuts post-finalisation :

Annulation d’une facture à identité masquée

Si la facture d’origine porte un marqueur de non-diffusion dans l’identité de l’acheteur, corrigez d’abord le nom et l’adresse de sa fiche client d’après ses documents. Créez ensuite un avoir creditNoteType: total couvrant toutes les lignes. Cette exception reprend le nom et l’adresse corrigés du même client ; les identifiants légaux présents sur l’original, le pays, la nature fiscale, les montants et la décision fiscale sont conservés. Une identité historique valide reste utilisée telle quelle pour les autres avoirs.

La finalisation relit la fiche client dans la transaction, y compris pour un ancien brouillon d’avoir, et vérifie l’annulation totale. Elle conserve relatedInvoiceId et relatedInvoiceNumber et ajoute à l’historique de l’avoir une mention de l’identité corrigée et du marqueur présent sur l’original. Une identité encore masquée ou incomplète bloque la finalisation. Les plafonds d’avoirs et les exigences de décision fiscale continuent de s’appliquer.

Ce chemin est disponible pour une facture finalisée puis rejetée avant dépôt. Il ne réécrit pas sa facture ni ses fichiers, ne la renvoie pas et ne déclenche aucun remboursement. Une facture de remplacement, si nécessaire, est une nouvelle émission après correction de la fiche client.

Montants négatifs

Les avoirs sont saisis avec des montants positifs dans l'API. Le générateur XML CII les identifie comme avoirs par le type 381. Côté comptable, le total apparaîtra en négatif sur le grand livre des ventes.

E-reporting d’un avoir unitaire

Un avoir suit les obligations fiscales figées de l’opération corrigée. Lorsqu’il relève du flux 10.1 (B2B international), ses lignes portent documentType: "381", originalInvoiceNumber et originalInvoiceDate : le numéro et la date de la facture corrigée. La référence est émise dans ReferencedDocument (TG-11) du FRR ou dans les champs de référence de Seqino. G1.32 exige la référence et sa date pour ce flux.

Les montants de l’avoir sont déduits des totaux de la déclaration. Le document unitaire transmis porte le type 381 avec les montants de l’avoir ; il ne crée pas une nouvelle vente. Les agrégats B2C restent corrigés par des montants signés dans le rapport de la journée. La catégorie de TVA et le VATEX viennent de la décision figée, sans être déduits du pays.

L’identité de l’acheteur, la référence d’origine et le numéro de TVA du déclarant (G2.33) sont contrôlés avant l’appel à la plateforme. Ces contrôles portent sur le lot entier.

Conformité Factur-X / CIUS-FR

• BT-3 InvoiceTypeCode : 381 (commercial credit note) systématique
• BT-25 BillingReference : numéro de la facture d'origine (obligatoire — BR-55)
• BT-26 BillingReference.IssueDate : date d'émission de la facture d'origine
• BT-20 PaymentTerms : mention « Avoir — pas de paiement attendu » si la valeur nette est négative
• Schematron : validation BR-55 + règles BR-FR appliquées avant finalize

Étapes suivantes

• Factures — la facture d'origine doit exister avant l'avoir
• Webhooks — événements credit_note.*
• Référence interactive

Numéro de la facture corrigée

relatedInvoiceNumber est une chaîne en lecture seule, figée à la création depuis la facture désignée par relatedInvoiceId. Elle est aussi portée par les événements d’avoir. Le champ peut être absent ou null sur un avoir ancien ; relisez alors GET /v1/invoices/:id avec relatedInvoiceId. Ce numéro ne remplace pas l’identifiant de relation.