InPost integration (Paczkomaty)

El módulo InPost integra WooCommerce con la API ShipX. Genere etiquetas, permita que los clientes elijan un Paczkomat en el mapa y haga seguimiento de los envíos desde el panel de administración.

Configuración

Vaya a WooCommerce > Ajustes > Polski PRO > InPost.

Autenticación de la API

Ajuste	Descripción
Token de API	Token de autorización del panel de InPost Manager
ID de organización	Identificador de la organización en el sistema de InPost
Modo sandbox	Usa el entorno de pruebas de la API ShipX

El token de API se envía en la cabecera Authorization: Bearer {token} con cada solicitud a la API ShipX. El token debe tener permisos para crear envíos y generar etiquetas.

Ajustes del método de envío

Después de configurar la API, cree un nuevo método de envío:

Vaya a WooCommerce > Ajustes > Envío > Zonas de envío
Edite la zona “Polonia”
Haga clic en “Añadir método de envío”
Seleccione “InPost Paczkomat” o “InPost Mensajería”

Ajuste del método	Valor predeterminado	Descripción
Título del método	”InPost Paczkomat”	Nombre mostrado al cliente
Coste	0	Coste de envío (0 = gratis)
Envío gratis a partir de	""	Importe del pedido a partir del cual el envío es gratis
Tamaño de paquete predeterminado	A	Tamaño: `A`, `B`, `C`
Seguro	No	Añadir seguro al envío

Mapa de puntos de recogida

En la página de pago, tras seleccionar el método de envío “InPost Paczkomat”, se muestra un widget de mapa interactivo que permite al cliente seleccionar un Paczkomat.

El widget ofrece:

Mapa con marcadores de Paczkomaty
Búsqueda por ciudad - escriba el nombre de una ciudad para centrar el mapa
Búsqueda por coordenadas - geolocalización automática (con el consentimiento del usuario)
Búsqueda por código postal - encontrar los Paczkomaty más cercanos
Lista de Paczkomaty - ordenada del más cercano
Detalles del punto - dirección, horario de apertura, tamaños de casilleros disponibles

Búsqueda por ciudad

El widget envía una solicitud al endpoint de la API ShipX:

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

Los resultados se almacenan en caché durante 24 horas en transients de WordPress para minimizar el número de solicitudes a la API.

Búsqueda por coordenadas

Cuando el cliente consiente la geolocalización:

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

Filtrado de puntos

/**
 * 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;

Ejemplo - excluir puntos temporalmente no disponibles:

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

Generación de etiquetas

Desde el panel del pedido

En la página de edición del pedido, el panel InPost ofrece las siguientes opciones:

Generar etiqueta - crea un envío en la API ShipX y genera una etiqueta PDF
Descargar etiqueta - descarga la etiqueta generada
Imprimir etiqueta - abre una vista previa de impresión

Generación masiva

En la lista de pedidos, seleccione varios pedidos y elija la acción masiva “Generar etiquetas InPost”. Las etiquetas se generan de forma asíncrona - al finalizar aparece una notificación con un enlace para descargar el archivo ZIP.

Datos del envío

La etiqueta se genera a partir de:

Campo	Origen	Descripción
Remitente	Ajustes de la tienda	Dirección y datos de la empresa de WooCommerce
Destinatario	Datos del pedido	Nombre, apellidos, teléfono, correo electrónico
Punto de recogida	Selección del cliente	ID del Paczkomat seleccionado en el pago
Tamaño del paquete	Ajuste del método	O anulación en el pedido
Importe contra reembolso	Pedido contra reembolso	Solo para pedidos contra reembolso

Hook de generación de etiquetas

/**
 * 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;

Ejemplo - añadir una referencia del pedido:

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

Seguimiento de envíos

Seguimiento automático

Tras generar una etiqueta, el módulo comprueba automáticamente el estado del envío cada 2 horas (WP-Cron). Los estados se asignan a los estados de pedido de WooCommerce:

Estado de InPost	Estado de WooCommerce	Descripción
`created`	`processing`	Envío creado
`dispatched_by_sender`	`processing`	Enviado por el remitente
`collected_from_sender`	`shipped`	Recogido del remitente
`out_for_delivery`	`shipped`	En reparto
`ready_to_pickup`	`shipped`	Listo para recoger en el Paczkomat
`delivered`	`completed`	Entregado / recogido

Notificaciones al cliente

El cliente recibe un correo electrónico con un enlace de seguimiento a la página de seguimiento de InPost. El enlace de seguimiento se añade a:

El correo electrónico “Pedido en proceso”
La página “Mi cuenta > Pedidos > Detalles”
Las notas del pedido (visibles para el cliente)

Hook de seguimiento

/**
 * 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);

Ejemplo - notificación por SMS sobre la disponibilidad para recogida:

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

Tamaños de paquete

Tamaño	Dimensiones (cm)	Peso máx.
A	8 x 38 x 64	25 kg
B	19 x 38 x 64	25 kg
C	41 x 38 x 64	25 kg

El tamaño del paquete se puede establecer globalmente, por método de envío o anular manualmente en el pedido.

Resolución de problemas

El mapa de Paczkomaty no carga Compruebe que el token de API sea válido y esté activo. Revise la consola del navegador en busca de errores de CORS o JavaScript. Asegúrese de que el script polski-pro-inpost-map.js esté cargado.

Error de generación de etiqueta “Unauthorized” El token de API ha caducado o no tiene permisos para crear envíos. Genere un nuevo token en el panel de InPost Manager.

El estado del envío no se actualiza Compruebe que WP-Cron funcione correctamente. Ejecute manualmente: wp cron event run polski_pro_inpost_tracking.

Próximos pasos

Notificar problemas: GitHub Issues
Documentación de la API ShipX: https://docs.inpost24.com/

Esta página tiene únicamente carácter informativo y no constituye asesoramiento legal. Consulte con un abogado antes de la implementación. Polski for WooCommerce es software de código abierto (GPLv2) que se proporciona sin garantía.