DEV Community: Drytrix

Adding Peppol e-invoicing (EN 16931) to a self-hosted Flask app

Dries Peeters — Sun, 27 Sep 2026 06:09:02 +0000

Since 1 January 2026, Belgian businesses have to exchange B2B invoices as structured e-invoices over the Peppol network. A PDF by email no longer counts.

I maintain TimeTracker, an open-source, self-hosted time tracker that also generates invoices. I'm based in Belgium and so are many of the people it's built for, so the mandate turned a nice-to-have into a must-have.

This post covers what I learned building it: the standards, the architecture choice that made it workable for a self-hosted app, and the parts that were harder than expected.

DRYTRIX / TimeTracker

Self-hosted time tracking & invoicing for freelancers and teams: timers, projects, PDF and Peppol e-invoicing. Open-source Toggl/Clockify alternative.

TimeTracker

Professional Time Tracking & Project Management for Teams

Track time. Manage projects. Generate invoices. All in one place.

🆕 What's New • 📥 Download & Install • 🚀 Quick Start • ✨ Features • 📸 Screenshots • 📖 Getting Started • 📚 Documentation • 🗑️ Uninstall • 📋 Changelog • 🐳 Deploy

🎯 What is TimeTracker?

TimeTracker is a self-hosted, web-based time tracking application designed for freelancers, teams, and businesses who need professional time management with complete control over their data.

Perfect for:

💼 Freelancers tracking billable hours across multiple clients
👥 Small Teams managing projects and tracking productivity
🏢 Agencies needing detailed reporting and client billing
🔒 Privacy-focused organizations wanting self-hosted solutions

You can support the project and purchase a key to hide donate prompts in your instance.

📥 Download & Install

Method	Best for	Get started
Docker image	Servers, VPS, homelab	`docker pull ghcr.io/drytrix/timetracker:latest` or Docker Hub

…

View on GitHub

Not legal or tax advice. I'm a developer, not an accountant. Check the official guidance from the Belgian FPS Finance before you rely on any of this for compliance.

The alphabet soup, untangled

When I started, the terms blurred together. Here's what finally made it click:

Term	What it actually is
EN 16931	The European semantic standard: which fields an e-invoice must contain (seller, buyer, VAT breakdown, totals, and so on). It defines data, not a file format.
UBL 2.1 and CII	Two XML syntaxes that can carry EN 16931 data.
Peppol BIS Billing 3.0	The Peppol network's rules on top of EN 16931, expressed in UBL.
Peppol	The transport: a network where businesses connect through certified Access Points ("4-corner model").
Factur-X / ZUGFeRD	A hybrid PDF: a normal human-readable invoice with CII XML embedded inside it.

The key insight: Peppol is the pipe, UBL is what goes through it, and Factur-X is a separate format that happens to share the same underlying standard. They need different XML (UBL for Peppol, CII for Factur-X), so I ended up generating both.

The architecture decision: don't become an Access Point

To send over Peppol you go through an Access Point. You can, in theory, speak the protocol yourself: look up the receiver in the SML/SMP directory, then send the document over AS4 with the right certificates, signatures and receipts.

I built an experimental "native" mode that does SML/SMP lookup and AS4 sending. It works for testing, but it lacks WS-Security, digital signatures and receipt handling, and getting certified is a business in itself. For a self-hosted app used by freelancers, that's the wrong layer to own.

So the recommended path is a generic HTTP transport: TimeTracker builds the UBL and POSTs it, with routing metadata, to an adapter URL. The adapter forwards it to whatever certified Access Point provider the user already has.

The contract is deliberately small:

{
  "recipient": { "endpoint_id": "…", "scheme_id": "…" },
  "sender":    { "endpoint_id": "…", "scheme_id": "…" },
  "document": {
    "id": "INV-…",
    "type_id": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##…::2.1",
    "process_id": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
  },
  "payload": { "ubl_xml": "<?xml version=\"1.0\" …>…</Invoice>" }
}

The adapter returns something like { "message_id": "…" }. Any HTTP status of 400 or higher marks the attempt as failed, and every attempt is stored (pending → sent or failed) so the invoice page can show a full send history.

The bridge sidecar

Asking self-hosters to write their own adapter would kill adoption. So the repo ships a small peppol-bridge service that runs next to the app in Docker Compose:

  peppol-bridge:
    build:
      context: .
      dockerfile: peppol_bridge/Dockerfile
    environment:
      - PEPPOL_BRIDGE_AUTH_TOKEN=${PEPPOL_BRIDGE_AUTH_TOKEN:?Set PEPPOL_BRIDGE_AUTH_TOKEN}
      - PEPPOL_BRIDGE_PROVIDER=einvoice      # or: peppyrus, generic_custom
      - EINVOICE_API_KEY=${EINVOICE_API_KEY:?Set EINVOICE_API_KEY}
    restart: unless-stopped

