API-Dokumentation

Mit der TachoArchive-API senden Download-Programme, Kartenlesestationen und Ihre eigenen Skripte Fahrtschreiberdateien automatisch ins Archiv. Es ist eine einfache REST-API über HTTPS, die in JSON antwortet.

Basis-URL: https://app.tacho.lnf.polbyte.app/api/v1
Format: JSON (UTF-8), Datumsangaben in ISO 8601 (UTC)
OpenAPI 3: /openapi.json

Authentifizierung

Erstellen Sie im Panel unter «Einstellungen & API» einen API-Schlüssel. Der Schlüssel wird nur einmal angezeigt – bewahren Sie ihn sicher auf. Senden Sie ihn mit jeder Anfrage:

Authorization: Bearer ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternativ können Sie den Header X-Api-Key verwenden. Ein Schlüssel gibt nur Zugriff auf die Dateien Ihres Unternehmens. Erstellen Sie für jeden Standort oder jedes Programm einen eigenen Schlüssel – so können Sie einen widerrufen, ohne die anderen zu stoppen.

Dateien hochladen

POST /files

Senden Sie eine Datei im Multipart-Feld "file", bis zu 50 Dateien in "files[]" oder die Datei direkt als Body (Content-Type: application/octet-stream) mit ihrem Namen im Header X-Filename. Erlaubte Endungen: .ddd, .c1b, .v1b, .tgd, .esm, .dtco, .add; max. 30 MB pro Datei.

curl -X POST https://app.tacho.lnf.polbyte.app/api/v1/files \
  -H "Authorization: Bearer $TACHO_KEY" \
  -F "file=@C_20261121_0712_KOWALSKI.DDD"
