Transaction

Définition de transaction

Une transaction est une action effectuée sur un document, telle que son envoi ou sa réception. Cette action peut inclure la validation, l’enregistrement et le suivi du document afin de garantir que les exigences établies sont respectées et que le document est correctement transféré.

Nous considérons comme document

• Facture (simplifiée, auto-facture, standard)
• Devis
• Commande
• Bon de livraison
• Déclaration fiscale

Transactions facturables

Chacune des actions suivantes est considérée comme une transaction facturable :

• Envoyer un document.
• Recevoir un document.
• Transformer un document pour téléchargement (API et APP).

Exceptions

• Le téléchargement d’une copie PDF d’une facture émise n’est pas considéré comme facturable.
• Les changements d’état ne sont pas considérés comme des documents ; par conséquent, les actions sur les changements d’état ne sont pas comptabilisées comme des transactions.
• L’événement error_sending : erreur d’envoi (statut : Error, Corner C2) n’est pas considéré comme une transaction.

Cas spécifiques

• Tax report activé : lorsqu’une facture est envoyée et que le tax report est activé, le rapport correspondant est automatiquement généré et envoyé. Par conséquent, l’envoi d’une facture génère deux transactions facturables.
• Cas Verifactu : créer et envoyer une facture avec Verifactu compte comme deux transactions facturables, une pour la facture et une pour la déclaration fiscale. Le “ledger” compte autant d’enregistrements qu’il contient. Un ledger avec 10 enregistrements compte comme 10 transactions individuelles.
• Cas SDI : lorsqu’une facture transfrontalière est envoyée, nous facturons l’envoi de la facture à l’administration fiscale. Dans ce cas, la déclaration fiscale correspond à la facture envoyée à l’autorité fiscale.

Endpoints API qui génèrent une transaction facturable

• Envoyer une facture
• Créer une facture émise (avec send_after_import: true)
• Importer une facture depuis un fichier (avec send_after_import: true)
• Obtenir une facture avec un type de document spécifique (sauf au format PDF)
• Générer une déclaration fiscale à partir d’une facture
• Créer une déclaration fiscale
• Importer une déclaration fiscale
• Annuler une déclaration fiscale

Exemples d’autres endpoints API qui, actuellement, ne génèrent pas de transaction facturable

• Créer une facture émise (avec send_after_import: false)
• Importer une facture depuis un fichier (avec send_after_import: false)
• Changer l’état d’une facture
• Validation
• Marquer une facture comme accusée de réception
• Lookup (Directory)

Compteurs de transactions par type de document

Les transactions peuvent être enregistrées en comptant l’un des événements suivants (1 événement = 1 transaction).

Liste des événements

• success_sending : envoi réussi (statut : Sent, Corner C2)
• success_clearing : processus de clearance terminé avec succès (ZATCA)
• error_clearing : erreur pendant le processus de clearance (ZATCA)
• notification_c2_state_downloaded : facture téléchargée. Correspond au corner C2. Lorsque le transport est “Download” et que l’utilisateur clique sur le bouton Issue and Download (statut : Downloaded)

Sortants

Factures émises de différents types (sendable_type: Invoice)

Endpoints API :

• Send invoice
• Import invoice (avec le paramètre send_after_import: true)

Événements :

• success_sending
• error_sending

Événements non liés à l’API :

• notification_c2_state_downloaded

Devis (sendable_type: Quote)

Endpoints API : Les devis ne peuvent pas être envoyés via l’API.

Événements non liés à l’API :

• success_sending
• error_sending

Bons de livraison (sendable_type: DespatchAdvice)

Endpoints API : Les bons de livraison ne peuvent pas être envoyés via l’API.

Événements non liés à l’API :

• success_sending
• error_sending

Commandes (sendable_type: Order)

Endpoints API :

• Mark as processed (cet endpoint ne génère aucune transaction)

Événements non liés à l’API : Lorsqu’une commande est acceptée ou rejetée (UI uniquement), une réponse de commande est envoyée et génère l’un de ces événements :

• success_sending
• error_sending

Déclarations fiscales (sendable_type: TaxReport)

Endpoints API :

