Recevoir, intégrer et gérer les factures reçues

Ce guide explique comment :

• recevoir des factures via différents canaux (Peppol, e-mail, b2brouter, uploads) ;
• intégrer les factures reçues dans votre système (JSON, PDF, fichier original) ;
• gérer le cycle de vie des factures (acknowledge, accept/refuse/paid, etc.).

Prérequis

• Une entreprise avec un Taxcode Identifier (TIN) ou un Company Identifier (CIN) valide.
• Un compte enregistré sur l’environnement de test de B2Brouter : Register Here
• Des permissions API (à demander via un ticket de support : Open a Ticket)
• En cas de doute sur le processus d’inscription, veuillez consulter le User Guide.

Si vous devez encore créer le compte ou activer les transports de réception, suivez :

• Getting started (configuration du compte) : https://developer.b2brouter.net/docs/setting_up_guide#/
• Guide Transports : https://developer.b2brouter.net/docs/transports_guide/

Concepts clés (éviter les confusions d’ID)

• ACCOUNT_ID est utilisé uniquement dans les endpoints /accounts/{ACCOUNT_ID}/....
• INVOICE_ID est l’identifiant de facture utilisé dans les endpoints /invoices/{INVOICE_ID}....
• Dans une received invoice, invoice.contact est l’émetteur/fournisseur (et non votre propre compte).

1) Ingérer des factures reçues

1.1 Importer un fichier de facture reçue (XML) (optionnel)

Si vous disposez déjà du fichier de facture reçue (par exemple pour des tests, des migrations ou des backfills), vous pouvez l’importer avec Import an invoice from a file. Utilisez le paramètre de requête issued=false pour l’importer comme ReceivedInvoice.

Il est également possible de générer une facture reçue avec JSON en utilisant l’appel Create an invoice, n’oubliez pas d’indiquer "type": "ReceivedInvoice" lorsque vous le faites.

1.2 Recevoir des factures via des transports

Une fois les transports activés pour le compte, les factures arriveront automatiquement (par exemple via Peppol ou e-mail).

2) Lister les factures reçues

Exemple de requête :

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/invoices?type=ReceivedInvoice' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Exemple de réponse (extrait) :

{
  "invoices": [
    {
      "id": 105337,
      "number": "2",
      "state": "new",
      "total": 107.1,
      "currency": "EUR"
    },
    {
      "id": 105332,
      "number": "1",
      "state": "received",
      "total": 178.5,
      "currency": "EUR"
    }
  ],
  "total_count": 2,
  "offset": 0,
  "limit": 25
}

Les factures reçues peuvent avoir différents statuts : les factures importées apparaissent à l’état new et celles reçues via différents transports apparaissent normalement à l’état received. Elles peuvent aussi avoir l’état invalid en cas de problème de validation.

Pour vérifier tous les états de facture disponibles, utilisez l’endpoint List of available invoice status.

3) Obtenir les détails d’une facture

Pour obtenir la facture au format JSON, utilisez l’endpoint Get an invoice. Ajoutez un Query Param pour inclure les informations de lignes :

Exemple de requête :

curl --request GET \
  --url 'https://api-staging.b2brouter.net/invoices/{INVOICE_ID}?include=lines' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

4) Télécharger le fichier original de la facture

Pour télécharger la facture légale originale reçue :

Exemple de requête :

curl --request GET \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/as/original \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Vous pouvez également utiliser document_type_code comme pdf.invoice pour générer une vue PDF, ou n’importe quel autre document_type_code depuis Get document types pour obtenir la facture dans n’importe quel format de facture électronique.

5) Accuser réception de la facture

Utilisez l’endpoint Mark an invoice as acknowledged pour éviter que la facture ne soit listée lors de la récupération de la liste des factures reçues.

6) Changer l’état de la facture

Changez l’état de la facture pour informer l’émetteur que vous avez accepted, refused ou paid la facture. Vous pouvez également marquer la facture comme annotated pour le suivi interne.

Utilisez l’endpoint Switch invoice state. Vous pouvez ajouter le paramètre de corps reason pour préciser le motif du rejet. Si la facture provient d’un e-mail, ajoutez le paramètre de corps "commit": "with_mail" pour informer l’expéditeur.

Exemple de requête :

curl --request POST \
  --url https://api-staging.b2brouter.net/invoices/{INVOICE_ID}/mark_as \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "state": "refused",
    "reason": "Missing PO number"
  }'

Exemple de réponse :

204 No Content

Pour plus de détails, consultez l’API Reference.