Download the PHP package ionysdev/pkuatia without Composer

📄 PKuatia

PKuatia es una biblioteca PHP para interactuar con el Sistema Integrado de Facturación Electrónica Nacional (SIFEN) de Paraguay, implementando la especificación técnica del sistema EKuatia.

Esta biblioteca permite generar, firmar, enviar y consultar Documentos Tributarios Electrónicos (DTE) según el Manual Técnico Versión 150 del SIFEN.

📋 Tabla de Contenidos

• Características
• Requisitos
• Instalación
• Configuración
• Recomendaciones para Producción
• Uso Básico
• Funcionalidades
• Tipos de Documentos Soportados
• Ejemplos
• Pruebas
• Estructura del Proyecto
• Contribución
• Licencia
• Autores

✨ Características

• 🔐 Firma digital de documentos usando certificados PEM, P12 o PFX
• 📤 Envío de documentos electrónicos individuales o en lotes (hasta 50 documentos)
• 🔍 Consultas al SIFEN:
  • Consulta de RUC (Registro Único del Contribuyente)
  • Consulta de documentos electrónicos por CDC
  • Consulta de lotes de documentos
• 🎫 Gestión de eventos:
  • Cancelación de documentos electrónicos
  • Inutilización de números de documentos
• 📱 Generación automática de códigos QR para validación de documentos
• 🏗️ Arquitectura orientada a objetos con clases tipadas
• ✅ Validaciones según especificaciones del Manual Técnico
• 🔄 Soporte para ambientes de desarrollo y producción
• 📊 Mapeos de datos predefinidos (países, departamentos, monedas, unidades de medida)

📦 Requisitos

• PHP >= 8.1
• Extensiones PHP: soap, dom, openssl, zip, bcmath
• Composer
• Certificado digital emitido por una ente prestador de servicios de confianza de Paraguay
• Clave privada correspondiente al certificado
• Credenciales de acceso al SIFEN (ID CSC y CSC)

🚀 Instalación

Instalación mediante Composer

Instalación desde el repositorio

⚙️ Configuración

Antes de utilizar la biblioteca, es necesario configurar los parámetros de conexión y autenticación:

Configuración desde archivo JSON

También puedes cargar la configuración desde un archivo JSON:

Ejemplo de config.json:

🏭 Recomendaciones para Producción

Caché de WSDL

El SIFEN limita la tasa de solicitudes. Descargar el WSDL en cada operación puede provocar bloqueos temporales. Se recomienda activar la caché de WSDL en disco:

En Windows, además, conviene asegurar un directorio de caché válido antes de iniciar Sifen, porque el valor por defecto (/tmp) no existe:

Tasa de solicitudes (rate limiting)

El ambiente de pruebas (sifen-test) es especialmente sensible a la saturación: ante un exceso de solicitudes deja de responder por varios minutos. Buenas prácticas:

• Mantener wsdlCacheEnabled = true.
• Espaciar los reintentos (no reintentar en bucle inmediato).
• Para la consulta de resultado de lote (ConsultaLote), implementar reintentos con espera progresiva (backoff): esperar ~1 minuto en el primer intento y aumentar gradualmente.

Certificados .p12 / .pfx con cifrado heredado (OpenSSL 3)

Los certificados emitidos por las CA de Paraguay suelen venir en un PKCS#12 cifrado con algoritmos heredados (RC2-40 / 3DES) que OpenSSL 3 —incluido en PHP 8— deshabilita por omisión. Si al inicializar obtenés un error del tipo digital envelope routines::unsupported, tenés tres opciones:

1. Habilitar el proveedor legacy de OpenSSL antes de iniciar PHP, mediante las variables de entorno OPENSSL_CONF (apuntando a un openssl.cnf que active los proveedores default y legacy) y OPENSSL_MODULES (apuntando al directorio que contiene legacy.dll / legacy.so). No alcanza con putenv() en tiempo de ejecución: el proveedor se inicializa en el primer uso de OpenSSL.