It exposes /health, /test (checks provider credentials) and /send (the contract above). Provider differences stay inside the bridge. For example, one provider authenticates with an X-Api-Key header instead of Authorization: Bearer, and the app never needs to know.

An admin setup wizard generates this snippet and points the app at http://peppol-bridge:8088/send. Adding a new provider means adding a preset to the bridge, not changing the invoicing code.

Identifiers: small detail, lots of failed sends

Every Peppol party is identified by a scheme ID plus an endpoint ID. For Belgian companies that's typically scheme 0208 with the enterprise number as endpoint.

Two lessons:

Validate identifiers before sending. Both sender and recipient IDs are checked for scheme and format before anything leaves the server. A malformed ID otherwise fails somewhere deep in a provider's API with an unhelpful error.
Recipients are per client. Each client record holds its own endpoint and scheme. The Send via Peppol button only appears when both are present, so users can't try to send to a client who isn't set up.

"Make all invoices Peppol compliant"

Most users don't want to think about BT-codes. So there's a single admin toggle that:

adds the mandatory BIS Billing 3.0 elements, such as InvoiceTypeCode 380 and a Buyer reference (BT-10). If the user leaves BT-10 empty it falls back to the project name, then the invoice number;
shows warnings on the invoice page when required data is missing (company VAT ID, sender endpoint, client endpoint);
adds a Download UBL button, so users whose accountant handles sending can still hand over a compliant file.

The warnings matter as much as the XML. A perfectly generated document still fails if the company VAT ID or the client's endpoint is missing, so surfacing those gaps before the user clicks Send is what makes the feature usable.

Factur-X: the hard part was the PDF, not the XML

Factur-X looks simple: attach an XML file to a PDF. In practice, validators are strict about how.

What the export does:

Embeds factur-x.xml (CII, EN 16931 profile) as a PDF Associated File with relationship Data, MIME type text/xml, and the Factur-X XMP metadata.
Optionally normalises the file to PDF/A-3b in the same pikepdf pass: XMP identification, an sRGB ICC output intent, and the pdfaExtension schema declaration.
Embeds Liberation fonts (metric-compatible with Helvetica, Times and Courier). PDF/A validators reject the unembedded base-14 fonts that many PDF generators use by default, and it's an easy thing to miss.
Can run veraPDF after export to check PDF/A-3b conformance.

And one rule I'd recommend to anyone doing this: fail loudly. If embedding is enabled and the step fails, the export aborts with an error. It never quietly returns a plain PDF that the user believes is compliant. Pre-export checks also block the download when a seller or buyer country is missing, or when reverse charge (VAT category AE) is used without a buyer VAT ID.

What it doesn't do (yet)

Being clear about limits matters more with compliance features than anywhere else:

