Entornos TEST, DEMO y producción de KSeF: una guía segura

KSeF ofrece tres entornos públicos de API, cada uno con una función distinta. TEST es un entorno compartido para integrar con datos sintéticos y simular fallos. DEMO emplea identidades y permisos reales para validar en condiciones similares a producción, pero el contenido de las facturas debe ser ficticio. PRD emite facturas con efectos jurídicos. Una integración segura aísla todas las credenciales y todos los registros, y después hace avanzar una compilación fijada y probada a través de esos límites.

Esta guía se contrastó con la documentación del Ministerio de Finanzas y del CIRF el 28 de agosto de 2026. KSeF despliega los cambios de la API por entorno, así que incluye el registro oficial de cambios y el contrato OpenAPI activo de cada entorno entre las referencias que revisas antes de cada despliegue. Se trata de orientación técnica, no de asesoramiento fiscal ni jurídico.

¿En qué se diferencian TEST, DEMO y PRD de KSeF?

La diferencia no se limita al nombre del host. Cada entorno tiene su propio modelo de confianza, sus reglas para los datos, sus credenciales, su versión de la API y su propia consecuencia cuando un envío se acepta.

Estos límites proceden del material de apoyo para integradores del Ministerio y de la matriz de entornos de KSeF del CIRF. Conviene conocer los alias porque la documentación oficial utiliza ambas denominaciones: TEST también aparece como TE o entorno de integración, mientras que DEMO también se llama TR o preproducción.

Hay una regla que no cambia entre versiones: nunca traslades datos ni credenciales de un entorno a otro. Traslada el código probado y la estructura de configuración, y después aprovisiona por separado el entorno de destino.

¿Cómo se configuran los endpoints de cada entorno de KSeF?

Selecciona un perfil de entorno de una lista cerrada, no una URL arbitraria. Un proceso en producción nunca debería aceptar un host base procedente de un parámetro de la petición, un campo de la factura ni un ajuste modificable de la base de datos.

Un pequeño mapa inmutable hace explícita la elección:

KSEF_ENVIRONMENTS = {
  test: {
    api_base: "https://api-test.ksef.mf.gov.pl/v2",
    docs: "https://api-test.ksef.mf.gov.pl/docs/v2"
  },
  demo: {
    api_base: "https://api-demo.ksef.mf.gov.pl/v2",
    docs: "https://api-demo.ksef.mf.gov.pl/docs/v2"
  },
  production: {
    api_base: "https://api.ksef.mf.gov.pl/v2",
    docs: "https://api.ksef.mf.gov.pl/docs/v2"
  }
}.freeze

profile = KSEF_ENVIRONMENTS.fetch(ENV.fetch("KSEF_ENV").to_sym)

Esa es solo la parte pública del perfil. Mantén separados los siguientes valores como una unidad vinculada a cada entorno:

• la referencia al certificado y a la clave privada;
• el token de KSeF y el almacenamiento de los tokens de acceso y renovación;
• la caché de claves públicas de KSeF y el publicKeyId seleccionado;
• el espacio de nombres de la base de datos o del almacenamiento de objetos para XML y UPO;
• la cola, el límite de reintentos y el coordinador de límites de peticiones;
• los paneles de control, las alertas y las etiquetas de los registros;
• una opción para activar producción y un interruptor de emergencia.

El aviso sobre credenciales de producción del Ministerio no deja lugar a dudas: las claves de producción y las credenciales de KSeF pertenecen a PRD. Un token, certificado o clave de cifrado de TEST o DEMO no es una credencial de producción. La guía de claves públicas también documenta su rotación, por lo que no debes almacenar una única clave global en caché para los tres entornos.

No reescribas las URL que devuelve KSeF

KSeF puede devolver URL firmadas para subir o descargar archivos. El CIRF señala que sus hosts se corresponden con el entorno consultado. Comprueba el host devuelto mediante la lista de hosts permitidos del entorno seleccionado y utiliza después la URL completa tal como llegó. No sustituyas su host, no antepongas /v2 ni adjuntes un token Bearer de producción a una URL de almacenamiento.

Parece un detalle menor, hasta que una función auxiliar pensada para rutas normales de la API recibe una URL firmada de almacenamiento de objetos. Trata las bases de la API y las URL de recursos devueltas como dos tipos distintos.

¿Qué conviene probar en el entorno TEST de KSeF?

TEST sirve para demostrar que el cliente gestiona contratos y fallos con datos sintéticos. El acceso es deliberadamente más sencillo que en producción. Por eso no demuestra que la identidad ni los permisos de producción vayan a funcionar.

