MapTrack API v1

REST API kompatybilne z Traccar + system Webhooków

Base URL: https://maptrack.pl/api/v1
Autentykacja: Authorization: Bearer {api_key} lub Basic Auth (email:api_key)

🔐 Autentykacja

Wszystkie endpointy (oprócz /docs) wymagają klucza API.

Nagłówek Authorization

curl -H "Authorization: Bearer YOUR_API_KEY" https://maptrack.pl/api/v1/devices

Basic Auth

curl -u "email@example.com:YOUR_API_KEY" https://maptrack.pl/api/v1/devices

Query param (fallback)

curl "https://maptrack.pl/api/v1/devices?token=YOUR_API_KEY"

Uprawnienia

Poziom	Operacje
`read`	GET — odczyt danych
`write`	POST, PUT, DELETE — zapis danych
`admin`	Zarządzanie kluczami API, pełny dostęp

🖥️ Serwer

GET /server

Informacje o serwerze (wersja, strefa czasowa, capabilities)

📱 Urządzenia

GET /devices

Lista urządzeń użytkownika z aktualną pozycją

GET /devices/{id}

Dane jednego urządzenia

Przykład odpowiedzi

{
  "id": 1,
  "name": "Fiat Ducato",
  "uniqueId": "352093081452451",
  "status": "online",
  "lastUpdate": "2026-09-22T08:00:00Z",
  "phone": "600123456",
  "category": "van",
  "position": {
    "latitude": 51.1234,
    "longitude": 17.0456,
    "speed": 35.1,
    "course": 180,
    "fixTime": "2026-09-22T08:00:00Z"
  }
}

📍 Pozycje

GET /positions

Ostatnie pozycje wszystkich urządzeń

GET /positions?deviceId={id}&from={ISO}&to={ISO}

Historia pozycji w zakresie dat

Parametr	Typ	Opis
`deviceId`	int	ID urządzenia
`from`	ISO 8601	Data początkowa wymagany
`to`	ISO 8601	Data końcowa wymagany
`limit`	int	Max wyników (domyślnie 5000, max 10000) opcjonalny
`speedUnit`	string	`kmh` (domyślnie) lub `kn` (węzły / knots) opcjonalny

📊 Raporty

Wszystkie raporty wymagają parametrów: deviceId, from, to

GET /reports/route

Pozycje GPS na trasie (jak /positions z datami)

GET /reports/trips

Przejazdy — segmenty jazdy z dystansem, adresami start/koniec

GET /reports/stops

Postoje — segmenty idle z lokalizacją i czasem trwania

GET /reports/summary

Podsumowanie dzienne — kilometry, minuty jazdy/postoju

GET /reports/events

Zdarzenia (ignition, alarm, speed) w zakresie dat

Przykład — Trips

curl -H "Authorization: Bearer KEY" \
  "https://maptrack.pl/api/v1/reports/trips?deviceId=1&from=2026-09-01T00:00:00Z&to=2026-09-22T23:59:59Z"

{
  "deviceId": 1,
  "startTime": "2026-09-22T07:15:00Z",
  "startAddress": "Wrocław",
  "endTime": "2026-09-22T08:30:00Z",
  "endAddress": "Strzelin",
  "distance": 42500,
  "distanceKm": 42.5,
  "duration": 4500000,
  "durationMinutes": 75,
  "averageSpeed": 30.6,
  "maxSpeed": 48.9
}

🔔 Zdarzenia

GET /events

Ostatnie zdarzenia (domyślnie 24h)

GET /events?deviceId={id}&from={ISO}&to={ISO}&type={type}

Zdarzenia filtrowane

Typy zdarzeń

Typ	Opis
`ignitionOn`	Włączenie zapłonu
`deviceOverspeed`	Przekroczenie prędkości
`alarm`	Alarm (SOS)
`maintenance`	Serwis / ważność

🗺️ Geofence'y (strefy)

GET /geofences

Lista stref

POST /geofences

Utwórz strefę

PUT /geofences/{id}

Modyfikuj strefę

DELETE /geofences/{id}

Usuń strefę

Przykład — Tworzenie geofence'a (okrąg)

curl -X POST -H "Authorization: Bearer KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Baza Strzelin",
    "area": {"type":"circle","center":[17.064,"50.714"],"radius":500},
    "deviceIds": [1, 2, 3]
  }' https://maptrack.pl/api/v1/geofences

🔗 Webhooks

GET /webhooks

Lista webhooków

POST /webhooks

Zarejestruj webhook

PUT /webhooks/{id}

Modyfikuj webhook

DELETE /webhooks/{id}

Usuń webhook

POST /webhooks/{id}/test

Wyślij testowe zdarzenie

Przykład — Rejestracja webhooka

curl -X POST -H "Authorization: Bearer KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Mój CRM",
    "url": "https://crm.example.com/api/maptrack-webhook",
    "events": ["deviceMoving", "ignitionOn", "ignitionOff", "alarm"]
  }' https://maptrack.pl/api/v1/webhooks

Payload webhooka

{
  "event": {
    "type": "ignitionOn",
    "deviceId": 1,
    "eventTime": "2026-09-22T08:00:00Z"
  },
  "device": {
    "id": 1,
    "name": "Fiat Ducato",
    "uniqueId": "352093081452451"
  },
  "position": {
    "latitude": 51.1234,
    "longitude": 17.0456,
    "speed": 0
  }
}

Weryfikacja signature

# Header: X-Webhook-Signature: sha256=abc123...
# Weryfikacja w PHP:
$signature = 'sha256=' . hash_hmac('sha256', $rawBody, $yourSecret);
$valid = hash_equals($signature, $_SERVER['HTTP_X_WEBHOOK_SIGNATURE']);

Auto-deaktywacja: Webhook jest automatycznie deaktywowany po 10 kolejnych niepowodzeniach. Reaktywuj przez PUT /webhooks/{id} z {"active": true}.

🔑 Klucze API

GET /keys

Lista kluczy (wymaga uprawnień admin)

POST /keys

Generuj nowy klucz API

DELETE /keys/{id}

Usuń klucz API

Przykład — Generowanie klucza

curl -X POST -H "Authorization: Bearer ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Integration",
    "permissions": ["read", "write"],
    "rateLimit": 200,
    "expiresIn": 365
  }' https://maptrack.pl/api/v1/keys

Uwaga: Pełny klucz API jest wyświetlany tylko raz — przy tworzeniu. Zapisz go natychmiast! Później klucz będzie zamaskowany.

⚠️ Kody błędów

Kod	Znaczenie
`400`	Nieprawidłowe zapytanie (brak parametrów, zły format)
`401`	Brak lub nieprawidłowy klucz API
`403`	Brak uprawnień do zasobu
`404`	Zasób nie znaleziony
`405`	Niedozwolona metoda HTTP
`429`	Rate limit — za dużo requestów
`500`	Wewnętrzny błąd serwera

{
  "error": true,
  "message": "Opis błędu",
  "code": 401
}

⏱️ Rate Limiting

Domyślny limit: 50 requestów/minutę per klucz API.

Limit konfigurowalny przy tworzeniu klucza (parametr rateLimit, max 100).

Przy przekroczeniu limitu serwer zwraca 429 Too Many Requests.