KSeF integration

El módulo KSeF envía facturas electrónicas al Sistema Nacional de Factura Electrónica (Ministerio de Hacienda). Las facturas se envían en segundo plano, con reintentos automáticos en caso de errores.

Qué es KSeF

El Sistema Nacional de Factura Electrónica (KSeF) es una plataforma del Ministerio de Hacienda para emitir, almacenar y recibir facturas estructuradas en formato XML. El plugin proporciona herramientas para integrar WooCommerce con KSeF - genera facturas en el formato XML requerido y las envía al sistema.

Configuración

Vaya a WooCommerce > Ajustes > Polski > Módulos PRO > KSeF.

Ajustes de conexión

Ajuste	Descripción
Activar la integración con KSeF	Activa el módulo
Entorno	De pruebas (sandbox) o de producción
Clave de API (token)	Token de autorización generado en el portal de KSeF
NIF del emisor (NIP)	NIF asociado a la cuenta de KSeF

Entorno de pruebas

KSeF ofrece un entorno de pruebas (sandbox) para verificar la integración. El entorno de pruebas:

• no requiere una clave de autorización real
• acepta facturas en el mismo formato que el entorno de producción
• no transmite datos a la Agencia Tributaria
• se recomienda para las primeras pruebas de integración

Tras una verificación satisfactoria en el entorno de pruebas, cambie al entorno de producción e introduzca la clave de API correcta.

Obtención del token de API

1. Inicie sesión en el portal de KSeF: https://ksef.mf.gov.pl/
2. Vaya a la sección de gestión de tokens
3. Genere un nuevo token con permisos para emitir facturas
4. Copie el token y péguelo en los ajustes del plugin

Envío de facturas

Envío automático

Tras activar la opción Envío automático a KSeF, el plugin envía la factura a KSeF automáticamente cuando su estado cambia a “Emitida”. El envío se gestiona de forma asíncrona a través de Action Scheduler.

Envío manual

En el panel del pedido, la meta box “Facturas” contiene un botón Enviar a KSeF. Al hacer clic en él, se añade una tarea de envío a la cola de Action Scheduler.

Procesamiento asíncrono

El plugin utiliza Action Scheduler (integrado en WooCommerce) para el envío asíncrono de facturas. Esto significa que:

• el envío no bloquea el procesamiento del pedido
• las facturas se envían en una cola, una tras otra
• cuando hay un gran número de facturas, el sistema las procesa de forma gradual

Generación de XML

El plugin genera facturas en formato XML conforme al esquema de KSeF (FA(2)). El documento XML contiene:

• encabezado con la fecha y el tipo de factura
• datos del vendedor (NIF, nombre, dirección)
• datos del comprador (NIF, nombre, dirección)
• líneas de la factura (nombre, cantidad, precio neto, tipo de IVA, valor)
• resumen con el desglose por tipos de IVA
• información de pago

El XML se valida antes del envío. Si la validación detecta errores, la factura no se enviará y aparecerá un mensaje detallado en el registro.

Seguimiento de estados

Tras enviar una factura a KSeF, el plugin realiza el seguimiento de su estado:

Estado	Descripción
Queued	Factura añadida a la cola de envío
Submitted	Factura enviada a KSeF, a la espera de procesamiento
Accepted	Factura aceptada por KSeF, número de KSeF asignado
Rejected	Factura rechazada - compruebe el mensaje de error
Error	Error de comunicación con la API de KSeF

Una vez aceptada la factura, el plugin guarda el número de referencia de KSeF en los metadatos de la factura. Este número es visible en el panel del pedido y en la impresión en PDF.

Sondeo de estado

El plugin comprueba automáticamente el estado de las facturas enviadas. Tras enviar una factura a KSeF, el plugin consulta el estado a la API cada pocos minutos (a través de Action Scheduler) hasta que recibe una respuesta “Accepted” o “Rejected”.

Gestión de errores y reintentos