2. Reexportar el certificado a un PKCS#12 con cifrado moderno:

3. Convertir el .p12 a PEM y usar certificateFormat = "pem".

La librería detecta este caso y arroja una excepción con estas mismas instrucciones.

📖 Uso Básico

Consultar un RUC

Consultar un Documento Electrónico

🎯 Funcionalidades

Los ejemplos completos de FE contado y cancelación están en Ejemplos. Otros tipos de documento y eventos se documentarán en una siguiente iteración.

📄 Tipos de Documentos Soportados

La biblioteca soporta los siguientes tipos de Documentos Tributarios Electrónicos, que son los que el XSD de producción del SIFEN acepta actualmente (iTiDE):

Nota sobre los tipos 2, 3 y 8 (Factura de Exportación, Factura de Importación y Comprobante de Retención): figuran en el Manual Técnico, pero el XSD de producción del SIFEN los rechaza (no están habilitados por la DNIT), por lo que ninguna librería del ecosistema puede emitirlos actualmente. La enumeración TimbTiDE los conserva para poder identificarlos al deserializar.

Puedes usar la enumeración TimbTiDE para referenciar estos tipos:

📁 Estructura del Proyecto

🔧 Dependencias

• robrichards/xmlseclibs (^3.1): Para la firma digital XML
• krowinski/bcmath-extended (^7.0): Para operaciones matemáticas de precisión extendida

📚 Ejemplos

Los fragmentos usan datos genéricos (RUC 80000000-5, timbrado 12345678). Reemplazalos por tu timbrado habilitado, certificado y CSC antes de enviar al SIFEN. En ambiente dev el nombre del emisor se ajusta automáticamente al texto de prueba reglamentario.

Factura electrónica al contado (emitir y enviar)

Cancelar un DE aprobado

Solo podés cancelar un CDC que el SIFEN haya autorizado previamente. El motivo debe tener entre 5 y 500 caracteres.

Otros scripts de referencia

En test/ hay scripts de consulta que requieren certificado y red:

• ConsultaRUC.php, ConsultaDE.php, ConsultaLote.php
• SmokeTest.php — verificación offline rápida (php test/SmokeTest.php)

Próximamente en esta sección: FE crédito en cuotas, NC, ND, NR con transporte, autofactura, inutilización y eventos del receptor (ConformarDE, etc.).

⚠️ Notas Importantes

1. Certificados Digitales: Debes contar con un certificado digital válido emitido por algún ente prestador de servicios de confianza habilitado por el Ministerio de Industria y Comercio del Paraguay.

2. Ambiente de Pruebas: Utiliza Config::ENV_DEV para desarrollo y pruebas. Los documentos generados en este ambiente llevarán el texto "DE generado en ambiente de prueba - sin valor comercial ni fiscal".

3. Credenciales del SIFEN: El ID CSC y CSC te serán proporcionados por la DNIT durante el proceso de habilitación.

4. Límites de Lotes: Cada lote puede contener un máximo de 50 documentos electrónicos.

5. Firma Digital: La biblioteca requiere que el certificado y la clave privada estén disponibles localmente.

🧪 Pruebas

Verificaciones offline (no requieren certificado ni conexión al SIFEN):

El CI en GitHub ejecuta lint (php -l), smoke test, PHPUnit y PHPStan en PHP 8.1, 8.2 y 8.3.

Detalle del flujo de contribución, estilo y convención de commits: CONTRIBUTING.md.

🤝 Contribución

Las contribuciones son bienvenidas. Leé CONTRIBUTING.md antes de abrir un PR.

Mantenedores: publicación en Packagist → docs/PUBLICAR.md.

📝 Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.

👥 Autores

• Abilio Mancuello Petters - [email protected]
• Gabriel Gauto - [email protected]

🔗 Enlaces Útiles

• Documentos técnicos para desarrollo del software
• Portal del Contribuyente DNIT - Marangatu
• Documentación del SIFEN

Desarrollado especialmente para la comunidad de desarrolladores paraguayos