README

Facturación electrónica de SUNAT (CPE Perú) en PHP puro, framework-agnóstico.

elpandape/quipu-lite construye el XML UBL 2.1 de un comprobante, lo firma (xmldsig), lo envía a los webservices SOAP/REST de SUNAT, consulta su estado y parsea el CDR — sin arrastrar Laravel, Symfony ni ningún framework. Es una implementación propia y completa de la maquinaria CPE, no un wrapper.

Es la edición Lite (MIT): el emisor completo y auto-verificable. La edición Pro (comercial) añade builders fluidos, motor tributario, validación avanzada, diagnóstico y tooling sobre esta base.

📚 Documentación

La documentación completa —instalación, cada tipo de comprobante, firma, validación, consulta de CPE, lotes, paso a producción y buenas prácticas— vive en el sitio público:

👉 https://quipu.elpanda.pe/

🚦 Estado

Estable — v1.0.0. El proyecto sigue Semantic Versioning: dentro de 1.x no habrá cambios incompatibles en la API pública. Probada con 100 % de cobertura de líneas y tipos y CI en PHP 8.4/8.5; una factura fue aceptada en SUNAT beta de extremo a extremo. Los cambios están en el CHANGELOG.

Instalación

composer require elpandape/quipu-lite

Requisitos: PHP 8.4+ y las extensiones soap, dom, openssl, zip. La extensión curl solo hace falta si usas el CurlHttpClient incluido (GRE y Consulta de Validez, que van por REST); si inyectas tu propio HttpClient o solo emites por SOAP, no la necesitas.

Qué hace

Construyes tu Invoice (un modelo de dominio readonly), le pasas un builder, un firmante y un sender, y emites:

use ElPandaPe\Quipu\Quipu;
use ElPandaPe\Quipu\Signer\XmlSecSigner;
use ElPandaPe\Quipu\Ws\{SoapEndpoints, SoapSender};
use ElPandaPe\Quipu\Xml\InvoiceBuilder;

$quipu = new Quipu(
    new InvoiceBuilder(),
    new XmlSecSigner($certificatePem),                             // PEM: cert X.509 + clave privada
    new SoapSender(SoapEndpoints::beta()->billServiceUrl(), $solUsername, $solPassword),
);

$errors = $quipu->validate($invoice);    // reglas de negocio SUNAT, opt-in — [] si es consistente
$result = $quipu->emitInvoice($invoice); // firma + envío; devuelve un BillResult con el CDR tipado

$result->cdr->status;        // Accepted | AcceptedWithObservations | Rejected
$result->cdr->responseCode;  // "0" = aceptado

La fachada Quipu centraliza todo el flujo: validate / assertValid, sign, emit / emitInvoice, emitSummary / emitVoidance / emitReversion, emitGuide / getGuideStatus, sendPack / getPackStatus, getStatus, validateCpe (Consulta de Validez), read (XML → modelo), qrString y printable (proyección a una vista de impresión tipada; el PDF lo renderizas tú).

Lite vs Pro

Lite es todo lo que necesitas para emitir correctamente. Pro es productividad y resiliencia encima, para quien quiere ir más rápido y con más red de seguridad.

Capacidad	`quipu-lite` (MIT)	`quipu-pro` (comercial)
Construir UBL 2.1, firmar, enviar (SOAP/REST) y parsear el CDR	✓	✓
Los 9 documentos / 11 códigos de SUNAT (ver abajo)	✓	✓
Validadores de negocio + XSD, catálogos tipados, round-trip (XML → modelo)	✓	✓
Representación impresa (vista tipada + string del QR)	✓	✓
Builders fluidos con motor tributario (calcula IGV/ISC/ICBPER/detracción…)	—	✓
Envío resiliente (logging → retry → idempotencia)	—	✓
Validación estricta/cruzada + diagnóstico accionable de rechazos	—	✓
Certificados `.pfx`/`.p12` (inspección, conversión a PEM, pre-flight)	—	✓
Tooling de XML (inspector XPath, diff, JSON) y toolkit de testing shippable	—	✓

Alcance

Construye, firma, valida, envía y parsea el CDR de:

Documento	Código (Cat. 01)	Builder
Factura / boleta de venta	`01` / `03`	`InvoiceBuilder`
Nota de crédito / débito	`07` / `08`	`NoteBuilder`
Guía de remisión remitente / transportista	`09` / `31`	`DespatchBuilder` / `CarrierDespatchBuilder`
Comprobante de retención / percepción	`20` / `40`	`RetentionBuilder` / `PerceptionBuilder`
Resumen diario de boletas	`RC`	`SummaryBuilder`
Comunicación de baja	`RA`	`VoidedBuilder`
Resumen de reversiones	`RR`	`ReversionBuilder`

No hace persistencia, series/correlativos, máquina de estados ni scheduling —eso corresponde a tu aplicación o a una capa de integración con tu framework (para Laravel existe elpandape/quipu-laravel)—, ni calcula el IGV: Lite recibe los montos ya calculados (el motor tributario que los calcula está en Pro).

Desarrollo y tests

Note

No hay PHP local: todo corre en Docker vía make. No invoques php/composer/vendor/bin/* directo.

make install          # instala dependencias en el contenedor
make cert             # genera el certificado de prueba (autofirmado, determinista)
make review           # quality gate completo (ver abajo)
make fix              # rector + php-cs-fixer
make test             # solo Pest

Calidad

make review debe quedar verde antes de cada commit: PHP-CS-Fixer → Rector → PHPStan nivel max + strict-rules → Pest con 100 % de cobertura de líneas y de tipos (--min=100). CI corre la matriz PHP 8.4 / 8.5. Los tests no usan red: la firma es local con un certificado autofirmado y el borde SOAP se mockea (el único @codeCoverageIgnore, junto al borde HTTP y el reloj de sistema).

Changelog

Los cambios notables están en el CHANGELOG (formato Keep a Changelog).

Contribuir

Las contribuciones son bienvenidas —códigos de catálogo, reportes de rechazos de SUNAT con evidencia, tests y documentación. Lee la guía de contribución.

Seguridad

Si descubres una vulnerabilidad de seguridad, no abras un issue público: escribe a contacto@elpanda.pe.

Créditos

ElPandaPe — autoría y mantenimiento.
greenter — referencia del dominio CPE de SUNAT (quipu es una implementación propia e independiente; greenter no es una dependencia).
robrichards/xmlseclibs — firma xmldsig.

Licencia

Distribuido bajo licencia MIT — ver LICENSE.md.

Paquete no oficial: no está afiliado, avalado ni patrocinado por SUNAT.

elpandape / quipu-lite

Package info

Security

Statistics