Sending, not receiving. The mandate also requires businesses to receive e-invoices from suppliers. TimeTracker has no accounts-payable inbox; that half needs another tool or your Access Point provider's portal.
An Access Point account is still needed. The bridge is an adapter, not network membership.
XRechnung (Germany's variant) isn't supported.
In-app validation checks structure, not the full Peppol Schematron rules. External validators are still worth running before you go live.

Takeaways for other developers

Separate "generate the document" from "transport the document." A thin adapter contract let me support several providers without touching invoicing code.
Invest in data-quality warnings. Correct XML is useless if the VAT ID or endpoint behind it is missing.
Hybrid PDFs are a PDF/A project. Budget for fonts, colour profiles and metadata.
Fail loudly on compliance steps. A silent fallback produces non-compliant invoices nobody notices.

Full setup docs are in the repo: PEPPOL_EINVOICING.md and PEPPOL_BRIDGE.md. There's also a plain-language overview at timetracker.drytrix.com/peppol-einvoicing.

If you're working on e-invoicing too, especially for another EU country, I'd love to compare notes in the comments. And if this was useful, a ⭐ on GitHub helps other people find it.

Host Your Own TimeTracker on a Raspberry Pi in 10 Minutes. Updated for 2026.

Dries Peeters — Wed, 01 Oct 2025 12:19:23 +0000

Updated September 2026. TimeTracker has grown a lot since this guide first went up: invoicing, Peppol e-invoicing, mobile and desktop apps, and a much simpler install. The steps below are current.

If you're a freelancer, consultant, or part of a small team, you probably track billable hours somewhere. Most popular tools are SaaS, which means:

your time and client data live on someone else's server,
you pay per user, every month,
and the tool can change its pricing or features whenever it wants.

TimeTracker is an open-source (GPL-3.0), self-hosted alternative. In this guide you'll run it on a Raspberry Pi in about ten minutes, with no git clone and no config editing beyond one secret key.

DRYTRIX / TimeTracker

Self-hosted time tracking & invoicing for freelancers and teams: timers, projects, PDF and Peppol e-invoicing. Open-source Toggl/Clockify alternative.

TimeTracker

Professional Time Tracking & Project Management for Teams

Track time. Manage projects. Generate invoices. All in one place.

🎯 What is TimeTracker?

TimeTracker is a self-hosted, web-based time tracking application designed for freelancers, teams, and businesses who need professional time management with complete control over their data.

Perfect for:

💼 Freelancers tracking billable hours across multiple clients
👥 Small Teams managing projects and tracking productivity
🏢 Agencies needing detailed reporting and client billing
🔒 Privacy-focused organizations wanting self-hosted solutions

You can support the project and purchase a key to hide donate prompts in your instance.

📥 Download & Install

Method	Best for	Get started
Docker image	Servers, VPS, homelab	`docker pull ghcr.io/drytrix/timetracker:latest` or Docker Hub

…

View on GitHub

What you get

Timers that run on the server, so they keep going when you close the browser or your laptop sleeps.
Projects, clients, tasks and a Kanban board.
Invoices generated from tracked time, exported as PDF, with multi-currency and tax support.
Peppol and Factur-X/ZUGFeRD e-invoicing (EN 16931), which matters if you invoice businesses in Belgium.
Reports and CSV export, plus expenses and mileage.
Multi-user with roles, OIDC/SSO and audit logs.
A web app, a Chromium browser extension, an Android app and a desktop app (Windows, macOS, Linux), all talking to your own server.

Want to look around first? There's a live demo, no signup: https://timetracker-demo.drytrix.com

What you need

A Raspberry Pi 4 with 2 GB RAM or more (a Pi 5 works too). Use a 64-bit OS; the images are published for arm64.
Raspberry Pi OS (64-bit) or another Debian-based distro, with network access.

Step 1 — Install Docker

If Docker isn't installed yet:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in (or reboot) so your user can run Docker. The install script includes the docker compose plugin, so you don't need the separate docker-compose package anymore.

Step 2 — Download the compose file

TimeTracker ships a single-file stack meant for NAS boxes and small servers. It pulls the published image and a PostgreSQL database, so there's nothing to build.

mkdir ~/timetracker && cd ~/timetracker
curl -fsSL -o docker-compose.yml \
  https://raw.githubusercontent.com/DRYTRIX/TimeTracker/main/docker-compose.nas.yml

Step 3 — Set a secret key

The stack refuses to start without a SECRET_KEY. Generate one and save it in a .env file next to the compose file:

echo "SECRET_KEY=$(openssl rand -hex 32)" > .env

Optional: the defaults are TZ=Europe/Brussels and CURRENCY=EUR. Change them in the same file if you need to:

echo "TZ=Europe/Amsterdam" >> .env
echo "CURRENCY=USD" >> .env

Step 4 — Start it

docker compose up -d

The first start takes a minute or two on a Pi while PostgreSQL initialises and migrations run. Check progress with:

docker compose logs -f app

Step 5 — Open it

In a browser on your network, go to:

http://<raspberry-pi-ip>:8080

Log in with the username admin. That's the default admin name set by ADMIN_USERNAMES in the compose file; the first login creates the account.

That's it. You're tracking time. 🎉

First things to set up

Create a client and a project, and set an hourly rate, so timers aren't free-floating.
Start a timer from the dashboard. Close the tab, come back later, and it's still running.
Generate an invoice from the tracked time and export the PDF.
Install the browser extension, desktop app or Android app from GitHub Releases and point it at your Pi's address.

Before you rely on it

Access from outside your home network: put it behind a reverse proxy with HTTPS (Caddy, nginx or Traefik), or reach it over a VPN like Tailscale or WireGuard. The compose file uses HTTP-friendly cookie defaults for LAN use; switch those to secure settings when you add HTTPS.
Backups: your data lives in Docker volumes (db_data for the database). Back them up, for example with a nightly pg_dump.
Updates: pull the latest image and restart:

  docker compose pull && docker compose up -d

SD cards wear out. For anything you depend on, boot the Pi from an SSD.

Coming from Toggl, Harvest or Clockify?

TimeTracker can import from the Toggl Track and Harvest APIs directly, and from CSV for everything else. Open Import/Export from the user menu.

Where to go next

⭐ Star TimeTracker on GitHub if it's useful. It helps other people find it.
🌐 Website and comparisons: https://timetracker.drytrix.com
🐛 Questions or bugs: GitHub Issues or Discussions

What are you running on your Pi? I'm curious what else people keep next to their time tracker. 👇