Guide de migration v2026-03-02 → v2026-04-20

Ce guide vous aide à passer de X-B2B-API-Version: 2026-03-02 à X-B2B-API-Version: 2026-04-20, en se concentrant sur ce que vous devez changer, pas seulement sur ce qui a changé.

Changelog Pour la liste complète des ajouts et corrections, consultez le changelog de v2026-04-20.

En bref

What changed	Do you need to act?
Credit notes and amendments use a new invoice_references structure	Yes — affects all integrations that create or read corrective invoices
payment_method_info removed from invoice responses	Yes — remove any code that reads this field
clasification_code_scheme typo fixed in invoice line responses	Yes — update your field name if you read it
New validation when creating child contacts (offices)	Yes — only if you set tin_value on contacts with a parent_id
New validation when creating invoices with an inline contact	Yes — ensure tin_value or cin_value is always included
New fields in invoice, account, and Peppol transport responses	Only if your code fails on unexpected JSON fields
Peppol transport: pending_peppol_directory_publish replaced	Only if you read this field
TIN verification endpoint (new)	No — opt-in feature
New account fields (routing_codes, auto_remittance, etc.)	No — opt-in
KSeF additions	No — only relevant for Polish KSeF integrations

---

Changements nécessitant une action

1. Notes de crédit et amendements : remplacer les champs plats par invoice_references

Il s’agit du changement le plus important. Les champs individuels d’amendement sur les factures ont été remplacés par un tableau unique invoice_references. Si votre intégration crée ou lit des factures correctives (notes de crédit, amendements), vous devez mettre à jour à la fois vos requêtes et votre traitement des réponses.

Les champs suivants ne sont plus envoyés ni renvoyés :

Removed field	Replaced by invoice_references[].
amended_number	number
amended_date	date
amended_invoicing_period_start	invoicing_period_start (send only, not returned)
amended_invoicing_period_end	invoicing_period_end (send only, not returned)
amend_reason	reason
amend_code_tax	tax_correction_code
correction_method	correction_method

Chaque entrée de invoice_references requiert un reference_type. Utilisez "amend" pour les factures correctives qui référencent une facture d’origine.

Mettre à jour votre requête (création / mise à jour) :

Avant (v2026-03-02)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "amended_number": "INV-2026-042",
    "amended_date": "2026-02-10",
    "amend_reason": "Price correction"
  }
}

Après (v2026-04-20)

{
  "invoice": {
    "number": "CN-2026-001",
    "is_credit_note": true,
    "contact_id": 123,
    "invoice_references": [
      {
        "reference_type": "amend",
        "number": "INV-2026-042",
        "date": "2026-02-10",
        "reason": "Price correction"
      }
    ]
  }
}

Mettre à jour le traitement des réponses (lecture) :

Avant (v2026-03-02)

const originalNumber = invoice.amended_number;
const reason = invoice.amend_reason;

Après (v2026-04-20)

const ref = invoice.invoice_references.find(
  (r) => r.reference_type === "amend",
);
const originalNumber = ref?.number;
const reason = ref?.reason;

Points de terminaison concernés : GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

2. payment_method_info supprimé des réponses de facture

Le champ payment_method_info n’est plus renvoyé. Il contenait un résumé lisible et formaté en HTML du paiement. Si vous l’utilisiez, remplacez-le par les champs structurés déjà présents dans la réponse : payment_method, contact_iban, contact_bic, etc.

Points de terminaison concernés : GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

3. Correction d’une faute de frappe dans un champ de ligne de facture : clasification_code_scheme → classification_code_scheme

Le champ était mal orthographié dans toutes les versions précédentes. La réponse renvoie désormais l’orthographe correcte. Si votre code lit clasification_code_scheme (un seul « s ») dans les réponses de lignes de facture, mettez-le à jour.

Remarque : l’envoi de l’orthographe correcte dans les requêtes était déjà accepté dans toutes les versions. Seule la clé de réponse change.

Avant (v2026-03-02)

{ "clasification_code_scheme": "..." }

Après (v2026-04-20)

{ "classification_code_scheme": "..." }

Points de terminaison concernés : GET /invoices/{id}, POST /accounts/{account}/invoices, PATCH /invoices/{id}

---

4. Contacts enfants (bureaux) : tin_value est désormais validé par rapport au parent

Lors de la création ou de la mise à jour d’un contact appartenant à une société mère (à l’aide de parent_id), l’API rejette maintenant la requête si la valeur tin_value fournie ne correspond pas à celle du contact parent. Auparavant, une valeur différente était ignorée silencieusement.

L’approche recommandée consiste à ne pas renseigner du tout tin_value lors de la création de bureaux : il est automatiquement hérité du parent.

// Recommandé (v2026-04-20) — créer une succursale
{
  "contact": {
    "name": "Branch Office Madrid",
    "parent_id": 456
  }
}

Points de terminaison concernés : POST /accounts/{account}/contacts, PATCH /contacts/{id}

---

5. Créer une facture avec un contact inline requiert désormais un identifiant

Si vous créez une facture et transmettez les données du contact inline (avec un objet contact au lieu d’un contact_id), le contact doit désormais inclure au moins l’un des deux champs tin_value ou cin_value. Les requêtes ne contenant ni l’un ni l’autre seront rejetées avec 422 Unprocessable Entity.

Cela ne s’applique pas aux factures simplifiées (IssuedSimplifiedInvoice), qui ne nécessitent pas un contact identifié.

