Zum Hauptinhalt springen

FrachtPilot-API Dokumentation

Die FrachtPilot-API hilft dir eigene Erweiterungen und Automatisierungen von FrachtPilot zu entwickeln. Du hast mit der API Zugriff auf viele Bewegungs- und Stammdaten in FrachtPilot. So können Daten von und zu anderen Apps oder Shops übertragen werden.

Info:

Die FrachtPilot-API folgt dem REST-Ansatz und erlaubt die Standard-HTTP-Anfragemethoden (GET, POST, PUT, PATCH und DELETE). Die Stamm-URL der API lautet https://my.frachtpilot.de/api_v2/. Die Daten können im ld+json oder im json Format ausgetauscht werden.

Erzeugung API-Key​

Im Personalmanagement kannst du nach dem Freischalten Benutzerzugänge zur API anlegen und einen API-Key zur Authentisierung erzeugen. Die Rechte zum Lesen und Bearbeiten von Objekten erfolgen anhand der Rechte des dafür angelegten Benutzers. Für deinen Admin-Benutzer kannst du keinen API-Key erzeugen, sondern musst einen weiteren Benutzer dafür anlegen.

API-Key!

Speicher die erzeugten API-Keys sicher ab und gebe niemandem Zugriff darauf.

Wir empfehlen die Vergabe einer E-Mail-Adresse pro API-Schlüssel, damit der API-Schlüssel nur in Kombination mit der E-Mail-Adresse verwendet werden kann.

Einen neuen Benutzer mit API-Zugriff anlegen​

So kannst du einen neuen Benutzer mit Zugriff auf die API hinzufügen:

  1. Im Personalmanagement legst du einen neuen Mitarbeiter an mit Klick auf den Button "Neuen Mitarbeiter anlegen".
  2. Du musst hier einen Vor- und Nachnamen vergeben. Verwende hier etwas, damit du weißt, wofür der API-Key verwendet wird.
  3. Es gibt zwei Möglichkeiten, API-Keys in FrachtPilot anzulegen:
    • Ohne E-Mail-Adresse: Du erhältst nur einen API-Schlüssel.
    • Mit E-Mail-Adresse: Du kannst einem Benutzer Zugriff geben und gleichzeitig diesen API-Schlüssel mit den gleichen Rechten wie der Benutzer hat verwenden.
  4. Weiter unten kannst du die verschiedenen Rollen auswählen. Abhängig von den ausgewählten Rollen erhält der API-Key entsprechenden Zugriff. Die Informationen über die Rollen findest du auf der Seite Benutzerrollen.
  5. Den API-Zugriff musst du unten rechts bei "Benutzerzugriff" mit einem Klick auf "API-Schlüssel" aktivieren.
  6. Wenn du auch Zugriff für den Benutzer mit der E-Mail-Adresse geben möchtest, dann musst du auch den Haken bei "E-Mail-Adresse und Passwort" setzen. In diesem Fall muss die E-Mail-Adresse existieren und du musst den Zugriff über diese E-Mail-Adresse bestätigen.
  7. Verwendest du nur eine E-Mail-Adresse und den API-Schlüssel, so wird die E-Mail-Adresse nicht bestätigt. Du könntest hier also auch E-Mail-Adressen verwenden, einfach nur damit du weißt, welche API-Schlüssel zu welchen Funktionen gehört.

Einen API-Key neu generieren​

Im Personalmanagement kannst du mit Klick auf

den API-Key für den Benutzer neu generieren.

Vorsicht: Durch das Neugenerieren wird der aktuelle API-Key ungültig.

Authentifizierung und Beispiel​

Für die Authentisierung wird neben dem API-Schlüssel auch ein CSRF-Token benötigt.

Wichtig: E-Mail-Adresse in Kleinbuchstaben

Die E-Mail-Adresse muss für die Generierung des CSRF-Tokens in Kleinbuchstaben (lowercase) umgewandelt werden. Andernfalls schlägt die Authentifizierung fehl.

Beispiel Python​

import hashlib
from datetime import datetime

import requests

api_url = 'https://my.frachtpilot.de/api_v2/customers?page=1'
api_key = 'Beispiel-API-Schlüssel1337'
mail = 'name@host.de'  # auch ein leerer String möglich, wenn ein Nutzer keine E-Mail hat  

date = datetime.now()
date = date.strftime("%Y-%m-%d")
csrf = mail.lower() + '.' + date  # E-Mail muss lowercase sein!
csrf_token = hashlib.md5(csrf.encode())

