KSeF

Le KSeF (Krajowy System e-Faktur - système national polonais de facturation électronique) est le système obligatoire de facturation électronique en Pologne, exploité par le ministère polonais des Finances. KSeF garantit l’intégrité et l’authenticité des factures grâce à la soumission en format XML structuré et à la certification numérique.

Cette réglementation impose aux entreprises opérant en Pologne d’adopter des systèmes capables de générer, valider et transmettre des factures de manière sécurisée à la plateforme KSeF. L’API REST de B2Brouter fournit une solution technique permettant à votre entreprise d’être conforme au KSeF, en confiant la complexité à B2Brouter et en vous laissant vous concentrer sur votre logique métier.

Qu’est-ce que le KSeF ?

Le KSeF est la plateforme centralisée de facturation électronique de la Pologne, devenue obligatoire pour les assujettis à la TVA. Il garantit que toutes les factures sont :

validées par rapport aux schémas XML officiels (structure FA) ;
certifiées numériquement à l’aide de certificats qualifiés ;
conservées de manière sécurisée par l’administration fiscale polonaise ;
vérifiables au moyen d’un accusé de réception officiel (UPO - Urzędowe Poświadczenie Odbioru).

En pratique, le KSeF impose :

de créer un fichier XML de facture structurée conforme à la variante de schéma FA 3 - FA(3) ;
de s’authentifier sur la plateforme KSeF avec un certificat électronique qualifié lié à votre NIP polonais ;
de soumettre la facture au KSeF pour validation et enregistrement ;
de recevoir et stocker l’UPO comme preuve d’enregistrement ;
d’inclure le code QR avec le numéro de référence KSeF sur les factures émises.

Avec B2Brouter, vous pouvez abstraire une grande partie de la complexité de ce processus et vous conformer au KSeF. Vous devrez fournir votre certificat électronique qualifié au format PKCS#12, et B2Brouter se chargera de l’authentification, de la soumission et de la récupération de l’UPO.

B2Brouter génère des déclarations fiscales au format FA(3) (variante de formulaire 3, version de schéma 1-0E), qui est le standard actuel pour les soumissions KSeF.

Configurer KSeF avec l’API B2Brouter

La première étape consiste à configurer KSeF pour chaque compte (identifié par un NIP polonais) pour lequel vous souhaitez soumettre des déclarations fiscales. Vous pouvez consulter le guide des paramètres de déclaration fiscale pour une description complète du processus.

Environnements B2Brouter et intégration KSeF

Commencez par le sandbox pour les premiers tests API et la validation des payloads. Les soumissions KSeF sont simulées dans le sandbox, donc aucun certificat KSeF n’est requis. Passez ensuite à l’environnement de staging lorsque vous êtes prêt à tester avec un véritable certificat KSeF sur l’environnement de test ou de démonstration KSeF.

B2Brouter se connecte à différents environnements KSeF selon votre configuration :

Environnement B2Brouter	Environnements KSeF disponibles	Exigences de certificat
API Production `api.b2brouter.net`	KSeF Production uniquement	Certificat KSeF de production
API Staging `api-staging.b2brouter.net`	KSeF Test (par défaut) KSeF Demo (configurable)	Test : certificat KSeF de test ou autosigné Demo : certificat KSeF de préproduction

Pour le développement et les tests :

utilisez l’API Staging (api-staging.b2brouter.net) ;
par défaut, elle se connecte à l’environnement test de KSeF ;
- il accepte les certificats KSeF de test (recommandé) ;
- il accepte également les certificats autosignés pour un développement rapide et les tests d’intégration ;
vous pouvez configurer facultativement l’environnement demo en définissant environment: "demo" lors de la création du paramètre de déclaration fiscale ;
- cela nécessite un certificat KSeF de préproduction ;
pour la production, seuls les certificats KSeF de production fonctionneront.

Exigences relatives au certificat

L’authentification vers KSeF utilise des certificats numériques au format PKCS#12 (.p12 ou .pfx). Le type de certificat requis dépend de l’environnement KSeF :

Pour l’environnement de production :

