Pigee Shipping Partner API

Schnellstart

Von der Kontoerstellung bis zu Ihrer ersten Live-Sendung in weniger als einer Stunde. Folgen Sie diesen fünf Schritten:

1. Erstellen Sie ein kostenloses Pigee-Konto unter account.pigeepost.com und wählen Versandpartner als Kontotyp.
2. Gehen Sie zu Dashboard → Developer → API-Schlüssel und generieren Sie einen Live-Schlüssel und einen Test-Schlüssel.
3. Wählen Sie Ihren Zahlungsmodus: Pigee Pay oder Pigee Account Balance.
4. Konfigurieren Sie Ihre Servicegebühr in Dashboard → Gebühren.
5. Importieren Sie die Postman-Sammlung für Staging-Entwicklung.

Authentifizierung

Jede Anfrage muss Ihren API-Schlüssel im Authorization Header als Bearer Tokenenthalten. Schlüssel sind auf Ihr Partnerkonto begrenzt und beinhalten Ihre Gebührenkonfiguration und Ihren Zahlungsmodus.

Authorization: Bearer pgk_live_YOUR_API_KEY_HERE

Schlüsseltypen

Umgebungen & Basis-URLs

Die Sandbox ist ein vollständiger 1:1-Spiegel der Produktion. Wechseln Sie zwischen Umgebungen durch Austausch Ihres Schlüsselpräfix oder verwenden Sie die explizite Sandbox-URL für Klarheit.

SDKs & Bibliotheken

Offizielle SDKs wrappen die REST-API mit typisierten Modellen, automatischen Wiederholungen und Sandbox-Helfern.

API-Schlüssel validieren

Rufen Sie diesen Endpunkt auf, um zu bestätigen, dass Ihr API-Schlüssel aktiv ist und richtig konfiguriert ist, bevor Sie live gehen.

POST /api/v1/store/valid
Authorization: Bearer pgk_live_…
Content-Type: application/json

{
  "store_type": 2,
  "api_key": "pgk_live_YOUR_KEY"
}

{
  "valid": true,
  "account": {
    "id": "acc_7H4K",
    "type": "shipping_partner",
    "payment_mode": "pigee_pay",
    "service_fee_pct": 8.5,
    "balance_gbp": 240.00
  }
}

Versandraten abrufen

Aktuelle Kuriere Tarife für eine Sendung abrufen. Gibt alle verfügbaren Services sortiert nach Preis zurück, einschließlich Transportzeit, Versicherungswertunterstützung und Endkosten.

{
  "shop_url": "https://your-store.com",
  "currency": "GBP",
  "parcel": {
    "type": "Box",
    "boxsize": 4
  },
  "weight": { "value": 4, "units": "kg" },
  "dimension": {
    "length": 40,
    "width": 30,
    "height": 20,
    "units": "cms"
  },
  "address": {
    "pickup": {
      "address_line1": "10 High Street",
      "town": "London",
      "post_code": "SW1A 1AA",
      "country": "United Kingdom"
    },
    "destination": {
      "address_line1": "123 Ocean Drive",
      "town": "Miami",
      "post_code": "33101",
      "country": "United States"
    }
  }
}

{
  "rates": [
    {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE",
      "method_title": "DHL Express Worldwide",
      "price": 125.50,
      "currency": "GBP",
      "transit_days": 2,
      "insurance_available": true,
      "customs_included": true
    }
  ],
  "currency": "GBP",
  "request_id": "req_7H4K2026"
}

Anfrageparameter

Bestellung erstellen

Eine Pigee-Bestellung mit einem carrier_request_id vom Rates-Endpoint. Pigee generiert das Versandetikett, die Handelsrechnung und bei Verwendung von Pigee Pay einen gehosteten Zahlungslink.

{
  "order_from": "api",
  "shop_url": "https://your-store.com",
  "order_id": "ORDER-10001",
  "currency": "GBP",
  "items": [
    {
      "name": "Vintage leather jacket",
      "quantity": 1,
      "value": 600.00,
      "currency": "GBP",
      "hs_code": "4203100090"
    }
  ],
  "shippingData": {
    "method_title": "DHL Express Worldwide",
    "cost": 125.50,
    "currency": "GBP",
    "meta_data": {
      "carrier_request_id": "cr_abc123",
      "carrier_id": "dhl",
      "pigee_carrier_id": "DHL_EXPRESS_WORLDWIDE"
    }
  }
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "pending_payment",
  "payment_url": "https://pay.pigee.com/c/abc123",
  "label_url": null,
  "tracking_number": null
}

Bestellung erfüllen

Senden Sie die endgültigen Erfüllungsdetails nach Zahlungsbestätigung. Pigee generiert das Versandetikett, bucht den Spediteur und gibt eine Trackingnummer zurück.

{
  "order_id": "po_78910",
  "status": "processing",
  "shop_id": "https://your-store.com",
  "currency": "GBP",
  "total": 725.50,
  "shipping_total": 125.50
}

{
  "order_id": "po_78910",
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "status": "booked",
  "label_url": "https://labels.pigeepost.com/PGE-7H4K-2026-0042.pdf",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "estimated_delivery": "2026-05-08"
}

Verfolgung

Rufen Sie Live-Trackingereignisse für jede über die API erstellte Sendung ab.

