Saltar al contenido principal

Cómo funciona

xhandler resuelve tres tareas de la facturación electrónica en Perú: crear el XML de un comprobante, firmarlo y enviarlo a la SUNAT. Esta página explica cómo encajan esas piezas y qué necesitas para usarlas.

Tres pasos independientes​

PasoQué haceEntradaSalida
CrearCompleta los datos que faltan, calcula impuestos y totales, y genera el XML UBL 2.1.Un documento con los datos esencialesXML sin firmar
FirmarAgrega la firma digital XML (RSA-SHA256) que exige la SUNAT.XML + certificado digitalXML firmado
EnviarComprime el XML, elige el servicio de la SUNAT según el tipo de comprobante y devuelve la respuesta.XML firmado + usuario SOLCDR, ticket o error de la SUNAT

Cada paso funciona por separado, así que puedes usar solo el que necesites:

  • Si ya generas el XML con otro sistema, puedes usar solo firmar y enviar. La firma no exige que el XML venga de xhandler.
  • Si tu sistema ya firma, puedes usar solo enviar con cualquier XML firmado.
  • Si solo necesitas el XML, por ejemplo para revisarlo o archivarlo, puedes usar solo crear.

Más detalles en Firma digital, Envío y respuestas de la SUNAT y Cálculos automáticos.

Un solo núcleo para todos los lenguajes​

La lógica de xhandler está escrita una sola vez, en Rust: generar el XML, calcular impuestos, firmar, armar las peticiones SOAP y REST para la SUNAT y leer sus respuestas.

  • Rust usa ese núcleo directamente, como un crate más.
  • Java, Python y Go traen el mismo núcleo compilado a WebAssembly y embebido en la librería:
    • En Java se ejecuta como bytecode de la JVM, así que funciona en cualquier JVM y es compatible con GraalVM native.
    • En Python el paquete es una wheel universal, sin extensiones nativas que compilar.
    • En Go es Go puro, sin cgo.

Por eso:

  • El comportamiento es idéntico en los cuatro lenguajes: el mismo documento genera el mismo XML, la misma firma y la misma petición a la SUNAT.
  • No compilas código nativo en Java, Python ni Go.
  • Los nombres de las clases y tipos (Invoice, FileSender, SigningKey, SunatClient...) son los mismos en todos los lenguajes.

Lo que sí cambia entre lenguajes es la parte de entrada y salida: el cliente HTTP, los reintentos y el caché de tokens. Cada librería usa el cliente HTTP propio de su lenguaje.

nota

En Go, la primera llamada compila el módulo WebAssembly, un costo que se paga una sola vez por proceso.

Comprobantes soportados​

El nombre del tipo es el mismo en los cuatro lenguajes; solo cambia el paquete desde donde lo importas.

ComprobanteJavaRustPythonGoRespuesta de la SUNAT
Factura y boletaInvoiceInvoicexbuilder.Invoicexbuilder.InvoiceCDR
Nota de créditoCreditNoteCreditNotexbuilder.CreditNotexbuilder.CreditNoteCDR
Nota de débitoDebitNoteDebitNotexbuilder.DebitNotexbuilder.DebitNoteCDR
Guía de remisión (remitente y transportista)DespatchAdviceDespatchAdvicexbuilder.DespatchAdvicexbuilder.DespatchAdviceTicket
Comprobante de percepciónPerceptionPerceptionxbuilder.Perceptionxbuilder.PerceptionCDR
Comprobante de retenciónRetentionRetentionxbuilder.Retentionxbuilder.RetentionCDR
Resumen diario de boletasSummaryDocumentsSummaryDocumentsxbuilder.SummaryDocumentsxbuilder.SummaryDocumentsTicket
Comunicación de bajaVoidedDocumentsVoidedDocumentsxbuilder.VoidedDocumentsxbuilder.VoidedDocumentsTicket
Resumen de reversionesReversionReversionxbuilder.Reversionxbuilder.ReversionTicket
  • Java: paquete io.github.project.openubl.xbuilder.models.
  • Rust: use xhandler::prelude::*;.
  • Python: from xhandler import xbuilder.
  • Go: github.com/project-openubl/xhandler-go/v6/xbuilder.

Algunos tipos se deducen de los datos: en Invoice, la serie decide si es factura (F001) o boleta (B001); en DespatchAdvice, si es guía del remitente (T001, tipo 09) o del transportista (V001, tipo 31).

Las guías paso a paso están en Casos de uso.

Entornos de la SUNAT​

BetaProducción
Para qué sirvePruebas, sin valor tributarioComprobantes reales
Facturas, boletas, notas, resúmenes y bajasSíSí
Percepciones, retenciones y reversionesSíSí
Guías de remisiónNoSí
Consulta y validación de comprobantesNoSí
Varias facturas en un zip (sendPack)NoSí
CredencialesPúblicas: 12345678959MODDATOS / MODDATOSTu usuario SOL
CertificadoEl certificado de prueba para el RUC 12345678912Tu certificado digital

Cada librería trae las URLs de ambos entornos. Para pasar de beta a producción solo cambias las URLs y las credenciales; el resto del código es el mismo. También puedes usar URLs propias, por ejemplo las de un OSE. Revisa Envío y respuestas de la SUNAT.

Credenciales que necesitas​

  • Usuario SOL: el RUC seguido del usuario (por ejemplo 12345678912USUARIO) y su contraseña. Sirve para enviar cualquier comprobante.
  • Certificado digital: un archivo PKCS#12 (.pfx o .p12) con su contraseña, o la llave privada y el certificado en PEM. Debe pertenecer al RUC emisor. Revisa Firma digital.
  • Client ID y client secret: solo para las guías de remisión, que usan la API REST de la SUNAT con OAuth. Los obtienes en el menú SOL. Revisa Guías de remisión.

Las credenciales se indican en Credentials: username, password y, para guías, clientId/clientSecret en Java, client_id/client_secret en Rust y Python, y ClientID/ClientSecret en Go.

Las respuestas de la SUNAT​

Al enviar un comprobante, la SUNAT puede responder de tres formas:

  • CDR (constancia de recepción): la respuesta inmediata para facturas, boletas, notas, percepciones y retenciones. Indica si el comprobante fue aceptado, aceptado con observaciones o rechazado.
  • Ticket: para resúmenes diarios, comunicaciones de baja, reversiones y guías de remisión. La SUNAT procesa el envío después y tú consultas el ticket para obtener el CDR.
  • Error de la SUNAT (fault): la SUNAT no procesó el envío, por ejemplo por credenciales sin permisos.

Ninguna de las tres es una excepción o un error de programación: todas llegan como respuesta. Revisa Envío y respuestas de la SUNAT para procesarlas y Manejo de errores para los errores que sí se lanzan.