// v2026-04-20 — tin_value ou cin_value est requis
{
  "invoice": {
    "contact": {
      "name": "Acme Corp",
      "tin_value": "B12345678",
      "tin_scheme": "9915"
    }
  }
}

Points de terminaison concernés : POST /accounts/{account}/invoices

---

Nouveaux champs dans les réponses existantes

Les champs suivants ont été ajoutés aux réponses existantes. Ils sont rétrocompatibles : votre intégration continuera à fonctionner sans modification. En revanche, si votre code échoue lorsqu’il rencontre des champs JSON inattendus, mettez à jour vos modèles de réponse pour les autoriser.

Réponses de facture (GET /invoices/{id}, POST, PATCH) :

• invoice_references — tableau de références d’amendement / acompte (voir section 1 ci-dessus)
• exchange_rate — taux de change appliqué lorsque la devise de la facture diffère de la devise locale de l’administration fiscale
• exchange_date — date du taux de change
• order_date — date de commande (complète le champ ponumber existant)
• contact.cin_value, contact.cin_scheme — identifiant d’entreprise du contact de la facture

Réponses de compte (GET /accounts/{account}, GET /accounts) :

• routing_codes — objet contenant jusqu’à 5 identifiants d’entreprise supplémentaires (cin1_value/cin1_scheme à cin5_value/cin5_scheme)
• auto_remittance — booléen
• skip_line_taxable_base_rounding — booléen

Réponse de transport Peppol (GET /accounts/{account}/transports) :

• sml_status — statut d’enregistrement SML : "not_published", "processing" ou "published"
• peppol_directory_status — statut de publication dans le Peppol Directory (remplace l’ancien booléen pending_peppol_directory_publish)
• reception_document_types — liste des types de documents que ce participant peut recevoir via Peppol
• standard_documents et pending_peppol_directory_publish ne sont plus renvoyés

---

Nouvelles fonctionnalités disponibles dans cette version

Vérification de TIN — vérifiez qu’un nom d’entreprise et un numéro fiscal sont bien enregistrés auprès de l’administration fiscale avant d’envoyer une facture. Actuellement disponible pour l’Espagne (AEAT).

• POST /tin_verifications?country=es — soumet une liste de jusqu’à 20 000 couples TIN+nom pour vérification ; renvoie 202 Accepted pendant le traitement en arrière-plan
• GET /tin_verifications/{id} — récupère les résultats une fois le traitement terminé
• Abonnez-vous à l’événement webhook tin_verification.finished pour être notifié automatiquement

Nouveaux champs de configuration de compte :

• routing_codes sur les comptes — stocke jusqu’à 5 identifiants d’entreprise supplémentaires, utiles pour le routage Peppol
• auto_remittance — génère automatiquement des références structurées OGM sur les factures belges
• skip_line_taxable_base_rounding — utile pour les factures comportant de nombreuses lignes où de petites différences d’arrondi s’accumulent ; requiert apply_taxes_per_line: true

Ajouts KSeF (facturation électronique polonaise) — si votre intégration gère des factures polonaises, cette version ajoute la prise en charge des workflows d’acompte (ZAL, ROZ, KOR_ZAL, KOR_ROZ), des scénarios de facturation aux administrations locales et aux groupes TVA, ainsi que plusieurs nouveaux champs de déclaration fiscale. Consultez le changelog pour la liste complète.

---

Checklist de migration

Utilisez cette checklist avant de passer à v2026-04-20 en production.

Factures correctives (notes de crédit, amendements) :

• Remplacer les champs plats d’amendement (amended_number, amended_date, amend_reason, etc.) par invoice_references dans toutes les requêtes de création / mise à jour de facture
• Inclure reference_type: "amend" pour chaque entrée
• Mettre à jour le traitement des réponses pour lire invoice_references au lieu des champs plats
• Test : créer une note de crédit, la relire et confirmer que le tableau invoice_references est présent et correct

Champs de réponse des factures :

• Supprimer tout code qui lit payment_method_info
• Mettre à jour clasification_code_scheme → classification_code_scheme partout où vous lisez les réponses des lignes de facture
• Vérifier que votre traitement des réponses accepte les nouveaux champs : exchange_rate, exchange_date, order_date, contact.cin_value, contact.cin_scheme

Contacts :

• Si vous créez des contacts avec parent_id, supprimer tin_value ou l’aligner sur la valeur du contact parent
• Si vous créez des factures avec un objet contact inline, vérifier que tin_value ou cin_value est toujours inclus

Transport Peppol :

• Mettre à jour le traitement des réponses du transport : remplacer pending_peppol_directory_publish par peppol_directory_status, et supprimer les lectures de standard_documents
• Vérifier que votre modèle de réponse accepte sml_status, peppol_directory_status et reception_document_types

Comptes :

• Vérifier que votre traitement des réponses de compte accepte les nouveaux champs routing_codes, auto_remittance et skip_line_taxable_base_rounding

Tester votre intégration

Passez d’abord au nouvel en-tête de version dans votre environnement sandbox ou staging :

X-B2B-API-Version: 2026-04-20

Vous pouvez définir cet en-tête requête par requête, ce qui vous permet de tester sur sandbox (ou staging) sans toucher à votre configuration de production. Une fois la checklist ci-dessus validée, mettez à jour la version dans les paramètres de votre clé API de production ou dans les en-têtes de requête.