TEST admite certificados autofirmados y credenciales simuladas. Sus endpoints /testdata/* permiten crear personas, estructuras de entidades y permisos de prueba; habilitar escenarios con adjuntos; bloquear un contexto; acortar la vigencia de un certificado; y modificar los perfiles de límites. El CIRF publica ejemplos ejecutables en la guía de escenarios con datos de prueba.

Utiliza esos controles para ejercitar estados que resultarían caros de provocar de forma natural:

1. autenticación válida y no válida;
2. permiso denegado después de aceptar una credencial;
3. caducidad y rotación de certificados;
4. fallos en envíos en línea y por lotes;
5. gestión de HTTP 429 y pausa coordinada de la cuota compartida;
6. reinicio del proceso mientras una factura sigue en estado asíncrono;
7. campos de respuesta desconocidos y nuevas cabeceras de aviso;
8. recuperación del UPO cuando ya no existe el proceso original.

El objetivo no es conseguir que un único caso favorable quede en verde. Se trata de demostrar que la integración alcanza un estado conocido cuando KSeF acepta, retrasa, rechaza o limita una petición, o cuando añade campos a una respuesta de manera compatible.

Por qué los datos reales no son seguros en TEST

TEST no ofrece un espacio privado para cada integrador. Como varios integradores pueden autenticarse en el mismo contexto de empresa sintética, los datos pueden quedar visibles fuera de tu ejecución de pruebas. El CIRF pide a los integradores que empleen identificadores aleatorios y prescindan de datos de entidades reales.

La advertencia no se limita a los nombres. No envíes números de factura, direcciones, descripciones de líneas, datos bancarios, direcciones de correo, referencias de clientes ni XML de producción en el que solo hayas sustituido el NIP. Genera un conjunto de datos de prueba completamente sintético. Vuelve a crearlo cuando haga falta: los datos de TEST se eliminan de forma periódica y ninguna fuente oficial vigente promete un intervalo de conservación.

Una protección del entorno debería rechazar los ID de clientes de producción y los prefijos conocidos de facturas de producción antes de serializar. Esa comprobación pertenece al código de la aplicación, no a una lista de comprobación para el despliegue que alguien pueda saltarse.

¿Qué debes validar en KSeF DEMO?

DEMO prueba aquello que TEST simula de forma intencionada: la identidad de autenticación real, los registros reales de titularidad y las cadenas de permisos reales. Es el ensayo final de una versión candidata a producción, no un segundo entorno de pruebas para identidades arbitrarias.

El aviso de lanzamiento de DEMO del Ministerio indica que DEMO utiliza datos de autenticación reales y permisos comparables a los de producción. Este entorno descubre la distancia entre «nuestro código XAdES funciona» y «este certificado puede actuar en nombre de este contribuyente con el permiso necesario». La guía de autenticación de KSeF explica el flujo en detalle.

DEMO debería responder a cinco preguntas antes de un despliegue:

• ¿Puede la organización real autenticarse mediante la ruta de certificados prevista?
• ¿Tienen los operadores y sistemas previstos los permisos efectivos de KSeF?
• ¿Funciona la versión candidata con los formatos de factura admitidos en producción?
• ¿Se mantiene estable con límites de peticiones similares a producción?
• ¿Puede reanudar la consulta de estados y la captura de justificantes después de un reinicio?

Utiliza exactamente la compilación que piensas desplegar. Evita ramas exclusivas de DEMO y parches manuales. Si hace falta una diferencia de configuración, debe residir en el perfil del entorno, no en código que modifique el comportamiento sin hacerlo visible.

Un inicio de sesión real no permite usar contenido real en las facturas

DEMO combina identidad real con contenido ficticio en las facturas. El Ministerio señala que las facturas de este entorno no producen efectos jurídicos y se eliminan más adelante. También advierte de que el entorno puede contener datos migrados o procedentes de producción que no están anonimizados y reciben protección equiparable a producción.

Ambas afirmaciones son compatibles. Los datos que uses en las pruebas deben ser ficticios, pero los que ya residen en DEMO pueden seguir siendo sensibles. Aplica controles de acceso de producción y enmascara los datos sensibles en los registros. No presentes DEMO como una base de datos de muestras inocuas.

¿Por qué una prueba de humo en PRD sigue siendo una factura real?

PRD no tiene un modo inocuo de «factura de prueba». Si KSeF acepta el documento y le asigna un número de KSeF, la factura entra en circulación jurídica.

El manual de KSeF 2.0, parte II del Ministerio advierte de que una factura de prueba enviada por error a producción puede tener consecuencias en el IVA. El artículo 108, apartado 1, de la Ley polaca del IVA es tajante: quien indique el IVA en una factura queda obligado a pagarlo.

Por tanto, el primer envío controlado debe corresponder a una operación empresarial auténtica. Antes de ejecutarlo:

• aprovisiona las credenciales de producción en PRD, en lugar de copiarlas desde DEMO;
• comprueba el contexto del contribuyente y sus permisos mediante operaciones que no emitan facturas;
• confirma que la factura es real, está aprobada y lista para contabilizarse;
• comienza con una cola vacía o controlada;
• asigna a un operador para que supervise el estado, el número de KSeF y el UPO;
• establece cómo detener nuevos envíos sin perder las referencias ya aceptadas.

No implementes nunca un mecanismo de respaldo que pase automáticamente de TEST o DEMO a PRD. Tampoco permitas que un reintento modifique el entorno seleccionado. Guarda el entorno junto a cada referencia de sesión, referencia de factura, número de KSeF y clave de objeto del UPO para que la conciliación no pueda cruzar ese límite.

La guía sobre el UPO y la consulta de estados explica qué justificantes deben acompañar a cada factura aceptada. Un HTTP 202 o una referencia de sesión no equivalen a la aceptación definitiva.

¿Cómo afecta al paso entre entornos el desfase de versiones de la API de KSeF?

TEST puede ir por delante de DEMO y PRD. Esto permite conocer un cambio con antelación, pero también implica que un entorno en verde puede estar validando un contrato distinto al del destino.

El registro oficial de cambios recoge la API 2.7.1 para TEST el 26 de agosto de 2026, con despliegues en DEMO y PRD programados para el 15 y el 23 de septiembre. En la fecha de comprobación, la versión 2.6.1 era la más reciente que figuraba como desplegada en PRD. Esta fotografía concreta quedará obsoleta; lo importante es el patrón de despliegue.

Antes de pasar a cada entorno, registra lo siguiente:

No generes un cliente a partir de la rama main del repositorio y des por hecho que coincide con producción. Fija el contrato probado, admite los campos de respuesta adicionales documentados y ejecuta pruebas de compatibilidad con el entorno de destino antes de desplegar.

Los límites de peticiones demuestran por qué importa. Un texto oficial anterior indicaba que los valores predeterminados de TEST multiplicaban por diez los de producción. El registro de cambios posterior de la API 2.5.0 señala que esos valores se igualaron con PRD, mientras TEST conservó sus endpoints de simulación. La regla segura es consultar los límites efectivos durante la ejecución y seguir la guía de reintentos de KSeF, en lugar de codificar un multiplicador.

¿Qué debes comprobar al pasar una integración de KSeF entre entornos?

Pasa de entorno con pruebas, no con suposiciones. La siguiente lista es una síntesis de ingeniería, no un procedimiento obligatorio del Ministerio.

En las pruebas locales y de CI

• Fija los esquemas FA(3) y datos de prueba deterministas.
• Comprueba los bytes exactos sobre los que calculas el hash y que después cifras y envías.
• Mantén la selección del entorno fuera de los datos de la factura.
• Rechaza cualquier host que no pertenezca a las tres listas oficiales de hosts permitidos.
• Prueba campos desconocidos y trabajos asíncronos interrumpidos.

En TEST

• Crea identidades y datos sintéticos nuevos.
• Ejercita los recorridos de éxito, rechazo, limitación, caducidad y reinicio.
• Confirma que ningún identificador ni secreto de producción llega a los registros o al almacenamiento.
• Registra la versión de OpenAPI de TEST que haya usado la ejecución.

En DEMO

• Autentica con la identidad real de la organización prevista.
• Comprueba la estructura real de permisos.
• Envía únicamente contenido de facturas ficticio o anonimizado.
• Ejecuta con límites similares a producción y la compilación candidata.
• Concilia los estados, las referencias y el UPO después de forzar un reinicio.

Antes y durante el paso a PRD

• Compara el OpenAPI activo de PRD con el contrato fijado en el cliente.
• Aprovisiona para PRD certificados, tokens y permisos nuevos, además de una caché nueva de claves públicas.
• Activa protecciones que bloqueen cuentas y datos sintéticos.
• Comprueba primero las operaciones que no emitan facturas.
• Envía una factura auténtica y después concilia su estado final y su UPO.
• Aumenta el volumen poco a poco mientras supervisas los 429, los fallos y la antigüedad de la cola.

Ten a mano la guía sobre la estructura FA(3) junto con esta lista. Superar la validación XSD y TEST confirma la forma del XML y el comportamiento del cliente, pero no el tratamiento fiscal ni la validez jurídica completa de una factura real. Para resolver fallos, consulta la guía de errores de validación de KSeF sin volver a enviar a ciegas una petición ambigua.

¿Cómo gestiona KSeF Kit el límite entre entornos?

El cambio de entorno más seguro es aquel que tu equipo no tiene que mantener. KSeF Kit es un producto independiente para equipos cuyo origen de facturación es Stripe. Convierte las facturas finalizadas de Stripe a FA(3), las envía, espera el resultado de KSeF, guarda el UPO y escribe el número de KSeF en el registro de origen.

Su guía pública de conexión documenta la configuración de TEST y producción. Esto lo convierte en una opción concreta para quienes valoran si desarrollar o comprar una integración para la facturación con Stripe, no en una promesa de cubrir todos los sistemas contables, todos los tipos de factura ni todas las decisiones fiscales.

Tanto si eliges un servicio gestionado como si mantienes tu propio cliente, respeta el mismo límite: trabajo sintético en TEST, identidad real con facturas ficticias en DEMO y solo facturas auténticas aprobadas en PRD. Pasa el código de un entorno al siguiente. No traslades nunca sus secretos ni sus datos.