Overview

This module seamlessly connects Odoo 19 with the Polish Government's KSeF 2.0 REST API. It lets you send, receive, and track e-invoices (FA-XML) directly from the Odoo accounting interface — both individually in real time and in bulk asynchronous batches.

Module Architecture & Data Flow

The module is layered into four clear tiers:

Tier	Files	Responsibility
Models	models/	ORM fields, computed values, business logic on invoices
Services	services/ksef_client.py	Low-level HTTP wrapper for the KSeF REST API (no Odoo ORM)
Wizards	wizard/	Interactive UI dialogs for send / batch-send
Controllers	controllers/main.py	Inbound webhook endpoint (POST /ksef/webhook)

Key Features

Models (Database Objects)

account.move — Invoice Extension

The core Odoo invoice model is extended with the following KSeF fields:

Field	Type	Description
ksef_state	Selection	Current KSeF status of the invoice (see status pills below)
ksef_reference_number	Char	Official KSeF ID assigned after acceptance
ksef_element_reference	Char	Temporary reference used for status polling
ksef_sent_at	Datetime	Timestamp when invoice was sent to KSeF
ksef_accepted_at	Datetime	Timestamp when KSeF confirmed acceptance
ksef_environment	Selection	Environment used during sending (test/demo/prod)
ksef_fa_type	Selection	FA invoice type (FA / FAK / FZA / FRZ) — auto computed
ksef_log_ids	One2many	Linked audit log entries

Invoice Status Values:

not_sent – Not Sent pending – Pending / Processing accepted – Accepted by KSeF rejected – Rejected error – Error received – Received from KSeF

ksef.invoice.log — Audit Log

Records every interaction between Odoo and KSeF per invoice.

Field	Description
invoice_id	Linked invoice (cascade delete)
operation	send / batch_send / status_poll / download / receive
invoice_type	FA type at time of operation
element_reference_number	Temporary reference for polling
ksef_reference_number	Official KSeF ID
batch_id	Batch identifier if part of a batch send
state	pending / processing / accepted / rejected / error / received

ksef.session — Session Tracker

Tracks each authenticated KSeF API session for audit and management.

Field	Description
nip	Polish Tax Identification Number (10 digits)
environment	test / demo / prod
session_token	Active session token from KSeF
state	active / terminated / expired / error
terminated_at	Session close timestamp

res.config.settings — Configuration Panel

Settings stored as system parameters (ir.config_parameter):

Parameter	Key	Default
KSeF Environment	ksef.environment	test
Taxpayer NIP	ksef.nip	—
API Token	ksef.api_token	—
Auto-send on Confirm	ksef.auto_send	false
Store KSeF XML	ksef.store_xml	true
API Timeout (sec)	ksef.timeout	30

KSeF API Client (Services Layer)

services/ksef_client.py is a pure Python HTTP wrapper — no Odoo ORM dependency — making it fully testable in isolation.

Covered API Endpoints

Authentication Flow (Challenge–Response)

# 1. Request challenge (timestamp token) from KSeF
challenge = client.authorisation_challenge(nip="1234567890")

# 2. Hash: SHA-256( base64(api_token) + challenge_timestamp )
# 3. Send hashed credentials → receive SessionToken
client.authorise(nip, api_token, challenge)

# 4. All subsequent calls carry the SessionToken header
status = client.invoice_status(element_reference)

# 5. Terminate session when done
client.terminate_session()

Sending Workflows

1 — Interactive (Single Invoice)

2 — Batch (Multiple Invoices)

3 — Auto-Send on Invoice Confirmation

Installation & Setup

Menu & UI Navigation

Path	What You Can Do
Accounting → KSeF → Dashboard	Overview of KSeF activity
Accounting → KSeF → Transmission Log	Full audit log of all KSeF API calls
Accounting → KSeF → Sessions	View and terminate active KSeF sessions
Accounting → Configuration → Settings → KSeF 2.0	Environment, NIP, token, auto-send toggle
Invoice Form → "Send to KSeF" button	Interactive send wizard for one invoice
Invoice List → Action → "Send to KSeF (Batch)"	Batch send wizard for selected invoices
Invoice Form → KSeF Log stat-button	Audit log entries for that specific invoice

Dependencies

Module	Purpose	Required?
account	Base Odoo invoicing framework	✅ Yes
account_edi	EDI framework / FA-XML rendering hooks	✅ Yes
base_setup	Settings panel integration	✅ Yes
Aura Odoo Tech Invoice (paid)	Production-grade FA(2)/FA(3) XML generation	⚠️ Recommended

KSeF Environments

Environment	Base URL	Use For
Production	https://ksef.mf.gov.pl	Live legal invoices
Demo	https://ksef-demo.mf.gov.pl	Demos without legal effect
Test	https://ksef-test.mf.gov.pl	Development & testing

Invoice Type (FA Type) Mapping

FA Type	Odoo move_type	Description
FA	out_invoice / in_invoice	Regular VAT invoice
FAK	out_refund / in_refund or debit origin	Corrective invoice (credit note)
FZA	out_invoice flagged manually	Advance payment invoice
FRZ	out_invoice flagged manually	Settlement (final) invoice against FZA

Webhook Endpoint

The module exposes an HTTP controller at POST /ksef/webhook for receiving push notifications from a KSeF middleware or integration platform. When a POST is received:

• The payload is parsed for a KSeF Reference Number or batch status update.
• The matching account.move record is located and its status updated.
• A new ksef.invoice.log entry with operation receive is created.

External References

Module File Structure

ksef_integration/
├── __manifest__.py      # Module metadata, dependencies, version
├── __init__.py
├── models/
│   ├── account_move.py     # Invoice extension: fields, send logic, XML builder
│   ├── ksef_config.py      # Settings (res.config.settings extension)
│   ├── ksef_invoice_log.py # Audit log model
│   └── ksef_session.py     # Session tracker model
├── services/
│   └── ksef_client.py      # Pure HTTP wrapper for KSeF REST API
├── wizard/
│   ├── ksef_send_wizard.py   # Interactive send dialog
│   └── ksef_batch_wizard.py  # Batch send dialog
├── controllers/
│   └── main.py             # Webhook controller POST /ksef/webhook
├── views/
│   ├── ksef_menu.xml             # Menu items under Accounting → KSeF
│   ├── ksef_config_views.xml     # Settings panel
│   ├── account_move_ksef_views.xml # Invoice form button & stat-button
│   ├── ksef_invoice_log_views.xml # Log list & form views
│   ├── ksef_send_wizard_views.xml # Interactive send wizard view
│   └── ksef_batch_wizard_views.xml # Batch wizard view
├── data/
│   └── ksef_data.xml       # Default data / server actions
├── security/
│   └── ir.model.access.csv # Access rights for all KSeF models
└── static/description/
    └── index.html          # This page