certificat KSeF de production ;
le client doit se connecter avec sa signature qualifiée ou son profil de confiance (Profil Zaufany) ;
il doit accéder à la section KSeF et générer un certificat KSeF dédié lié à son NIP ;
le sujet du certificat doit correspondre à votre NIP polonais ou être autorisé via ZAW-FA ;
mot de passe / PIN du certificat.

Pour l’environnement Demo (préproduction) :

certificat KSeF de préproduction ;
le certificat doit être au format PKCS#12 (.p12 ou .pfx) ;
le sujet du certificat doit correspondre à votre NIP polonais ou être autorisé via ZAW-FA ;
mot de passe / PIN du certificat.

Pour l’environnement de test (développement) :

certificat KSeF de test (recommandé) ou certificat autosigné (uniquement pour le développement) ;
le certificat doit être au format PKCS#12 (.p12 ou .pfx) ;
pour les certificats autosignés, le numéro de série du certificat doit correspondre au numéro de TVA (NIP) ;
mot de passe / PIN du certificat.

Exemple : encoder votre certificat

# Encode your certificate to base64 without line breaks
base64 -w 0 your-certificate.p12 > certificate-base64.txt

Création du paramètre de déclaration fiscale KSeF

Vous devez configurer l’intégration KSeF pour chaque entreprise pour laquelle vous souhaitez soumettre des factures structurées. Cette configuration définit comment B2Brouter gère la génération et l’envoi des factures au KSeF au nom de votre système. Vous devez configurer ces paramètres pour chaque entreprise avant de soumettre une facture.

Cette étape de configuration embarquera le client dans KSeF et effectuera un test de connexion.
Si le certificat ou la configuration est invalide, le point de terminaison renverra une erreur.

Exemple de requête :

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "ksef",
      "type_operation": "services",
      "credit_note_code": "1",
      "certificate": "MIIKZAIBAzCCCh4GCSqGSIb3DQEHAaCCCg8Egg...",
      "certificate_pin": "YourCertificatePassword",
      "auto_generate": true,
      "auto_send": true,
      "enabled": true
    }
  }'

Paramètres :

code : doit être "ksef" ;
type_operation : type d’opération par défaut ("services" ou "goods") ;
credit_note_code : code d’effet correctif par défaut ("1", "2" ou "3") ;
certificate : votre certificat PKCS#12 encodé en base64 ;
certificate_pin : mot de passe du certificat ;
auto_generate : génère automatiquement des déclarations fiscales pour les factures ;
auto_send : envoie automatiquement les déclarations fiscales au KSeF.

Utiliser les déclarations fiscales KSeF

B2Brouter fournit deux façons de travailler avec le KSeF :

API Tax Report : pour un contrôle direct de la création et de la soumission des déclarations fiscales (RECOMMANDÉ).
API Invoice : si vous utilisez B2Brouter pour émettre des factures, les déclarations fiscales sont générées automatiquement.

API Tax Report

L’API Tax Report vous donne un contrôle maximal sur le processus de soumission au KSeF. Vous pouvez créer des déclarations fiscales en fournissant des données JSON structurées que B2Brouter convertira en XML FA(3).

La structure du format JSON des déclarations fiscales B2Brouter est basée sur PEPPOL Continuous Transaction Control (CTC). Cela signifie que l’API Tax Report de B2Brouter est une API universelle, non seulement orientée KSeF mais conçue pour gérer les déclarations fiscales dans le monde entier.

Important : les déclarations fiscales pour KSeF utilisent tax_report_lines et tax_breakdowns. Chaque tax_report_line représente une ligne de facture avec sa propre quantité, position, unit_code, prix et information fiscale.

Créer une déclaration fiscale

Pour créer une déclaration fiscale KSeF, appelez le point de terminaison create tax report.