En caso de un error de comunicación con la API de KSeF, el plugin aplica un mecanismo de retroceso exponencial (exponential backoff):

Intento	Retraso
1.er reintento	5 minutos
2.º reintento	25 minutos
3.er reintento	125 minutos

Tras tres intentos fallidos, la factura recibe el estado “Error” y requiere intervención manual. El administrador recibe una notificación por correo electrónico sobre el envío fallido.

Causas típicas de errores:

• token de API no válido o caducado
• errores de validación del XML (p. ej. datos del comprador faltantes)
• indisponibilidad temporal de la API de KSeF
• discrepancia entre el NIF del emisor y el token

Hooks

polski_pro_ksef_submit

Acción que se dispara antes de enviar una factura a KSeF.

/**
 * @param int    $invoice_id ID faktury
 * @param string $xml        Wygenerowany XML faktury
 */
do_action('polski_pro_ksef_submit', int $invoice_id, string $xml);

Ejemplo:

add_action('polski_pro_ksef_submit', function (int $invoice_id, string $xml): void {
    // Zapisanie kopii XML przed wysyłką
    $upload_dir = wp_upload_dir();
    $xml_path = $upload_dir['basedir'] . '/polski-pro/ksef-xml/';

    if (! is_dir($xml_path)) {
        wp_mkdir_p($xml_path);
    }

    file_put_contents(
        $xml_path . "invoice-{$invoice_id}.xml",
        $xml
    );
}, 10, 2);

polski_pro_ksef_check_status

Acción que se dispara tras comprobar el estado de una factura en KSeF.

/**
 * @param int    $invoice_id    ID faktury
 * @param string $status        Nowy status (accepted, rejected, error)
 * @param string $ksef_number   Numer referencyjny KSeF (tylko dla accepted)
 */
do_action('polski_pro_ksef_check_status', int $invoice_id, string $status, string $ksef_number);

Ejemplo:

add_action('polski_pro_ksef_check_status', function (int $invoice_id, string $status, string $ksef_number): void {
    if ($status === 'accepted') {
        // Powiadomienie zewnętrznego systemu o zaakceptowaniu faktury
        wp_remote_post('https://erp.example.com/api/ksef-update', [
            'body' => wp_json_encode([
                'invoice_id'  => $invoice_id,
                'ksef_number' => $ksef_number,
            ]),
            'headers' => ['Content-Type' => 'application/json'],
        ]);
    }
}, 10, 3);

Diagnóstico

Registros

El plugin registra todas las operaciones de KSeF en el registro de WooCommerce. Vaya a WooCommerce > Estado > Registros y seleccione la fuente polski-pro-ksef.

Eventos registrados:

• envío de facturas (solicitud/respuesta)
• comprobación de estado
• errores de validación del XML
• errores de comunicación con la API
• reintentos de envío

Prueba de la conexión

En los ajustes del módulo KSeF hay disponible un botón Probar conexión. Envía una solicitud de prueba a la API de KSeF y verifica:

• la validez del token
• la conectividad con el servidor de KSeF
• la coincidencia del NIF con el token

Problemas frecuentes

Factura rechazada por KSeF

1. Compruebe el mensaje de error en el registro de WooCommerce
2. Causas más frecuentes: NIF del comprador faltante, tipo de IVA no válido, datos de dirección incompletos
3. Corrija los datos y vuelva a enviar

El token de API no funciona

1. Asegúrese de que el token no haya caducado
2. Compruebe si el token tiene permisos para emitir facturas
3. Verifique que el NIF en los ajustes del plugin coincida con el asociado al token

Action Scheduler no procesa la cola

1. Compruebe si WP-Cron funciona correctamente
2. Vaya a Herramientas > Scheduled Actions y compruebe el estado de la cola
3. Verifique que no haya tareas bloqueadas

Recursos relacionados

• Sistema de facturas
• Información sobre KSeF
• Informar de un problema

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