{
  "pigee_order_id": "PGE-7H4K-2026-0042",
  "tracking_number": "1234567890",
  "carrier": "DHL",
  "status": "in_transit",
  "estimated_delivery": "2026-05-08",
  "events": [
    {
      "timestamp": "2026-05-06T08:14:00Z",
      "status": "in_transit",
      "location": "DHL Hub, Leipzig",
      "description": "Shipment in transit"
    }
  ]
}

Zahlungsmodi

Pigee unterstützt zwei Zahlungsarten. Die aktive Zahlungsart wird in Ihrem Partner-Dashboard festgelegt und gilt für alle Bestellungen.

Servicegebühren

Als Versandpartner können Sie eine eigene Gebühr auf die Basistarife von Pigee aufschlagen. Gebühren werden in Ihrem Dashboard konfiguriert und vor der Tarifabfrage automatisch angewendet.

• Prozentuale Gebühr: Wird als Prozentsatz der Basistarifen des Spediteurs berechnet.
• Pauschale Gebühr: Ein Pauschalbetrag, der pro Sendung hinzugefügt wird.
• Übersteuerungen pro Strecke: Überschreiben Sie die globale Gebühr für bestimmte Versand-/Lieferpaarungen.

Abrechnungen & Wechselkurs

Pigee Pay nimmt von Endbenutzern in 135+ Währungen an und zahlt auf Ihr Bankkonto in Ihrer Landeswährung aus.

• Der Auszahlungszyklus beträgt normalerweise T+2 Geschäftstage nach Bestätigung der Sendungslieferung.
• Heben Sie Ihr Pigee-Guthaben über das Dashboard ab.
• Detaillierte Transaktionsprotokolle sind verfügbar unter Finanzen → Abrechnungen.
• Rechnungen für abgerechnete Transaktionen werden automatisch erstellt und sind als PDF verfügbar.

Webhooks

Pigee sendet Echtzeitevents als JSON an Ihren HTTPS-Endpoint POST Anfragen. Konfigurieren Sie Ihre Webhook-URL unter Dashboard → Entwickler → Webhooks.

{
  "event": "parcel.delivered",
  "created_at": "2026-05-08T14:22:07Z",
  "api_version": "v1",
  "data": {
    "pigee_order_id": "PGE-7H4K-2026-0042",
    "order_id": "ORDER-10001",
    "carrier": "DHL",
    "tracking_number": "1234567890",
    "delivered_at": "2026-05-08T14:18:00Z"
  }
}

Webhook-Event-Referenz

Webhook-Signaturen

Jede Webhook-Anfrage enthält einen X-Pigee-Signature Header, einen HMAC-SHA256-Digest des rohen Request-Body. Überprüfen Sie diesen immer vor der Verarbeitung.

// Node.js
const crypto = require('crypto');

function verifyPigeeWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Fehler

Alle Fehler geben JSON mit einem error Objekt zurück, das einen maschinenlesbaren code und einen benutzerfreundlichen message.

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your Pigee partner balance is not sufficient to create this shipment.",
    "request_id": "req_7H4K2026"
  }
}

Rate Limits

Anfragenlimits werden pro API-Schlüssel angewendet und skalieren mit Ihrem Kontotyp.

Wenn ein Anfragelimit erreicht wird, gibt die API zurück HTTP 429 mit einem Retry-After Header.

Datentypen und Konventionen

• Datumsangaben und Zeiten - ISO 8601 UTC, z. B. 2026-05-06T14:22:07Z
• Währungen - ISO 4217 dreistellige Codes, z. B. GBP, USD, NGN
• Geldbeträge - number mit zwei Dezimalstellen, immer kombiniert mit einem currency Feld
• Ländernamen - Englische Vollnamen, z. B. "United Kingdom", "United States"
• Telefonnummern - E.164-Format empfohlen, z. B. +447700900123
• Gewichte - kg oder lbs je nach Anfrage angegeben
• IDs - Von Pigee generierte IDs verwenden Präfixformat, z. B. po_78910, cr_abc123

Referenz der Spediteur-IDs

Verwendung pigee_carrier_id Werte aus der Ratenabfrage beim Erstellen von Aufträgen.

Changelog

v1.3 - Mai 2026

• Hinzugefügt insurance_available und customs_included Flags-zu-Sätze-Antwort.
• Webhook-Signaturverifizierung verwendet jetzt HMAC-SHA256.
• Neuer Fehlercode RATE_EXPIRED.
• Tracking-Endpoint hinzugefügt: GET /api/v1/tracking/{pigee_order_id}.

v1.2 - Februar 2026

• Gebührenschlüsselungs-Außerkraftsetzungen im Dashboard hinzugefügt.
• Pigee Pay-Zahlungslinks enthalten jetzt einen expires_at Feld.
• Neue Webhook-Ereignisse für Zoll und Abrechnungen hinzugefügt.

v1.1 - Oktober 2025

• Erste Postman-Collection veröffentlicht.
• Sandbox-Umgebung gestartet.
• Kontostand-Zahlungsmodus veröffentlicht.

v1.0 - Juni 2025

• Erste öffentliche Version: Validieren, Sätze abrufen, Bestellung erstellen, Bestellung erfüllen.