• Send invoice (si la facture requiert la déclaration fiscale)
• Create tax report
• Import tax report
• Modify tax report
• Annulate tax report
• Annulate tax report (legacy)

Événements :

• success_sending
• error_sending
• success_clearing
• error_clearing

Remarques : Lorsque le tax_authority est Verifactu ou TicketBAI (Bizkaia), en plus de l’envoi du TaxReport, un Ledger est également envoyé.

Ledger

Endpoints API : les mêmes que pour TaxReport.

Événements :

• success_sending
• error_sending

Entrants

Factures reçues de différents types (sendable_type: Invoice)

Une transaction est générée lorsqu’une “received invoice” est reçue. Lorsqu’une facture reçue est créée manuellement ou importée via la plateforme, elle n’est pas comptée comme transaction.

Endpoints API :

• Import invoice (avec issued=false, correspondant à from_net: 'uploaded')

Commandes (sendable_type: Order)

Endpoints API : Les commandes ne peuvent pas être générées ni envoyées via l’API.

Remarques : Une transaction est générée lorsqu’une commande est reçue. Lorsqu’elle est importée via la plateforme, elle n’est pas comptée comme transaction.

View_as

Chaque fois que l’API view_as est appelée avec un paramètre document_type différent de "original" ou "legal", une transaction est générée. Une nouvelle transaction est créée chaque fois qu’un nouveau document est généré à partir de notre objet en base de données.

Types de document non facturables

original — Retourne le document exactement tel qu’il a été initialement soumis ou importé, servi depuis le stockage. Aucune régénération n’a lieu.

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

legal — Retourne le document légal archivé (par exemple, la version signée et horodatée) tel qu’il est stocké. Aucune régénération n’a lieu.

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

pdf.invoice et pdf.invoice.signed — Bien que le PDF soit généré à la demande, le téléchargement d’une copie PDF d’une facture émise n’est pas considéré comme facturable.

Types de document facturables

Toute autre valeur de document_type régénère le document dans le format demandé et compte comme une transaction facturable.

curl --request GET \
  --url https://api.b2brouter.net/invoices/{id}/as/xml.ubl.invoice.bis3 \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Remarque : si vous avez seulement besoin de récupérer le document que vous avez déjà envoyé ou reçu, utilisez plutôt /as/legal ou /as/original.

Comment suivre votre consommation de transactions

Si vous êtes Partner ou Reseller, vous pouvez suivre la consommation de transactions de chaque groupe d’intégration directement depuis le portail B2Brouter.

Lorsque vous provisionnez un groupe d’intégration, que ce soit parce que vous gérez un seul groupe d’entreprises ou parce que vous opérez en tant que eDocSync, la manière la plus efficace de suivre l’usage total et par compte est via l’endpoint API suivant : GET /accounts

Exemple de requête

curl --request GET \
  --url 'https://api-staging.b2brouter.net/accounts?offset=0&limit=25' \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'accept: application/json'

Exemple de réponse

{
  "accounts": [
    {
      "id": 12345,
      "name": "Ejemplo S.L.",
      ...
      "transactions_count": 24,
      "transactions_count_previous_period": 41,
      "transactions_limit": 100
    },
    {
      "id": 23456,
      "name": "Muster GmbH",
      ...
      "transactions_count": 32,
      "transactions_count_previous_period": 9,
      "transactions_limit": 100
    },
    {
      "id": 34567,
      "name": "Esempio S.r.l.",
      ...
      "transactions_count": 124,
      "transactions_count_previous_period": 326,
      "transactions_limit": 100
    }
    ...
  ]
}

Chaque compte inclut :

• transactions_count → transactions consommées durant la période de facturation en cours.
• transactions_count_previous_period → transactions consommées durant la période de facturation précédente.
• transactions_limit → nombre maximal de transactions incluses dans l’abonnement.

En contrôlant ces données, vous pouvez gérer automatiquement la consommation de chaque compte ainsi que le total global. Cela vous permet d’automatiser les paiements en fonction du volume de transactions de vos clients finaux, ou de surveiller votre consommation par rapport au quota convenu et d’augmenter votre limite de transactions avant de la dépasser.