sunat_cpe_core
Núcleo de dominio, catálogos oficiales del Anexo N° 8 de SUNAT, validador aritmético de traspaso directo (Strict Passthrough), generador XML UBL 2.1/2.0, firmador digital XAdES-BES (RSA-SHA256) en Dart puro y contratos unificados OSE/PSE para Facturación Electrónica en el Perú (CPE).
Propósito y Arquitectura Strict Passthrough con Decimal
sunat_cpe_core constituye la base compartida por los 9 adaptadores de Operadores de Servicios Electrónicos (OSE) y Proveedores de Servicios Electrónicos (PSE) del ecosistema sunat_cpe, así como por la fachada unificada multimarca.
Principios de Diseño
- Precisión Financiera Exacta (
Decimal): Todos los valores monetarios, precios unitarios, valores unitarios sin impuestos, cantidades, tasas impositivas y tipos de cambio utilizan el tipoDecimal(reexportado directamente porsunat_cpe_core), eliminando por completo los errores de redondeo de punto flotante binario (doubleIEEE 754). - Arquitectura Strict Passthrough (Traspaso Directo): La librería nunca muta, inventa ni recalcula silenciosamente los importes tributarios enviados por el ERP o sistema de facturación. En su lugar, transmite exactamente los montos calculados por el sistema origen y los verifica previamente mediante
CpeMathValidatorrespetando las tolerancias oficiales de redondeo de SUNAT. - 100 % Dart 3 Puro: Construido con clases selladas (
sealed class), evaluación exhaustiva por pattern matching y cero generación de código (build_runner).
Jerarquía de Entidades de Dominio (CpeDocument)
Todos los comprobantes electrónicos heredan de la clase sellada raíz CpeDocument:
| Entidad | Clase Padre | Código(s) SUNAT | Estándar XML | Descripción |
|---|---|---|---|---|
InvoiceDocument |
SalesCpeDocument |
01, 03 |
UBL 2.1 | Factura Electrónica y Boleta de Venta Electrónica (incluye cuotas al crédito RS 000193-2020, detracciones SPOT, retenciones IGV, percepciones y anticipos). |
CreditNoteDocument |
SalesCpeDocument |
07 |
UBL 2.1 | Nota de Crédito Electrónica (incluye causal Catálogo 09 y reprogramación de cuotas con código 13). |
DebitNoteDocument |
SalesCpeDocument |
08 |
UBL 2.1 | Nota de Débito Electrónica (intereses por mora, aumento en el valor, penalidades según Catálogo 10). |
PurchaseSettlementDocument |
SalesCpeDocument |
04 |
UBL 2.1 | Liquidación de Compra Electrónica emitida a personas naturales sin RUC con ubicación de operación. |
DailySummaryDocument |
CpeDocument |
RC |
UBL 2.0 | Resumen Diario de Boletas de Venta y Notas Electrónicas vinculadas (SummaryDocuments). |
VoidedDocument |
CpeDocument |
RA, RR |
UBL 2.0 | Comunicación de Baja de comprobantes y Resumen de Reversiones (VoidedDocuments). |
DespatchAdviceDocument |
CpeDocument |
09, 31 |
UBL 2.1 | Guía de Remisión Electrónica Remitente (09) y Transportista (31) con vehículos, conductores y puntos de partida/llegada. |
RetentionDocument |
AgentCpeDocument |
20 |
UBL 2.0 | Comprobante de Retención Electrónico con detalle de pagos y tipo de cambio. |
PerceptionDocument |
AgentCpeDocument |
40 |
UBL 2.0 | Comprobante de Percepción Electrónico con detalle de cobros y régimen aplicable. |
Catálogos Oficiales SUNAT (Anexo N° 8)
El paquete incluye enumeraciones tipadas con los códigos oficiales de SUNAT:
CpeDocumentType(Catálogo 01): Tipo de Documento (factura,boleta,liquidacionCompra,notaCredito,notaDebito,guiaRemisionRemitente,comprobanteRetencion,guiaRemisionTransportista,comprobantePercepcion,resumenDiario,comunicacionBaja,reversion).CurrencyCode(Catálogo 02): Monedas ISO 4217 (pen,usd,eur).TaxCategoryCode(Catálogo 05): Tipos de Tributos (1000IGV,1016IVAP,9997Exonerado,9998Inafecto,9996Gratuito,9995Exportación,2000ISC,7152ICBPER,9999Otros).IdentityDocumentType(Catálogo 06): Documentos de Identidad (noDomiciliado,dni,carnetExtranjeria,ruc,pasaporte,cedulaDiplomatica,tam).IgvAffectationType(Catálogo 07): Afectación del IGV (gravadoOperacionOnerosa10, retiros gratuitos gravados11–16,gravadoIvap17,exoneradoOperacionOnerosa20,inafectoOperacionOnerosa30, retiros inafectos31–36,exportacion40).CreditNoteReasonCode(Catálogo 09): Motivos de Nota de Crédito (01Anulación de la operación hasta13Corrección del monto neto pendiente de pago y/o fechas de vencimiento).DebitNoteReasonCode(Catálogo 10): Motivos de Nota de Débito (01Intereses por mora,02Aumento en el valor,03Penalidades,10Exportación,11IVAP).TransportModeCode(Catálogo 18): Modalidad de Traslado (transportePublico01,transportePrivado02).SummaryLineStatus(Catálogo 19): Estado de ítem en Resumen Diario (adicionar1,modificar2,anulado3).DespatchReasonCode(Catálogo 20): Motivos de Traslado para Guías de Remisión (venta01,compra02,trasladoEntreEstablecimientos04,importacion08,exportacion09, etc.).PerceptionRegimeCode(Catálogo 22): Régimen de Percepción (ventaInterna01al 2 %,adquisicionCombustible02al 1 %,tasaEspecial03al 0.5 %).RetentionRegimeCode(Catálogo 23): Régimen de Retención (tasaTresPorCiento01al 3 %,tasaSeisPorCiento02al 6 %).OperationType(Catálogo 51): Tipo de Operación (ventaInterna0101,operacionSujetaDetraccion1001, etc.).
Motores Core: Validación, UBL 2.1, Firma XAdES-BES y Códec ZIP/CDR
1. Validador Matemático (CpeMathValidator)
Valida un CpeDocument antes de generar el XML o transmitirlo a la red:
- Verifica formato de RUC de 11 dígitos, consistencia entre
DocumentId.issuerRucyCompanyParty.ruc, y correlativo positivo. - Verifica ecuaciones por cada
CpeLineItem: valor de venta por línea, reglas de transferencia gratuita (isReferencePrice = true,unitValue == 0.00), cálculo de IGV/IVAP, ISC e impuesto a las bolsas plásticas (ICBPER). - Verifica sumatorias de bases imponibles hacia
MonetaryTotals(totalGravadas,totalExoneradas,totalInafectas,totalExportacion,totalGratuitas,totalValorVenta,totalImpuestos,totalPrecioVenta,importeTotalPagar). - Aplica la regla obligatoria de la RS 000193-2020/SUNAT en ventas al crédito: el monto neto pendiente de pago (
netPendingAmount) y la suma de cuotas (Cuota001,Cuota002...) deben descontar la detracción SPOT y/o retención del IGV respecto alimporteTotalPagar.
2. Generador XML UBL 2.1 y 2.0 (UblXmlBuilder)
Construye el documento XML estándar con todos los espacios de nombres (cac, cbc, ds, ext, sac) y el contenedor <ext:ExtensionContent/> listo para la firma digital mediante buildUnsignedXml(document).
3. Firmador Digital RSA-SHA256 (XadesBesSigner)
Firma digitalmente en Dart puro (sin dependencias nativas ni OpenSSL externo):
- Incluye un serializador determinista de XML Canónico 1.0 (W3C C14N).
- Calcula el resumen criptográfico SHA-256 (
digestValue) y la firma RSA-SHA256 (signatureValue) usandoCpeCertificateCredentials(cargable desde formato PEM PKCS#1 o PKCS#8 conCpeCertificateCredentials.fromPem). - Inyecta el nodo
<ds:Signature Id="SignSUNAT">en<ext:ExtensionContent>.
4. Códec ZIP y Analizador de CDR (CpeZipCodec)
encodeXmlToZip: Empaqueta{RUC}-{TIPO}-{SERIE}-{NUMERO}.xmlen un archivo.zipen memoria y devuelve tanto los bytes (Uint8List) como su representación en Base64.parseCdrFromBase64Zip/parseCdrFromZipBytes/parseCdrFromXmlString: Extrae y analiza la Constancia de Recepción (<ar:ApplicationResponse>), obteniendo el código de respuesta (0aceptado), descripción, hash (digestValue), fecha/hora y observaciones no bloqueantes (SunatWarning, códigos 4000+).
Manejo de Errores Tipado con CpeResult<T>
Todas las operaciones de validación y emisión devuelven CpeResult<T>, una clase sellada con dos variantes (CpeSuccess<T> y CpeFailure<T>) que soporta tres estilos de consumo:
- Pattern Matching Exhaustivo (
switch):switch (resultado) { case CpeSuccess(:final data): print('Éxito: $data'); case CpeFailure(:final error): print('Fallo (${error.code}): ${error.message}'); } - Programación Funcional (
fold):final mensaje = resultado.fold( (data) => 'Procesado correctamente', (error) => 'Error detectado: ${error.message}', ); - Estilo Imperativo (
getOrThrow()):try { final data = resultado.getOrThrow(); } on CpeValidationException catch (e) { for (final issue in e.issues) { print(issue); } }
Jerarquía Sellada de Excepciones (CpeException)
CpeValidationException: Error aritmético o estructural detectado localmente antes de enviar a la red (contieneList<ValidationIssue>).OseTransportException: Error de red, timeout o fallo HTTP 5xx (reintentable).OseAuthException: Credenciales WS-Security o token OAuth2 inválidos.SunatExceptionError: Excepción técnica de SUNAT/OSE (códigos0100a1999). El comprobante no fue registrado y puede corregirse reutilizando el mismo correlativo.SunatRejectionException: Rechazo definitivo de negocio por SUNAT/OSE (códigos2000a3999). Incluye el CDR de rechazo (rejectionCdr) si fue emitido.
Ejemplo Rápido
Ejecuta el ejemplo completo incluido en el paquete para ver los 6 escenarios en acción (100 % offline):
dart run packages/sunat_cpe_core/example/main.dart
Libraries
- sunat_cpe_core
- Entidades de dominio, catálogos oficiales SUNAT, validador matemático passthrough, generador XML UBL 2.1, firmador digital XAdES-BES en Dart puro y contratos OSE/PSE.