Zurück zur Startseite

API Dokumentation

Integrieren Sie UniTracker nahtlos in Ihre bestehenden Logistik- und ERP-Systeme über unsere RESTful API.

REAL-TIME EVENTSBevorzugen Sie Event-Push statt Polling?

Erfahren Sie alles über unsere Webhook-Endpunkte für Paketstatus, Fahrer-Events und Empfänger-Präferenzen.

Webhooks Docs

Authentifizierung

Öffentliche Endpunkte zum Lesen grundlegender Paketstatus benötigen keine Authentifizierung. Für alle Endpunkte, die Daten erstellen oder ändern, ist jedoch ein API-Schlüssel erforderlich. Sie können API-Schlüssel im Admin-Dashboard generieren.

Headers:

x-api-key: YOUR_API_KEY

Content-Type: application/json

Fehler-Format

Alle API-Fehler folgen einem standardisierten JSON-Format, um die Fehlerbehebung zu erleichtern.

{
  "success": false,
  "error": "Error message description",
  "code": 400
}

Ratenbegrenzung & Quotas

Um einen stabilen und sicheren Betrieb zu gewährleisten, unterliegen alle API-Endpunkte einer Ratenbegrenzung mit Sliding-Window-Zählern. Standardmäßig haben authentifizierte Anfragen mit API-Schlüssel ein deutlich höheres Kontingent als anonyme Abfragen.

Mit API-Schlüssel
120 req / min

Standard für verifizierte Partner & Carrier

Öffentlich (IP-basiert)
30 req / min

Tracking-Abfragen ohne Authentifizierung

Burst-Puffer
+10 requests

Toleranz für kurzzeitige Lastspitzen

Rate-Limit HTTP-Header

X-RateLimit-Limit: 120 // Maximale Anfragen im aktuellen Zeitfenster

X-RateLimit-Remaining: 84 // Verbleibende Anfragen im Zeitfenster

X-RateLimit-Reset: 1727140000 // UTC Unix-Timestamp, wann das Fenster zurückgesetzt wird

Retry-After: 18 // Sekunden bis zur nächsten erlaubten Anfrage (bei HTTP 429)

HTTP 429 Antwort bei Limit-Überschreitung

{
  "success": false,
  "error": "Rate limit exceeded. Maximum 120 requests per 60s allowed. Please retry in 18 seconds.",
  "code": 429,
  "limit": 120,
  "remaining": 0,
  "reset": 1727140000,
  "retryAfter": 18,
  "identifierType": "api_key"
}

Endpunkte

GET/api/v1/packages/{trackingCode}
Öffentlich (Keine Auth)

Rufen Sie grundlegende Tracking-Informationen und den Verlauf für ein bestimmtes Paket ab.

Antwort-Beispiel

{
  "trackingId": "TRK-987654321",
  "currentStatus": "IN_TRANSIT",
  "lastUpdated": "2026-07-29T10:00:00.000Z",
  "history": [
    {
      "status": "LABEL_CREATED",
      "timestamp": "2026-07-28T14:30:00.000Z",
      "note": "Label created by sender"
    }
  ]
}
POST/api/v1/packages
Auth Erforderlich

Erstellen Sie ein neues Paket oder aktualisieren Sie ein bestehendes. Wenn die trackingId existiert, wird ein neues Verlaufsereignis angehängt und der currentStatus aktualisiert.

Hinweis zur Autorisierung: API-Schlüssel können an einen oder mehrere Benutzer gebunden werden. Sie können nur Pakete aktualisieren, die derzeit einem der Ihrem API-Schlüssel zugeordneten Benutzer zugewiesen sind. Wenn Ihr API-Schlüssel an mehrere Benutzer gebunden ist, MÜSSEN Sie responsibleUserId im Anfragekörper angeben, um anzugeben, welcher Benutzer die Aktualisierung vornimmt. Wenn Sie versuchen, ein Paket zu aktualisieren, das einem nicht an Ihren Schlüssel gebundenen Benutzer zugewiesen ist, erhalten Sie einen 403 Forbidden Fehler. Wenn ein Paket über die API erstellt wird, wird der angegebene Benutzer automatisch zum verantwortlichen Transporteur.

Erlaubte Paket-Status

LABEL_CREATED, PICKED_UP, AT_SORTING_FACILITY, IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED, DELAYED_WEATHER, DELAYED_CUSTOMS, ATTEMPTED_DELIVERY_FAILED, RETURNED_TO_SENDER, LOST_IN_TRANSIT, DAMAGED

Anfrage-Body

{
  "trackingId": "TRK-123456789",
  "currentStatus": "IN_TRANSIT",
  "note": "Arrived at customs", // Optional
  "responsibleUserId": "usr-123", // Required if API key is bound to multiple users
  "recipientName": "John Doe", // Optional, used on creation
  "recipientAddress": "123 Main St", // Optional, used on creation
  "recipientPhone": "+15550100" // Optional, used on creation
}

Erfolgreiche Antwort

{
  "success": true,
  "trackingId": "TRK-123456789",
  "status": "Updated"
}

Fehler-Antwort (403)

{
  "success": false,
  "error": "Forbidden: You are not responsible for this package",
  "code": 403
}
GET/api/v1/users
Auth Erforderlich

Rufen Sie die Liste der Ihrem API-Schlüssel zugeordneten Benutzer (Fahrer/Subunternehmer) ab. Dies ist nützlich, um die richtige responsibleUserId für das Erstellen oder Aktualisieren von Paketen im Namen verschiedener Fahrer zu identifizieren.

Erfolgreiche Antwort

{
  "users": [
    {
      "id": "usr-123",
      "name": "John Doe Driver"
    },
    {
      "id": "usr-456",
      "name": "Jane Smith Subcontractor"
    }
  ]
}