Exemple : facture TVA basique

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/001",
      "description": "Consulting services",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting hours",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple : facture corrective (KOR)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "KOR",
      "amend_type": "2",
      "invoice_date": "2025-11-08",
      "tax_point_date": "2025-11-07",
      "invoice_number": "FK/2025/11/001",
      "description": "Correction of invoice F/2025/11/001",
      "amended_ksef_number": "1234567890-20251107-ABCD1234-EF",
      "amended_date": "2025-11-07",
      "amended_number":  "F/2025/11/001",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting hours",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00,
          "ksef_amended": true
        },
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "PCE",
          "description": "Consulting hours - new line",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple : exportation de biens exonérée - facture TVA (devise étrangère)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/003",
      "description": "Sample Exempt VAT Invoice -  Export of Goods",
      "customer_party_name": "EFG Ltd.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Flower (St) 1, Seattle, WA 99999",
      "customer_party_country": "us",
      "currency": "USD",
      "exchange_rate": 3.65,
      "tax_inclusive_amount": 8000,
      "tax_amount": 0,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 20,
          "unit_code": "szt.",
          "description": "lodówka Zimnotech mk1",
          "price": 400,
          "tax_code": "0 EX",
          "tax_exclusive_amount": 8000,
          "tax_amount": 0,
          "tax_inclusive_amount": 8000
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "E",
          "percent": 0.0,
          "taxable_base": 8000,
          "tax_amount": 0,
          "comment": "reason why exempt"
        }
      ]
    }
  }'

Exemple : facture TVA (paiement intégral reçu au moment de l’émission) - Zaplacono

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "payment_date": "2025-11-07",
      "payable_amount": 0,
      "invoice_number": "F/2025/11/004",
      "description": "Sample VAT Invoice (full payment has been received at the time of issue)",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "product 1",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple : facture ZAL (acompte)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "ZAL",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "payment_date": "2025-11-07",
      "payable_amount": 0,
      "invoice_number": "F/2025/11/005",
      "description": "Sample ZAL Invoice (full payment has been received at the time of issue)",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "product 1",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Exemple : facture ROZ (régularisation des acomptes)

Une facture ROZ règle le montant restant après tous les acomptes. Elle référence les factures ZAL précédentes via prepayment_references. Chaque référence correspond à un élément FakturaZaliczkowa dans le XML FA(3).

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "ROZ",
      "invoice_date": "2026-08-17",
      "tax_point_date": "2026-09-17",
      "invoice_number": "FV2026/08/12",
      "description": "Settlement invoice",
      "customer_party_name": "Jan Kowalski",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "ul. Przykładowa 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 306899.80,
      "tax_amount": 22720.76,
      "type_operation": "goods",
      "prepayment_references": [
        { "registration_code": "9999999999-20260215-8BEF280C8D35-4D" },
        { "number": "FZ2026/03/200" }
      ],
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "C62",
          "description": "mieszkanie 50m^2",
          "price": 280177.59,
          "tax_code": "8",
          "tax_exclusive_amount": 280177.59,
          "tax_amount": 22414.21,
          "tax_inclusive_amount": 302591.80
        },
        {
          "position": 2,
          "quantity": 1,
          "unit_code": "C62",
          "description": "usługi dodatkowe",
          "price": 4001.55,
          "tax_code": "23",
          "tax_exclusive_amount": 4001.55,
          "tax_amount": 306.55,
          "tax_inclusive_amount": 4308.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 8.0, "taxable_base": 280177.59, "tax_amount": 22414.21 },
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 4001.55, "tax_amount": 306.55 }
      ]
    }
  }'

prepayment_references : utilisez registration_code pour le numéro KSeF (NrKSeFFaZaliczkowej) ou number pour le numéro de facture (NrFaZaliczkowej) lorsque la ZAL a été émise hors KSeF.

Exemple : facture KOR_ZAL (correction d’acompte)

Une KOR_ZAL corrige une facture ZAL précédemment émise. Utilisez previous_advance_total pour indiquer le montant d’acompte initial (P_15ZK dans le XML FA(3)).

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "KOR_ZAL",
      "amend_type": "1",
      "invoice_date": "2026-03-17",
      "tax_point_date": "2026-02-15",
      "invoice_number": "FK2026/03/7",
      "description": "Correction of advance invoice FZ2026/02/150",
      "amended_ksef_number": "9999999999-20260215-8BEF280C8D35-4D",
      "amended_date": "2026-02-15",
      "amended_number": "FZ2026/02/150",
      "customer_party_name": "Jan Kowalski",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "ul. Przykładowa 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 25000.00,
      "tax_amount": 4674.80,
      "previous_advance_total": 20000.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "C62",
          "description": "mieszkanie 50m^2",
          "price": 300000,
          "tax_code": "23",
          "tax_exclusive_amount": 20325.20,
          "tax_amount": 4674.80,
          "tax_inclusive_amount": 25000.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 20325.20, "tax_amount": 4674.80 }
      ]
    }
  }'

