Dokumentacja API

API TachoArchive pozwala programom do pobierania danych, stanowiskom z czytnikiem kart i własnym skryptom automatycznie wysyłać pliki z tachografów do archiwum. To zwykłe REST API przez HTTPS, odpowiada w JSON.

Adres bazowy: https://app.tacho.lnf.polbyte.app/api/v1
Format: JSON (UTF-8), daty w ISO 8601 (UTC)
OpenAPI 3: /openapi.json

Uwierzytelnianie

Utwórz klucz API w panelu w zakładce Ustawienia i API. Klucz jest pokazywany tylko raz – zapisz go w bezpiecznym miejscu. Wysyłaj go w każdym zapytaniu:

Authorization: Bearer ta_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Możesz też użyć nagłówka X-Api-Key. Klucz daje dostęp tylko do plików Twojej firmy. Utwórz osobny klucz dla każdej lokalizacji lub programu – wtedy możesz unieważnić jeden bez zatrzymywania pozostałych.

Wysyłanie plików

POST /files

Wyślij jeden plik w polu multipart "file", do 50 plików w "files[]" albo sam plik jako treść zapytania (Content-Type: application/octet-stream) z nazwą w nagłówku X-Filename. Dozwolone rozszerzenia: .ddd, .c1b, .v1b, .tgd, .esm, .dtco, .add; maks. 30 MB na plik.

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

Odpowiedź dla jednego pliku: 201 Created (nowy plik) albo 200 OK z "duplicate": true (ten sam plik już jest w archiwum – nic nie zapisuje się dwa razy, więc ponowne wysłanie jest bezpieczne).

{
  "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"
}

Przy kilku plikach ("files[]") odpowiedź to {"files": [...]} z jednym wpisem na plik; status 207, jeśli część została odrzucona (te wpisy zawierają "error").

Lista plików

GET /files

Od najnowszych. Parametry zapytania (wszystkie opcjonalne):

kinddriver_card | vehicle_unit | unknown
driver, vehicleID z /drivers lub /vehicles
from, todata przesłania, RRRR-MM-DD
qszukanie w nazwie pliku, nazwisku, numerze karty, rejestracji, VIN
page, per_pagestronicowanie, per_page maks. 200 (domyślnie 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 } }

Jeden plik

GET /files/{id}

Opis jednego pliku (te same pola co wyżej).

Pobranie oryginalnego pliku

GET /files/{id}/download

Zwraca plik dokładnie w takiej postaci, w jakiej został przesłany. Nagłówek X-Sha256 zawiera jego sumę kontrolną.

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

Kierowcy

GET /drivers

Karty kierowców znane z przesłanych plików, z datą ostatniego i następnego pobrania.

{ "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
} ] }

Pojazdy

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"
} ] }

Test klucza

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

Błędy i limity

StatuserrorZnaczenie
401unauthorizedbrak klucza API, błędny lub unieważniony klucz
404not_foundnie ma takiego pliku w Twoim archiwum
422no_file, unsupported_extension, too_large, too_many_fileszapytanie lub plik zostały odrzucone
429—ponad 120 zapytań na minutę dla jednego klucza – odczekaj i ponów

Błędy mają zawsze postać {"error": "kod", "message": "…"}. Przy 429 i 5xx ponów zapytanie po przerwie; dzięki wykrywaniu duplikatów ponowne wysłanie nigdy nie tworzy drugiej kopii.

Automatyczne wysyłanie folderu

Większość programów do pobierania zapisuje pliki w folderze. Ten skrypt PowerShell wysyła nowe pliki i przenosi je do podfolderu "sent"; uruchamiaj go co 15 minut w Harmonogramie zadań Windows.

$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