InPost integration (Paczkomaty)

Das InPost-Modul integriert WooCommerce mit der ShipX API. Erstellen Sie Etiketten, lassen Sie Kunden einen Paczkomat auf der Karte auswählen und verfolgen Sie Sendungen aus dem Adminbereich.

Konfiguration

Gehen Sie zu WooCommerce > Einstellungen > Polski PRO > InPost.

API-Authentifizierung

Einstellung	Beschreibung
API-Token	Autorisierungstoken aus dem InPost Manager Panel
Organisations-ID	Kennung der Organisation im InPost-System
Sandbox-Modus	Verwendet die Testumgebung der ShipX API

Das API-Token wird bei jeder ShipX-API-Anfrage im Header Authorization: Bearer {token} übergeben. Das Token sollte über Berechtigungen zum Erstellen von Sendungen und Generieren von Etiketten verfügen.

Einstellungen der Versandmethode

Erstellen Sie nach der Konfiguration der API eine neue Versandmethode:

Gehen Sie zu WooCommerce > Einstellungen > Versand > Versandzonen
Bearbeiten Sie die Zone “Polen”
Klicken Sie auf “Versandmethode hinzufügen”
Wählen Sie “InPost Paczkomat” oder “InPost Kurier”

Methoden-Einstellung	Standardwert	Beschreibung
Methodentitel	”InPost Paczkomat”	Dem Kunden angezeigter Name
Kosten	0	Versandkosten (0 = kostenlos)
Kostenloser Versand ab	""	Bestellbetrag, ab dem der Versand kostenlos ist
Standard-Paketgröße	A	Größe: `A`, `B`, `C`
Versicherung	Nein	Versicherung zur Sendung hinzufügen

Karte der Abholpunkte

Auf der Kassenseite wird nach der Auswahl der Versandmethode “InPost Paczkomat” ein interaktives Karten-Widget angezeigt, mit dem der Kunde einen Paczkomat auswählen kann.

Das Widget bietet:

Karte mit Paczkomat-Markierungen
Städtesuche - geben Sie einen Städtenamen ein, um die Karte zu zentrieren
Koordinatensuche - automatische Geolokalisierung (mit Zustimmung des Nutzers)
Postleitzahlensuche - die nächstgelegenen Paczkomaty finden
Paczkomat-Liste - sortiert vom nächstgelegenen
Punktdetails - Adresse, Öffnungszeiten, verfügbare Fachgrößen

Städtesuche

Das Widget sendet eine Anfrage an den ShipX-API-Endpunkt:

GET /v1/points?type=parcel_locker&city={city}&per_page=25

Die Ergebnisse werden 24 Stunden lang in WordPress-Transients zwischengespeichert, um die Anzahl der API-Anfragen zu minimieren.

Koordinatensuche

Wenn der Kunde der Geolokalisierung zustimmt:

GET /v1/points?type=parcel_locker&relative_point={lat},{lng}&per_page=10

Filtern von Punkten

/**
 * Filtruje listę punktów odbioru InPost.
 *
 * @param array  $points  Tablica punktów odbioru z API
 * @param string $city    Wyszukiwane miasto
 * @param array  $coords  Współrzędne [lat, lng] lub pusta tablica
 */
apply_filters('polski_pro/inpost/points', array $points, string $city, array $coords): array;

Beispiel - Ausschluss vorübergehend nicht verfügbarer Punkte:

add_filter('polski_pro/inpost/points', function (array $points, string $city, array $coords): array {
    $excluded_points = ['KRA123', 'WAW456']; // Tymczasowo wyłączone
    return array_filter($points, function (array $point) use ($excluded_points): bool {
        return ! in_array($point['name'], $excluded_points, true);
    });
}, 10, 3);

Etikettenerstellung

Aus dem Bestellbereich

Auf der Bestellbearbeitungsseite bietet das Panel InPost die folgenden Optionen:

Etikett generieren - erstellt eine Sendung in der ShipX API und generiert ein PDF-Etikett
Etikett herunterladen - lädt das generierte Etikett herunter
Etikett drucken - öffnet eine Druckvorschau

Massenerstellung

Wählen Sie in der Bestellliste mehrere Bestellungen aus und wählen Sie die Massenaktion “InPost-Etiketten generieren”. Die Etiketten werden asynchron generiert - nach Abschluss erscheint eine Benachrichtigung mit einem Link zum Herunterladen der ZIP-Datei.

Sendungsdaten

Das Etikett wird auf Grundlage der folgenden Daten generiert:

Feld	Quelle	Beschreibung
Absender	Shop-Einstellungen	Adress- und Firmendaten aus WooCommerce
Empfänger	Bestelldaten	Vorname, Nachname, Telefon, E-Mail
Abholpunkt	Kundenauswahl	An der Kasse ausgewählte Paczkomat-ID
Paketgröße	Methoden-Einstellung	Oder Überschreibung in der Bestellung
Nachnahmebetrag	Nachnahmebestellung	Nur für Bestellungen per Nachnahme

Hook für die Etikettenerstellung

/**
 * Filtruje dane przesyłki przed wysłaniem do API ShipX.
 *
 * @param array     $shipment_data Dane przesyłki
 * @param \WC_Order $order         Zamówienie WooCommerce
 */
apply_filters('polski_pro/inpost/shipment_data', array $shipment_data, \WC_Order $order): array;

Beispiel - Hinzufügen einer Bestellreferenz:

add_filter('polski_pro/inpost/shipment_data', function (array $shipment_data, \WC_Order $order): array {
    $shipment_data['reference'] = sprintf('ORDER-%s', $order->get_order_number());
    return $shipment_data;
}, 10, 2);

Sendungsverfolgung

Automatische Verfolgung

Nach der Erstellung eines Etiketts prüft das Modul den Sendungsstatus automatisch alle 2 Stunden (WP-Cron). Die Status werden den WooCommerce-Bestellstatus zugeordnet:

InPost-Status	WooCommerce-Status	Beschreibung
`created`	`processing`	Sendung erstellt
`dispatched_by_sender`	`processing`	Vom Absender versandt
`collected_from_sender`	`shipped`	Beim Absender abgeholt
`out_for_delivery`	`shipped`	In Zustellung
`ready_to_pickup`	`shipped`	Zur Abholung im Paczkomat bereit
`delivered`	`completed`	Zugestellt / abgeholt

Kundenbenachrichtigungen

Der Kunde erhält eine E-Mail mit einem Tracking-Link zur InPost-Verfolgungsseite. Der Tracking-Link wird hinzugefügt zu:

E-Mail “Bestellung in Bearbeitung”
Seite “Mein Konto > Bestellungen > Details”
Bestellnotizen (für den Kunden sichtbar)

Hook für die Verfolgung

/**
 * Akcja wywoływana po aktualizacji statusu przesyłki.
 *
 * @param int      $order_id      ID zamówienia
 * @param string   $tracking_number Numer śledzenia
 * @param string   $old_status    Poprzedni status InPost
 * @param string   $new_status    Nowy status InPost
 */
do_action('polski_pro/inpost/status_updated', int $order_id, string $tracking_number, string $old_status, string $new_status);

Beispiel - SMS-Benachrichtigung über die Abholbereitschaft:

add_action('polski_pro/inpost/status_updated', function (
    int $order_id,
    string $tracking_number,
    string $old_status,
    string $new_status
): void {
    if ($new_status === 'ready_to_pickup') {
        $order = wc_get_order($order_id);
        $phone = $order->get_billing_phone();
        send_sms($phone, sprintf(
            'Twoja paczka %s czeka w Paczkomacie. Kod odbioru w e-mailu.',
            $tracking_number
        ));
    }
}, 10, 4);

Paketgrößen

Größe	Abmessungen (cm)	Max. Gewicht
A	8 x 38 x 64	25 kg
B	19 x 38 x 64	25 kg
C	41 x 38 x 64	25 kg

Die Paketgröße kann global, pro Versandmethode oder manuell in der Bestellung überschrieben werden.

Fehlerbehebung

Die Paczkomat-Karte lädt nicht Prüfen Sie, ob das API-Token gültig und aktiv ist. Prüfen Sie die Browser-Konsole auf CORS- oder JavaScript-Fehler. Stellen Sie sicher, dass das Skript polski-pro-inpost-map.js geladen wird.

Fehler bei der Etikettenerstellung “Unauthorized” Das API-Token ist abgelaufen oder verfügt nicht über Berechtigungen zum Erstellen von Sendungen. Generieren Sie ein neues Token im InPost Manager Panel.

Der Sendungsstatus wird nicht aktualisiert Prüfen Sie, ob WP-Cron ordnungsgemäß funktioniert. Manuell ausführen: wp cron event run polski_pro_inpost_tracking.

Nächste Schritte

Probleme melden: GitHub Issues
ShipX-API-Dokumentation: https://docs.inpost24.com/

Diese Seite dient ausschließlich zu Informationszwecken und stellt keine Rechtsberatung dar. Konsultieren Sie vor der Umsetzung einen Anwalt. Polski for WooCommerce ist Open-Source-Software (GPLv2), die ohne Gewährleistung bereitgestellt wird.