previous_advance_total: 20000.00 : montant brut total de la ZAL d’origine corrigée (correspond à P_15ZK).

Exemple : facture JST (unité d’administration locale)

Une facture adressée à une unité subordonnée d’administration locale (JST). L’acheteur (Podmiot2) est l’entité parente ; le destinataire effectif est un Podmiot3 avec le rôle 8.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2026-03-23",
      "tax_point_date": "2026-03-23",
      "invoice_number": "F/2026/JST/001",
      "description": "Services for local government unit",
      "customer_party_name": "Gmina Kraków",
      "customer_party_tax_id": "6762450871",
      "customer_party_address": "Plac Wszystkich Świętych 3-4",
      "customer_party_country": "pl",
      "customer_party_jst": true,
      "third_party_name": "Szkoła Podstawowa nr 7",
      "third_party_tax_id": "7654321098",
      "third_party_tax_scheme": "9945",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting services",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 1000.0, "tax_amount": 230.00 }
      ]
    }
  }'

customer_party_jst: true : définit Podmiot2/JST sur 1 dans le XML FA(3).
third_party_name / third_party_tax_id : destinataire JST, rendu comme Podmiot3 avec le rôle 8.
Pour les factures à destination d’un membre d’un groupe TVA, utilisez plutôt customer_party_gv: true (rôle 10).

Exemple : facture UPR

Pour UPR, les champs customer_party_tax_id et customer_party_country sont obligatoires.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "UPR",
      "ticket": true,
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/006",
      "description": "Sample UPR Invoice",
      "customer_party_tax_id": "1234567890",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 12.30,
      "tax_amount": 2.30,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "EA",
          "description": "product 1",
          "price": 10.00,
          "tax_code": "23",
          "tax_exclusive_amount": 10.00,
          "tax_amount": 2.30,
          "tax_inclusive_amount": 12.30
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 10.0,
          "tax_amount": 2.30
        }
      ]
    }
  }'

Exemple : facture avec autoliquidation nationale

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/007",
      "description": "Construction services - reverse charge",
      "customer_party_name": "Example Construction Sp. z o.o.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 5000.00,
      "tax_amount": 0.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "EA",
          "description": "Construction services per contract X",
          "price": 5000.00,
          "tax_code": "oo",
          "tax_exclusive_amount": 5000.00,
          "tax_amount": 0.00,
          "tax_inclusive_amount": 5000.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "VAT",
          "category": "AE",
          "percent": 0.0,
          "taxable_base": 5000.0,
          "tax_amount": 0.0,
          "scope": "domestic"
        }
      ]
    }
  }'

Exemple : autoliquidation transfrontalière (services)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/008",
      "description": "Consulting services - cross-border",
      "customer_party_name": "Example Company GmbH",
      "customer_party_tax_id": "DE123456789",
      "customer_party_address": "Berlin Street 1, 10115 Berlin",
      "customer_party_country": "de",
      "currency": "EUR",
      "exchange_rate": 4.30,
      "tax_inclusive_amount": 3000.00,
      "tax_amount": 0.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 20,
          "unit_code": "HUR",
          "description": "IT consulting services",
          "price": 150.00,
          "tax_code": "np I",
          "tax_exclusive_amount": 3000.00,
          "tax_amount": 0.00,
          "tax_inclusive_amount": 3000.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "VAT",
          "category": "AE",
          "percent": 0.0,
          "taxable_base": 3000.0,
          "tax_amount": 0.0
        }
      ]
    }
  }'

Structure de réponse

La réponse inclura la déclaration fiscale avec l’état "sending" :

