TimeTracker
Send the invoices you make in TimeTracker over the Peppol network, through its self-hosted bridge.
TimeTracker is an open-source, self-hosted time tracking and invoicing app. It generates each invoice as Peppol BIS 3.0 UBL and hands it to peppol_bridge, a small service that ships with TimeTracker and forwards the document to an access point. With the getpeppr preset, the bridge sends it through getpeppr, which validates it against the official Peppol rulebooks and delivers it to the recipient's access point.
develop branch (pull request #847, after the maintainer's agreement on issue #840). It is not in a TimeTracker release yet: until the next one, build the bridge from a checkout of develop.
Set up the bridge
Create an account and a sandbox key (sk_sandbox_…) in the getpeppr console. The key decides the environment: a sandbox key sends on the Peppol test network, a live key (sk_live_…) in production. Then add the bridge to your TimeTracker compose file with the getpeppr preset:
services:
peppol-bridge:
build:
context: .
dockerfile: peppol_bridge/Dockerfile
environment:
- PEPPOL_BRIDGE_AUTH_TOKEN=${PEPPOL_BRIDGE_AUTH_TOKEN:?Set PEPPOL_BRIDGE_AUTH_TOKEN}
- PEPPOL_BRIDGE_TIMEOUT_S=30
- PEPPOL_BRIDGE_PROVIDER=getpeppr
- GETPEPPR_API_KEY=${GETPEPPR_API_KEY:?Set GETPEPPR_API_KEY}
ports: []
restart: unless-stoppedIn TimeTracker's admin area, open System Settings, then the Peppol Setup wizard, and pick the getpeppr preset. Enter the bridge URL http://peppol-bridge:8088 and the same PEPPOL_BRIDGE_AUTH_TOKEN. The full list of bridge settings, getpeppr section included, is in TimeTracker's PEPPOL_BRIDGE.md.
Check who you send as
The bridge's /test endpoint calls GET /v1/identity, which reads your account without changing anything. It returns the environment of the key and your company's Peppol identifiers with their status. The bridge publishes no port, so run the call from a container on the same Docker network:
curl -X POST http://peppol-bridge:8088/test{
"ok": true,
"provider": "getpeppr",
"data": {
"environment": "sandbox",
"legal_entity": { "company_name": "Acme BV", "country": "BE" },
"identifiers": [{ "scheme": "0208", "value": "0123456789", "status": "verified" }]
}
}getpeppr takes the sender from your API key, and it refuses a document whose supplier is another company. So the Sender Endpoint ID and Sender Scheme ID in TimeTracker's Peppol settings must be an identifier that /test lists as verified. An identifier in any other status cannot send: wait while it reads pending or provisioning, and check it in the console if it reads failed. TimeTracker writes the standard or zero-rated VAT category, and both require the seller's VAT number (Peppol rules BR-S-02 and BR-Z-02): fill in your company's tax ID in TimeTracker's company settings.
Send a test invoice
With a sandbox key, give a TimeTracker client the Peppol test receiver 0208:0314595348 as Peppol endpoint (scheme 0208, identifier 0314595348), then send one of its invoices over Peppol. The bridge passes the UBL to POST /v1/invoices/import exactly as TimeTracker generated it, with the client's scheme:identifier as the only routing. A document that breaks a Peppol rule is refused before anything is sent.
Accepted is not delivered. TimeTracker marks the transmission as sent as soon as getpeppr accepts the document, then asks the bridge for the status, which reads GET /v1/invoices/{id}. Only a failure changes what it recorded:
| getpeppr status | In TimeTracker | Meaning |
|---|---|---|
submitted | Sent | Accepted by getpeppr, on its way. Not delivered yet. |
delivered, and the buyer's answers (acknowledged, accepted, rejected, paid…) | Sent | The recipient's access point received it. A rejected is the buyer's business answer after delivery. |
no_action | Failed, with the reason in the history | The recipient could not be found on the Peppol network. Check the client's Peppol ID. |
failed | Failed, with the reason in the history | The document could not be delivered. |
So TimeTracker shows the same Sent whether the document is still on its way or delivered. It checks the status for a few seconds after the send, and only a failure seen then turns it into Failed. For the real state, delivered or failed later, look the document up in the getpeppr console: its id is the message id in the invoice's Peppol history.
Something does not work between TimeTracker and getpeppr? Write to hello@getpeppr.dev with that message id, so we can find the document right away.
Resending
- The bridge gives every send an idempotency key built from the invoice, its recipient and the UTC date. The PDF that TimeTracker embeds is left out of the key, because it is regenerated on every attempt and is not always attached. Sending the same invoice again the same day never delivers a second copy: getpeppr answers with the original document, or refuses the resend when the request differs. TimeTracker then shows a failed send although the first one went out, so check the document in the getpeppr console before sending it again.
- The same invoice number to the same recipient within 15 minutes is refused (
409 duplicate_document). - A resend on a later UTC day, and more than 15 minutes after the first one, is a new request: it goes out, and getpeppr marks it as a duplicate of the earlier document.
- A corrected invoice is a new send.
Next steps
Create a free sandbox key and send your first TimeTracker invoice to 0208:0314595348. When it reads delivered, prepare production as described in Going to Production: complete your company's production onboarding in the console and create a live key. Put that key in the bridge, run /test again, and set TimeTracker's Sender Endpoint ID and Sender Scheme ID to an identifier it lists as verified in production.