$headers = @{ Authorization = "Bearer $env:TACHO_KEY" }
Invoke-RestMethod -Method Post -Uri "https://app.tacho.lnf.polbyte.app/api/v1/files" -Headers $headers `
  -Form @{ file = Get-Item "C:\Tacho\C_20261121_0712_KOWALSKI.DDD" }
import os, requests

r = requests.post(
    "https://app.tacho.lnf.polbyte.app/api/v1/files",
    headers={"Authorization": f"Bearer {os.environ['TACHO_KEY']}"},
    files={"file": open("C_20261121_0712_KOWALSKI.DDD", "rb")},
    timeout=60,
)
r.raise_for_status()
print(r.json())
curl -X POST https://app.tacho.lnf.polbyte.app/api/v1/files \
  -H "Authorization: Bearer $TACHO_KEY" \
  -H "Content-Type: application/octet-stream" \
  -H "X-Filename: M_20261120_1530_WX1234A.DDD" \
  --data-binary @M_20261120_1530_WX1234A.DDD

Antwort für eine Datei: 201 Created (neue Datei) oder 200 OK mit "duplicate": true (dieselbe Datei ist bereits im Archiv – nichts wird doppelt gespeichert, erneutes Senden ist also unbedenklich).

{
  "duplicate": false,
  "id": 1842,
  "kind": "driver_card",          // driver_card | vehicle_unit | unknown
  "generation": "2",              // 1 | 2 | 2.2 | null
  "original_name": "C_20261121_0712_KOWALSKI.DDD",
  "size": 28431,
  "sha256": "9f2c0b…",
  "downloaded_at": "2026-11-21T06:12:40+00:00",
  "period_start": "2026-10-21",
  "period_end": "2026-11-21",
  "driver": { "id": 12, "card_number": "PL12345678901234", "surname": "KOWALSKI", "first_names": "JAN" },
  "vehicle": null,
  "source": "api",
  "uploaded_at": "2026-11-21T06:15:02+00:00"
}

Bei mehreren Dateien ("files[]") lautet die Antwort {"files": [...]} mit einem Eintrag pro Datei; Status 207, wenn einige davon abgelehnt wurden (diese Einträge enthalten "error").

Dateien auflisten

GET /files

Neueste zuerst. Query-Parameter (alle optional):

kinddriver_card | vehicle_unit | unknown
driver, vehicleID aus /drivers oder /vehicles
from, toUpload-Datum, JJJJ-MM-TT
qSuche in Dateiname, Name, Kartennummer, Kennzeichen, VIN
page, per_pageSeitenweise Ausgabe, per_page max. 200 (Standard 50)
curl "https://app.tacho.lnf.polbyte.app/api/v1/files?kind=vehicle_unit&from=2026-11-01" -H "Authorization: Bearer $TACHO_KEY"

{ "data": [ { "id": 1843, "kind": "vehicle_unit", … } ],
  "meta": { "page": 1, "per_page": 50, "total": 1, "last_page": 1 } }

Eine Datei

GET /files/{id}

Beschreibung einer Datei (gleiche Felder wie oben).

Originaldatei herunterladen

GET /files/{id}/download

Liefert die Datei genau so, wie sie hochgeladen wurde. Der Header X-Sha256 enthält ihre Prüfsumme.

curl -OJ "https://app.tacho.lnf.polbyte.app/api/v1/files/1842/download" -H "Authorization: Bearer $TACHO_KEY"

Fahrer

GET /drivers

Fahrerkarten aus den hochgeladenen Dateien, mit dem letzten und dem nächsten Download-Termin.

{ "data": [ {
  "id": 12, "card_number": "PL12345678901234", "card_nation": "PL",
  "surname": "KOWALSKI", "first_names": "JAN", "card_expiry": "2030-04-30",
  "last_download_at": "2026-11-21T06:12:40+00:00",
  "next_download_due": "2026-12-19T06:12:40+00:00",
  "status": "ok"                  // ok | soon | overdue | never
} ] }

Fahrzeuge

GET /vehicles
{ "data": [ {
  "id": 4, "vin": "WDB9634031L123456", "vrn": "WX1234A", "vrn_nation": "PL",
  "last_download_at": "2026-11-20T14:30:00+00:00",
  "next_download_due": "2027-02-18T14:30:00+00:00",
  "status": "ok"
} ] }

Schlüssel testen

GET /ping
{ "ok": true, "account": { "id": 1, "name": "Trans-Pol Sp. z o.o.", "country": "PL", "regime": "eu" }, "key": "Download-Station" }

Fehler und Limits

StatuserrorBedeutung
401unauthorizedAPI-Schlüssel fehlt, ist falsch oder widerrufen
404not_foundkeine solche Datei in Ihrem Archiv
422no_file, unsupported_extension, too_large, too_many_filesdie Anfrage oder Datei wurde abgelehnt
429—mehr als 120 Anfragen pro Minute für einen Schlüssel – warten und erneut versuchen

Fehler haben immer die Form {"error": "code", "message": "…"}. Wiederholen Sie bei 429 und 5xx mit einer Pause; dank Duplikaterkennung erzeugt ein wiederholter Upload nie eine zweite Kopie.

Automatischer Upload eines Ordners

Die meisten Download-Programme speichern Dateien in einem Ordner. Dieses PowerShell-Skript lädt neue Dateien hoch und verschiebt sie in den Unterordner "sent"; führen Sie es mit der Windows-Aufgabenplanung alle 15 Minuten aus.

$Key    = "ta_xxxxxxxxxxxx"
$Folder = "C:\Tacho\Download"
$Sent   = Join-Path $Folder "sent"
New-Item -ItemType Directory -Force -Path $Sent | Out-Null

Get-ChildItem $Folder -File -Include *.ddd,*.c1b,*.v1b,*.tgd,*.esm -Recurse:$false | ForEach-Object {
  try {
    Invoke-RestMethod -Method Post -Uri "https://app.tacho.lnf.polbyte.app/api/v1/files" `
      -Headers @{ Authorization = "Bearer $Key" } -Form @{ file = $_ } | Out-Null
    Move-Item $_.FullName -Destination $Sent -Force
  } catch { Write-Warning "$($_.Exception.Message) – $($_.TargetObject)" }
}

Linux / macOS (cron):

#!/bin/sh
cd /data/tacho || exit 1
mkdir -p sent
for f in *.[dD][dD][dD]; do
  [ -f "$f" ] || continue
  curl -fsS -X POST https://app.tacho.lnf.polbyte.app/api/v1/files -H "Authorization: Bearer $TACHO_KEY" -F "file=@$f" \
    && mv "$f" sent/
done