{
  "tax_report": {
    "id": 12345,
    "type": "KSeF",
    "state": "sending",
    "fingerprint": "a3f2c1b9e8d7...",
    "identifier": "https://ksef-test.mf.gov.pl/client-app/invoice/5792000046/2025-11-07/a3f2c1b9e8d7...",
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    ...
  }
}

Important : contrairement aux modèles de clearance traditionnels, B2Brouter peut générer le fingerprint, l’identifier (URL du code QR) et le qr (image du code QR) immédiatement lors de la création de la déclaration fiscale, sans attendre la confirmation du KSeF. Cela est possible car ces champs sont calculés à partir des données dont nous disposons déjà :

fingerprint : hash SHA-256 du document XML FA(3) ;
identifier : URL construite à partir du NIP du fournisseur + de la date de la facture + du fingerprint (format Base64URL) ;
qr : image du code QR encodant l’URL identifier.

Libellé du code QR :

tant que la déclaration fiscale est dans l’état sending (avant confirmation du KSeF), le libellé du code QR doit afficher “OFFLINE” ;
une fois que la déclaration fiscale atteint l’état registered et que vous recevez le to_net_id (numéro de référence KSeF), vous devez afficher le numéro KSeF sous le code QR à la place.

Bonne pratique : même si les données du code QR sont disponibles immédiatement, il est recommandé d’attendre que la déclaration fiscale atteigne l’état registered avant d’imprimer / envoyer les factures aux clients. Cela garantit que la facture a bien été acceptée par le KSeF et évite des problèmes potentiels si la soumission échoue.

Vérifier l’état de la déclaration fiscale

La soumission au KSeF est asynchrone. Vous devez surveiller l’état de la déclaration fiscale :

Option 1 : utiliser des webhooks (recommandé)

Configurez un webhook de déclaration fiscale pour recevoir des notifications lorsque l’état passe à un état final : registered ou error.

Option 2 : polling

Interrogez le point de terminaison get tax report jusqu’à ce que l’état soit final :

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

Comprendre la réponse à l’état `registered`

Lorsque la déclaration fiscale atteint l’état registered, la réponse inclut le numéro de référence officiel KSeF :

{
  "tax_report": {
    "id": 12345,
    "type": "KSeF",
    "state": "registered",
    "to_net_id": "1234567890-20251107-ABCD1234-EF",
    "fingerprint": "a3f2c1b9e8d7...",
    "identifier": "https://ksef-test.mf.gov.pl/client-app/invoice/1234567890/2025-11-07/a3f2c1b9e8d7...",
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    ...
  }
}

Field	Available	Description
`to_net_id`	After KSeF confirmation	Numéro de référence KSeF - identifiant unique attribué par le KSeF. Affichez ce numéro sous le code QR sur les factures imprimées / PDF.
`fingerprint`	Immediately on creation	Hash SHA-256 du document XML FA(3) soumis. Utilisé pour la vérification de l’intégrité du document et la génération du code QR.
`identifier`	Immediately on creation	URL du code QR - URL complète pointée par le code QR. Construite à partir du NIP du fournisseur + de la date de la facture + du fingerprint.
`qr`	Immediately on creation	Image du code QR - image PNG encodée en base64. Peut être intégrée aux factures immédiatement, avant même la confirmation du KSeF.

Télécharger l’UPO (accusé de réception officiel)

Une fois la déclaration fiscale passée à l’état registered, vous pouvez télécharger l’UPO à l’aide du point de terminaison download response :

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID}/download_response \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Accept: application/xml'

Télécharger le XML FA(3)

Vous pouvez également télécharger le XML FA(3) complet envoyé au KSeF :

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID}/download \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Accept: application/xml'

Sinon, le champ xml_base64 de la réponse de déclaration fiscale contient le XML encodé en base64.

Gestion des erreurs

Si la déclaration fiscale atteint l’état error, consultez les détails de la déclaration fiscale pour obtenir les informations d’erreur :

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

Équivalence entre les champs Tax Report de B2Brouter et les nœuds XML KSeF FA(3)