payload = {'X-AUTH-TOKEN': api_key, 'X-CSRF-TOKEN': csrf_token.hexdigest()}
response = requests.get(api_url, headers=payload)


Beispiel PHP​

$apiUrl = 'https://my.frachtpilot.de/api_v2/customers?page=1';

$api_key = 'Beispiel-API-Schlüssel1337';
$mail = 'name@host.de'; // auch ein leerer String möglich, wenn der API-Nutzer keine E-Mail hat

$date = date("Y-m-d");
$csrf_token = md5(sprintf('%s.%s', strtolower($mail), $date)); // E-Mail muss lowercase sein!

$headers = [
    'X-AUTH-TOKEN: '.$api_key,
    'X-CSRF-TOKEN: '.$csrf_token
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$response = curl_exec($ch);
curl_close($ch);

Beispiel JavaScript (Node.js)​

const crypto = require('crypto');

const apiUrl = 'https://my.frachtpilot.de/api_v2/customers?page=1';
const apiKey = 'Beispiel-API-Schlüssel1337';
const email = 'name@host.de'; // auch ein leerer String möglich, wenn der API-Nutzer keine E-Mail hat

const now = new Date();

// Format: YYYY-MM-DD
const dateStr = now.toLocaleDateString('en-CA', {timeZone: 'Europe/Berlin'});
// WICHTIG: E-Mail muss kleingeschrieben sein (entspricht strtolower() in PHP)
const normalizedEmail = email.toLowerCase();

const inputString = `${normalizedEmail}.${dateStr}`;
const csrfToken = crypto.createHash('md5').update(inputString).digest('hex');

const response = await fetch(apiUrl, {
    method: 'GET',
    headers: {
        'X-AUTH-TOKEN': apiKey,
        'X-CSRF-TOKEN': csrfToken
    }
});

Operationen auf Collections​

Responses bei Collections sind auf 30 Items per Page limitiert.

Hinweise​

  • Derzeit gibt es keine Limits für die API. Daher bitten wir darum, schlank zu programmieren und die Anzahl der Requests auf die notwendige Anzahl zu beschränken und häufig benötigte Daten lokal zwischenzuspeichern. Außerdem sollte die Anzahl der parallel ausgeführten Requests niedrig sein.
  • Wir behalten uns vor, Limits für die Anzahl der möglichen Requests einzuführen.
  • Bei schädlicher Nutzung der API behalten wir uns vor, den API-Zugang für das jeweilige System dauerhaft zu deaktivieren.

Häufige Probleme mit dem CSRF-Token​

Warum schlägt meine Authentifizierung fehl, obwohl der API-Key korrekt ist?​

In den meisten Fällen liegt das Problem bei der Generierung des CSRF-Tokens. Prüfe folgende Punkte:

E-Mail-Adresse nicht in Kleinbuchstaben

Die E-Mail-Adresse muss vor der Generierung des CSRF-Tokens vollständig in Kleinbuchstaben umgewandelt werden. Name@Host.de führt zu einem anderen Hash als name@host.de.

  • Python: mail.lower()
  • PHP: strtolower($mail)
  • JavaScript: email.toLowerCase()

Leerzeichen vor oder nach der E-Mail-Adresse

Überprüfe, ob deine E-Mail-Adresse führende oder abschließende Leerzeichen enthält. Bereits ein einzelnes Leerzeichen verändert den generierten Hash und führt zu einem ungültigen Token.

  • Python: mail.strip().lower()
  • PHP: strtolower(trim($mail))
  • JavaScript: email.trim().toLowerCase()

Falsches Datumsformat

Das Datum muss im Format YYYY-MM-DD vorliegen (z. B. 2026-04-13). Ein abweichendes Format wie DD.MM.YYYY oder MM/DD/YYYY erzeugt einen falschen Hash.

Falsche Zeitzone

Das Datum muss dem aktuellen Tag auf dem FrachtPilot-Server entsprechen (Zeitzone Europe/Berlin). Besonders bei Requests kurz vor oder nach Mitternacht kann es vorkommen, dass dein lokales Datum vom Serverdatum abweicht.

info

Verwende immer die IRI-Schreibweise zur Referenz auf Entitäten. In einem kommenden Update der API wird der Zugriff über IDs deaktiviert. Der Zeitpunkt dafür steht aber noch nicht fest.

Richtig mit IRI (enthält die ID): /api_v2/products/1

Falsch mit ID: 1