Integración con KSeF
El módulo KSeF guarda los ajustes de conexión con el Sistema Nacional de Factura Electrónica. Hoy no puede enviar ninguna factura, ni a producción ni a un entorno de pruebas. El cliente de la API del plugin está escrito contra KSeF 1.0, una versión del sistema que el Ministerio de Hacienda ya apagó, y los servidores a los que apunta han dejado de existir. Esta página describe lo que el plugin hace realmente hoy.
Qué es KSeF
Section titled “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. Los vendedores polacos presentan allí sus facturas estructuradas en lugar de intercambiar documentos PDF. Desde el 1 de febrero de 2026, KSeF 2.0 es el único sistema en funcionamiento y su uso es obligatorio.
Por qué el envío no funciona
Section titled “Por qué el envío no funciona”El cliente de la API del plugin conoce exactamente dos servidores, https://ksef-test.mf.gov.pl/api y https://ksef.mf.gov.pl/api, y un único endpoint de sesión, /online/Session/InitSigned. Esa es la forma de KSeF 1.0. Lo que ocurrió con esa versión:
- el 1 de septiembre de 2025 el Ministerio desactivó el entorno de PRUEBAS de KSeF 1.0
- el 1 de febrero de 2026 se detuvo la PRODUCCIÓN de KSeF 1.0 y se apagó de forma permanente, junto con el antiguo Módulo de Certificados y Autorizaciones
- desde esa misma fecha, KSeF 2.0 es el único sistema y es obligatorio
En consecuencia, cualquier intento de envío falla en la capa de red, antes de que se pueda hablar de credenciales, esquemas o estados. No existe ningún ajuste, ninguna casilla y ningún token que lo arregle. Tampoco hay un entorno de pruebas alcanzable: el servidor de pruebas al que apunta el cliente también fue retirado.
La ruta POST /wp-json/polski-pro/v1/invoices/{id}/ksef sigue existiendo, exige la capacidad manage_woocommerce y encola una tarea en segundo plano mediante Action Scheduler. Esa tarea ya no llega a ninguna parte. Ninguna pantalla del escritorio, botón, acción masiva, cambio de estado del pedido ni tarea programada la llama, y llamarla a mano tampoco cambia el resultado.
KSeF 2.0 es un sistema distinto en todos los puntos que importan aquí. Según la especificación OpenAPI publicada en https://api-test.ksef.mf.gov.pl/docs/v2/openapi.json:
- otra base:
https://api-test.ksef.mf.gov.pl/v2para pruebas yhttps://api.ksef.mf.gov.pl/v2para producción - otra autenticación:
POST /auth/challenge, despuésPOST /auth/ksef-tokencon el token de KSeF cifrado junto con la marca de tiempo del desafío, y por últimoPOST /auth/token/redeempara obtener un token de acceso. Nada de esto se parece aInitSigned - otro envío: se abre una sesión con
POST /sessions/onlineentregando una clave AES-256 cifrada con la clave pública del Ministerio, y la factura se envía ya cifrada aPOST /sessions/online/{referenceNumber}/invoices, acompañada de los hashes SHA-256 del documento en claro y del documento cifrado
Está previsto reescribir el módulo contra KSeF 2.0. No damos fecha.
Qué hace esta versión
Section titled “Qué hace esta versión”| Funcionalidad | Estado |
|---|---|
| Ajustes de conexión con KSeF y almacenamiento de credenciales | Disponible |
| Marcado de pedidos con requisito de KSeF (plugin FREE) | Disponible |
| Envío de facturas a KSeF, en cualquier entorno | Imposible: el cliente está escrito contra KSeF 1.0, que ya no existe |
| Un botón, acción masiva o tarea programada que envíe | No en esta versión |
| Estados y números de referencia devueltos por el Ministerio | No disponibles |
| Descarga del XML del esquema FA desde el escritorio | No en esta versión |
| Descarga de la factura en UBL / PEPPOL | Disponible, sin relación con KSeF |
| Informe JPK_FA | Disponible, sin relación con KSeF |
Considere este módulo un lugar donde dejar preparadas las credenciales, no un canal para presentar facturas.
Configuración
Section titled “Configuración”No hay ninguna pantalla de ajustes renderizada para los campos de KSeF. Los valores viven en la opción polski_pro_ksef y se escriben a través de la ruta REST de ajustes PRO, igual que las credenciales de los transportistas:
PUT /wp-json/polski-pro/v1/settingsContent-Type: application/jsonX-WP-Nonce: {nonce wp_rest}
{ "ksef": { "enabled": true, "environment": "test", "api_token": "..." }}La ruta exige la capacidad manage_woocommerce. El payload guardado sustituye la opción polski_pro_ksef completa, así que envíe en la misma petición todas las claves que quiera conservar. Guardar estos valores no habilita ningún envío.
Ajustes de conexión
Section titled “Ajustes de conexión”| Clave | Descripción |
|---|---|
enabled | Marca el módulo como activo. No hace alcanzable ningún servidor de KSeF. |
environment | Se guarda como test o production. Ninguno de los dos valores lleva a un sistema en funcionamiento: ambos servidores de KSeF 1.0 fueron apagados. |
api_token | Token de autorización de KSeF. Se guarda, pero no hay hoy ninguna llamada que pueda usarlo. |
auto_send | Se guarda, pero nada lo lee. Activarlo no envía nada. |
El NIF del emisor (NIP) no forma parte de esta opción. Procede de los datos del vendedor en los ajustes de Facturas y se utiliza en las facturas que el plugin ya emite.
Sobre el token de API
Section titled “Sobre el token de API”No hace falta que genere un token para este módulo, porque no hay nada que pueda usarlo. Si ya tiene uno guardado, déjelo o bórrelo, da igual: la autenticación de KSeF 2.0 sigue una secuencia completamente distinta (desafío, token cifrado, canje por un token de acceso) que este plugin todavía no implementa.
Una fecha que conviene tener presente al planificar: los tokens de KSeF dejan de ser un método de autenticación válido el 31 de diciembre de 2026. A partir del 1 de enero de 2027, el certificado de KSeF será la única forma de acceder.
Preparación para KSeF en el plugin FREE
Section titled “Preparación para KSeF en el plugin FREE”El plugin FREE Polski incluye un módulo aparte, Preparación para KSeF, en Polski > Módulos. Nunca se comunica con KSeF, y por eso nada de lo anterior le afecta. Le indica qué pedidos necesitarán una factura estructurada.
Con el módulo activado:
- cada pedido que pasa por la finalización de compra se comprueba en busca del NIP del comprador y el meta del pedido
_polski_ksef_requiredse establece enyesono - aparece una columna KSeF en la lista de pedidos, con un distintivo en los pedidos marcados
- la pantalla del pedido muestra una línea KSeF bajo la dirección de facturación, que lee el meta
_polski_ksef_status, el cual permanece enpendingsalvo que su propio código lo escriba
El único ajuste del módulo, Detectar automáticamente a partir del NIP, controla la detección descrita arriba.
Puntos de extensión
Section titled “Puntos de extensión”polski/ksef/is_required filtra el resultado de la detección antes de guardarlo.
add_filter('polski/ksef/is_required', function (bool $required, WC_Order $order): bool { // No marcar nunca los pedidos por debajo de 100 PLN. if ($order->get_total() < 100) { return false; }
return $required;}, 10, 2);polski/ksef/invoice_ready se dispara con el objeto WC_Order justo después de marcar un pedido como sujeto a facturación en KSeF. Es el hook adecuado si presenta las facturas a través de su propio sistema contable o de un integrador de KSeF 2.0.
Cómo obtener hoy los datos de la factura
Section titled “Cómo obtener hoy los datos de la factura”Estas dos funciones no tocan la API de KSeF y funcionan con normalidad:
- la meta box PEPPOL / UBL (XML) de la pantalla del pedido descarga una factura individual como archivo UBL conforme a EN 16931 / PEPPOL
- la página de administración Informe JPK_FA genera un XML JPK_FA(3) con todas las facturas emitidas en un intervalo de fechas concreto
Ninguna de las dos opciones es una presentación en KSeF, pero ambas cubren el caso habitual de llevar los datos de facturación a un programa de contabilidad o a una herramienta que sí presente en KSeF 2.0. Consulte Exportaciones contables.