La structure du format JSON des déclarations fiscales B2Brouter est basée sur PEPPOL Continuous Transaction Control (CTC). Les champs utilisés dans le payload JSON ont des noms différents de ceux de leur représentation XML FA(3). En effet, l’API Tax Report de B2Brouter est une API universelle conçue pour gérer les déclarations fiscales dans le monde entier, et pas seulement le KSeF.

Champs principaux de facture

B2Brouter Field	KSeF FA(3) XML Node
type	Must be “KSeF”
invoice_type_code	Fa > RodzajFaktury
invoice_date	Fa > P_1
invoice_number	Fa > P_2
tax_point_date	Fa > P_6
customer_party_name	Podmiot2 > DaneIdentyfikacyjne > Nazwa
customer_party_tax_id	Podmiot2 > DaneIdentyfikacyjne > NIP (PL) or NrVatUE (EU) or NrID (non-EU)
customer_party_country	Podmiot2 > DaneIdentyfikacyjne > KodUE or KodKraju
supplier_party_name	Podmiot1 > DaneIdentyfikacyjne > Nazwa
supplier_party_tax_id	Podmiot1 > DaneIdentyfikacyjne > NIP
supplier_party_country	Podmiot1 > PrefiksPodatnika
description	Stopka > Informacje > StopkaFaktury
currency	Fa > KodWaluty
exchange_rate	Fa > KursWalutyZ
payment_date	Fa > Platnosc > TerminPlatnosci > Termin (unpaid) or Fa > Platnosc > DataZaplaty (paid)
payable_amount	When set to 0 with payment_date, marks invoice as paid (Zaplacono=1)
payment_means_type_code	Fa > Platnosc > FormaPlatnosci
payment_account_identifier	Fa > Platnosc > RachunekBankowy > NrRB
payment_service_provider_identifier	Fa > Platnosc > RachunekBankowy > SWIFT
amended_ksef_number	Fa > DaneFaKorygowanej > NrKSeFFaKorygowanej
tax_inclusive_amount	Fa > P_15 (total amount)
customer_party_jst	Podmiot2 > JST (`1` when true, `2` when false)
customer_party_gv	Podmiot2 > GV (`1` when true, `2` when false)
third_party_name	Podmiot3 > DaneIdentyfikacyjne > Nazwa
third_party_tax_id	Podmiot3 > DaneIdentyfikacyjne > NIP (PL), NrVatUE (EU), or NrID (non-EU)
purchase_order_date	Fa > WarunkiTransakcji > Zamowienia > DataZamowienia
despatch_advice_reference	Fa > WZ
supplier_contact_email	Podmiot1 > DaneKontaktowe > Email
supplier_contact_phone	Podmiot1 > DaneKontaktowe > Telefon
supplier_party_regon	Stopka > Rejestry > REGON
supplier_party_krs	Stopka > Rejestry > KRS
supplier_party_bdo	Stopka > Rejestry > BDO
previous_advance_total	Fa > P_15ZK (KOR_ZAL only)
prepayment_references	Fa > FakturaZaliczkowa (ROZ/KOR_ROZ only)

Lignes de déclaration fiscale (FaWiersz)

B2Brouter Field	KSeF FA(3) XML Node
position	FaWiersz > NrWierszaFa
description	FaWiersz > P_7
unit_code	FaWiersz > P_8A
quantity	FaWiersz > P_8B
price	FaWiersz > P_9A
discount_amount	FaWiersz > P_10
tax_code	FaWiersz > P_12
tax_exclusive_amount	FaWiersz > P_11
tax_amount	FaWiersz > P_11Vat
ksef_amended	FaWiersz > StanPrzed (marks corrected line)

Ventilation des taxes

B2Brouter Field	KSeF FA(3) XML Node
name	Tax scheme name (e.g., “PTU”, “VAT”)
category	Tax category: “S” (standard), “E” (exempt), “AE” (reverse charge)
percent	Tax rate percentage
taxable_base	P_13_x (taxable amount per rate bucket)
tax_amount	P_14_x (tax amount per rate bucket)
comment	Adnotacje > Zwolnienie > P_19A (exemption reason, when category is “E”)
exemption_code	P_12 override — accepts `zw`
no_subject_code	P_12 override — accepts `np I`, `np II`
non_exemption_code	P_12 override — accepts `0 KR`, `0 WDT`, `0 EX`, `oo`

