Facturino / Documentation / Avoirs

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

MéthodeCheminDescription
POST/v1/credit-notesCréer un brouillon
GET/v1/credit-notesLister les avoirs
GET/v1/credit-notes/:idRécupérer un avoir
PATCH/v1/credit-notes/:idModifier (drafts uniquement)
DELETE/v1/credit-notes/:idSupprimer un brouillon
POST/v1/credit-notes/:id/finalizeFinaliser — attribue un numéro AV-…
POST/v1/credit-notes/:id/sendDéposer via PA (mode live)
POST/v1/credit-notes/:id/emailEnvoyer par email avec PDF
GET/v1/credit-notes/:id/pdfPDF lisible
GET/v1/credit-notes/:id/facturxFactur-X (PDF/A-3 + XML CII) — génération asynchrone (202 + job)
GET/v1/credit-notes/:id/xmlXML CII brut (InvoiceTypeCode 381) — finalized requis

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)

ValeurDescription
totalAnnulation intégrale de la facture d'origine.
partialAnnulation partielle — remboursement d'une ou plusieurs lignes.
commercialGeste commercial / remise post-facturation.
financialAjustement financier (escompte, agios, écart d'arrondi).

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).

CodeDescription
defective_goodsProduits défectueux / retour de marchandise.
duplicateFacture émise en doublon par erreur.
qualityQualité de service ou de produit insuffisante.
otherAutre motif — détailler dans le champ reason.

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 :

StatutDescription
draftBrouillon éditable
finalizedNuméro attribué, immuable
sendingDépôt PA en cours (mode live)
credit_depositedDéposé sur la PA
credit_transmittedTransmis à la DGFiP
credit_approvedApprouvé par l'acheteur
credit_refusedRefusé par l'acheteur

Effet sur la facture d'origine. L'émission d'un avoir n'altère jamais la facture liée — c'est un document indépendant et opposable. Pour suivre l'encours net (facture moins avoirs), utilisez l'endpoint GET /v1/invoices/:id?expand=credit_notes qui renvoie expanded.credit_notes[] (la liste des avoirs liés) et expanded.net_balance (le solde net).

Montants négatifs

Les avoirs sont saisis avec des montants positifs dans l'API — le signe est appliqué automatiquement par le générateur XML CII (InvoiceTypeCode = 381). Côté comptable, le total apparaîtra en négatif sur le grand livre des ventes.

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