Zum Hauptinhalt springen

FrachtPilot-API Dokumentation

Die FrachtPilot-API hilft dir eigene Erweiterungen und Automatisierungen von FrachtPilot zu entwickeln. Du hast damit Zugriff auf fast alle Daten in FrachtPilot und kannst sie auch verändern. So können Daten von und zu anderen Apps oder Shops übertragen werden.

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.

Info:

Hier findest du die FrachtPilot API Dokumentation

Hier kannst du die aktuelle OpenAPI-Spezifikation herunterladen: json

Vorbereitung​

Im Personalmanagement (Verwaltungsübersicht ⇾ Firmendaten - 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.

Aufgepasst!

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.

Authentisierung und Beispiel​

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

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 + '.' + date
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', $mail, $date));

$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);

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.
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