Les trois champs *_code sont optionnels. Lorsqu’ils ne sont pas définis, B2Brouter déduit le code P_12 à partir de category, percent, scope et type_operation. Définissez l’un de ces champs si vous souhaitez fixer explicitement le code.

Vue d’ensemble de la structure FA(3)

<tns:Faktura xmlns:tns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <tns:Naglowek>
    <tns:KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</tns:KodFormularza>
    <tns:WariantFormularza>3</tns:WariantFormularza>
    <tns:DataWytworzeniaFa><!-- Timestamp --></tns:DataWytworzeniaFa>
    <tns:SystemInfo>B2Brouter</tns:SystemInfo>
  </tns:Naglowek>

  <tns:Podmiot1><!-- Supplier (Seller) --></tns:Podmiot1>
  <tns:Podmiot2><!-- Customer (Buyer) --></tns:Podmiot2>

  <tns:Fa>
    <!-- Invoice details: currency, dates, tax amounts -->
    <!-- Tax breakdown totals: P_13_x, P_14_x, P_15 -->
    <!-- Adnotacje (annotations/flags) -->
    <!-- RodzajFaktury (invoice type) -->

    <tns:FaWiersz><!-- Invoice line 1 --></tns:FaWiersz>
    <tns:FaWiersz><!-- Invoice line 2 --></tns:FaWiersz>

    <tns:Platnosc><!-- Payment details (optional) --></tns:Platnosc>
    <tns:WarunkiTransakcji><!-- Transaction conditions (optional) --></tns:WarunkiTransakcji>
  </tns:Fa>

  <tns:Stopka><!-- Footer/notes (optional) --></tns:Stopka>
</tns:Faktura>

Descriptions des codes des champs spécifiques au KSeF

Codes de type de facture

Param : invoice_type_code

Code	Description	Used for
VAT	Basic invoice	Regular invoices
KOR	Corrective invoice	Corrections
ZAL	Advance payment invoice (Article 106f sec. 4)	Advance payments
ROZ	Invoice per Article 106f sec. 3	Settlements
UPR	Simplified invoice (Article 106e sec. 5 item 3)	Simplified
KOR_ZAL	Corrective invoice for advance payment	Corrections
KOR_ROZ	Corrective invoice for ROZ	Corrections

Codes d’effet des notes de crédit

Type d’effet de la correction dans les registres de TVA. Utilisé pour les factures correctives (KOR, KOR_ZAL, KOR_ROZ). Param : credit_note_code (dans Tax Report Setting)

Code	Description
1	Correction avec effet à la date de comptabilisation de la facture d’origine
2	Correction avec effet à la date d’émission de la facture corrective
3	Correction avec effet à une autre date (ou à des dates différentes selon les lignes)

Codes de taxe

Taux et catégories de TVA utilisés en Pologne. Utilisés au niveau ligne. Param : tax_code (dans tax_report_lines)

Code	Description
23	Taux de TVA standard 23%
22	Taux de TVA standard 22%
8	Taux de TVA réduit 8%
7	Taux de TVA réduit 7%
5	Taux de TVA réduit 5%
4	Taux de TVA réduit 4%
3	Taux de TVA réduit 3%
0 WDT	Livraison intracommunautaire 0% (Wewnątrzwspólnotowa Dostawa Towarów)
0 EX	Exportation 0%
0 KR	Taux national zéro 0%
zw	Exonéré de TVA (zwolniona)
oo	Autoliquidation nationale (odwrotne obciążenie)
np I	Non soumis à la TVA - services transfrontaliers (nie podlega)
np II	Non soumis à la TVA - services nationaux

Codes des moyens de paiement

Param : payment_means_type_code

Code	Description
1	Espèces
2	Carte
3	Bon
4	Mobile
5	Chèque
6	Virement bancaire
7	Autre

Types d’opération

Param : type_operation (dans Tax Report Setting)

Code	Description
services	Services
goods	Biens