Zurück zur Startseite

API-Dokumentation

Integrieren Sie packageHunter in Ihre Systeme

Version 1.0.0 Base URL: /api/v1

Authentifizierung

Alle API-Anfragen erfordern einen API-Key im Header:

Authorization: Bearer YOUR_API_KEY

Wichtig

Ihren API-Key finden Sie im Dashboard Ihres packageHunter-Servers unter Einstellungen. Behandeln Sie diesen vertraulich.

Ihre Subdomain

Nach Abschluss Ihres Abos erhalten Sie einen eigenen Server mit Ihrer eigenen Subdomain (z.B. ihre-firma.packagehunter.de).

Endpoints

POST /api/v1/trackings

Importieren Sie eine oder mehrere Sendungsverfolgungen in das System

Request Body

Content-Type: application/json

{

"trackings": [TrackingCreateRequest[]] *

}

Schema: TrackingCreateRequest

Feld	Typ	Pflicht	Beschreibung
carrier	string	Ja	Versanddienstleister (z.B. DHL, DPD, UPS)
trackingNumber	string	Ja	Sendungsnummer des Carriers
deliveryNoteNumber	string	Ja	Lieferscheinnummer
shippingDate	date	Ja	Versanddatum (ISO 8601: YYYY-MM-DD)
items	DeliveryItem[]	Ja	Bestellpositionen
shippingAddress	ShippingAddress	Ja	Lieferadresse
orderNumber	string	Nein	Bestellnummer
orderDate	date	Nein	Bestelldatum
customIdentifier	string	Nein	Eigene Referenz-ID
totalPrice	float	Nein	Gesamtwert der Bestellung
estimatedDeliveryDate	date	Nein	Voraussichtliches Lieferdatum
weight	float	Nein	Gewicht in kg
bulkyGood	boolean	Nein	Sperrgut (Standard: false)
dangerousGood	boolean	Nein	Gefahrgut (Standard: false)

Schema: DeliveryItem

Feld	Typ	Pflicht	Beschreibung
articleNumber	string	Ja	Artikelnummer / SKU
quantity	integer	Ja	Menge
unitPrice	float	Nein	Einzelpreis
description	string	Nein	Produktbeschreibung

Schema: ShippingAddress

Feld	Typ	Pflicht	Beschreibung
zipCode	string	Ja	Postleitzahl
city	string	Ja	Stadt
countryIsoCode	string	Ja	ISO 3166-1 Alpha-2 Ländercode (z.B. DE)
name	string	Nein	Empfängername
customerNumber	string	Nein	Kundennummer
email	string	Nein	E-Mail-Adresse
street	string	Nein	Straße und Hausnummer
company	string	Nein	Firmenname
additionalAddress	string	Nein	Adresszusatz (z.B. c/o, Etage)

Response Codes

201 Created - Trackings erfolgreich erstellt

{
  "success": true,
  "message": "",
  "data": {
    "new": 5,
    "alreadyExists": 2
  }
}

400 Bad Request - Validierungsfehler

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    "trackingNumber: Dieses Feld ist erforderlich",
    "shippingAddress.zipCode: Ungültiges Format"
  ]
}

401 Unauthorized - Ungültiger oder fehlender API-Key

Beispiel Requests

Minimales Beispiel

curl -X POST https://{ihre-subdomain}.packagehunter.de/api/v1/trackings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackings": [
      {
        "carrier": "DHL",
        "trackingNumber": "00340400000000000001",
        "deliveryNoteNumber": "LS-2024-001",
        "shippingDate": "2024-12-20",
        "items": [
          {
            "articleNumber": "ART-12345",
            "quantity": 1
          }
        ],
        "shippingAddress": {
          "zipCode": "46244",
          "city": "Bottrop",
          "countryIsoCode": "DE"
        }
      }
    ]
  }'

Vollständiges Beispiel mit allen Feldern

curl -X POST https://{ihre-subdomain}.packagehunter.de/api/v1/trackings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackings": [
      {
        "carrier": "DHL",
        "trackingNumber": "00340400000000000001",
        "deliveryNoteNumber": "LS-2024-001",
        "orderNumber": "ORD-2024-001",
        "orderDate": "2024-12-20",
        "customIdentifier": "SHIP-2024-001",
        "totalPrice": 74.98,
        "shippingDate": "2024-12-20",
        "estimatedDeliveryDate": "2024-12-23",
        "weight": 2.5,
        "bulkyGood": false,
        "dangerousGood": false,
        "items": [
          {
            "articleNumber": "ART-12345",
            "quantity": 2,
            "unitPrice": 29.99,
            "description": "Wireless Bluetooth Headphones"
          },
          {
            "articleNumber": "ART-67890",
            "quantity": 1,
            "unitPrice": 15.00,
            "description": "USB-C Charging Cable"
          }
        ],
        "shippingAddress": {
          "name": "Max Mustermann",
          "customerNumber": "CUST-001",
          "email": "max@example.com",
          "street": "Musterstraße 123",
          "company": "Musterfirma GmbH",
          "additionalAddress": "c/o Müller, 2. OG",
          "zipCode": "46244",
          "city": "Bottrop",
          "countryIsoCode": "DE"
        }
      }
    ]
  }'

Mehrere Sendungen in einem Request

curl -X POST https://{ihre-subdomain}.packagehunter.de/api/v1/trackings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackings": [
      {
        "carrier": "DHL",
        "trackingNumber": "00340400000000000001",
        "deliveryNoteNumber": "LS-2024-001",
        "shippingDate": "2024-12-20",
        "items": [{"articleNumber": "ART-001", "quantity": 1}],
        "shippingAddress": {"zipCode": "46244", "city": "Bottrop", "countryIsoCode": "DE"}
      },
      {
        "carrier": "DPD",
        "trackingNumber": "00340434161094015002",
        "deliveryNoteNumber": "LS-2024-002",
        "shippingDate": "2024-12-21",
        "items": [{"articleNumber": "ART-002", "quantity": 3}],
        "shippingAddress": {"zipCode": "10115", "city": "Berlin", "countryIsoCode": "DE"}
      }
    ]
  }'

Benötigen Sie Hilfe bei der Integration?

Kontaktieren Sie uns Hilfe & FAQ