Saltar al contenido principal

Emitir facturas y boletas

La factura y la boleta de venta son los comprobantes de pago más comunes. Emites una factura cuando vendes a una empresa o persona con RUC, y una boleta cuando vendes a un consumidor final, normalmente identificado con su DNI.

En xhandler las dos se crean con el mismo modelo, Invoice. La serie decide el tipo: una serie que empieza con F (por ejemplo F001-1) genera una factura (tipo 01), y una que empieza con B (por ejemplo B001-1) genera una boleta (tipo 03).

Factura​

Solo necesitas la serie y número, el proveedor, el cliente y los detalles. Este ejemplo agrega los campos más usados: moneda, fechas, unidad de medida, tipo de IGV y observaciones.

En cada detalle indica el precio unitario sin impuestos (precio) o el precio con impuestos (precioConImpuestos); el otro se calcula.

Invoice factura = Invoice.builder()
.serieNumero("F001-1")
.moneda("PEN") // por defecto "PEN"
.fechaEmision(LocalDate.of(2026, 11, 15)) // por defecto: hoy en Perú
.horaEmision(LocalTime.of(10, 30)) // opcional
.fechaVencimiento(LocalDate.of(2026, 12, 15)) // opcional
.proveedor(Proveedor.builder()
.ruc("12345678912")
.razonSocial("Softgreen S.A.C.")
.build())
.cliente(Cliente.builder()
.tipoDocumentoIdentidad("6") // RUC (Catálogo 6)
.numeroDocumentoIdentidad("12121212121")
.nombre("Carlos Feria")
.build())
.detalles(List.of(
Detalle.builder()
.descripcion("Item")
.cantidad(new BigDecimal("2"))
.precio(new BigDecimal("100.00")) // sin impuestos
.unidadMedida("NIU") // por defecto "NIU"
.igvTipo("10") // Catálogo 7; por defecto "10" (gravado)
.build(),
Detalle.builder()
.descripcion("Item 2")
.cantidad(new BigDecimal("1"))
.precioConImpuestos(new BigDecimal("118.00")) // con impuestos
.build()))
.observaciones("Entregar en almacén")
.build();

String xml = new XBuilder().build(factura);

El resultado es el XML UBL 2.1 de la factura, todavía sin firmar. Los campos que no indicaste se completan con valores por defecto: moneda PEN, fecha de emisión de hoy en Perú, tipo de operación 0101 (venta interna), unidad de medida NIU, tipo de IGV 10 (gravado) y forma de pago al contado. El IGV, los totales y las leyendas se calculan a partir de los detalles; revisa Cálculos de impuestos y totales para ver cómo.

Venta al crédito​

Si no indicas la forma de pago, el comprobante se emite al contado. Para una venta al crédito, agrega las cuotas con su importe y fecha de pago. No hace falta indicar el tipo: si hay cuotas, se completa como crédito, y el total del crédito se calcula como la suma de las cuotas.

Las cuotas de este ejemplo suman 354.00, el total de la factura anterior: (2 × 100.00 + 100.00) + 18 % de IGV.

Invoice factura = Invoice.builder()
// ... los mismos campos de la factura anterior
.formaPago(FormaPago.builder()
.cuotas(List.of(
CuotaPago.builder()
.importe(new BigDecimal("200.00"))
.fechaPago(LocalDate.of(2026, 12, 15))
.build(),
CuotaPago.builder()
.importe(new BigDecimal("154.00"))
.fechaPago(LocalDate.of(2027, 1, 15))
.build()))
.build())
.build();
Las cuotas no se validan contra el total

xhandler no comprueba que la suma de las cuotas coincida con el importe del comprobante, pero la SUNAT sí lo valida y rechaza el comprobante si no cuadra. Calcula las cuotas a partir del total que obtienes al crear el documento.

Si quieres indicar el tipo de forma de pago de forma explícita, usa el enum TipoFormaPago: CONTADO o CREDITO en Java y Python, TipoFormaPago::Contado o TipoFormaPago::Credito en Rust, y las constantes TipoFormaPagoContado o TipoFormaPagoCredito en Go.

Boleta​

Una boleta tiene la misma estructura. Usa una serie que empiece con B y, normalmente, un cliente identificado con su DNI (tipo 1 del Catálogo 6).

Invoice boleta = Invoice.builder()
.serieNumero("B001-1") // serie B: boleta (tipo "03")
.proveedor(Proveedor.builder()
.ruc("12345678912")
.razonSocial("Softgreen S.A.C.")
.build())
.cliente(Cliente.builder()
.tipoDocumentoIdentidad("1") // DNI (Catálogo 6)
.numeroDocumentoIdentidad("12345678")
.nombre("Carlos Feria")
.build())
.detalles(List.of(Detalle.builder()
.descripcion("Item")
.cantidad(new BigDecimal("2"))
.precio(new BigDecimal("100.00"))
.build()))
.build();

String xml = new XBuilder().build(boleta);

Diferencias entre lenguajes​

  • Rust separa la creación en dos pasos: enrich(&Defaults) completa los valores por defecto y calcula impuestos y totales, y render() genera el XML. En Java, Python y Go, build hace las dos cosas.
  • Go usa punteros para los campos opcionales: envuélvelos con xbuilder.Ptr(...). Los montos son xbuilder.Decimal (MustDecimal("100.00"), DecimalFromInt(2)) y las fechas xbuilder.NewDate(...).
  • Python valida los modelos al construirlos: un campo con un nombre que no existe falla de inmediato. Usa siempre Decimal para los montos, nunca float.
  • Los códigos de catálogo (tipo de documento, tipo de IGV, etc.) son textos, como "6" o "10". Un código que no existe hace fallar la creación del documento con un error de validación.

Otros campos disponibles​

Invoice también acepta, entre otros: orden de compra (ordenCompra / orden_compra), guías relacionadas, documentos relacionados, detracción, percepción, anticipos, descuentos, cargos y dirección de entrega. Los nombres siguen la misma convención en cada lenguaje (camelCase en Java, snake_case en Rust y Python, PascalCase en Go).

Siguientes pasos​