Cálculos automáticos
Al crear un comprobante solo describes lo esencial: serie y número, proveedor, cliente e ítems. Antes de generar el XML, xhandler enriquece el documento: completa los valores por defecto y calcula impuestos y totales. A este paso se le llama enrich.
Qué se completa y se calcula
Solo se completa lo que no indicaste. Si das un valor, se respeta.
Datos del comprobante
- Fecha de emisión: la fecha de hoy en Perú (UTC-5). En Rust, la fecha que pasas en
Defaults. - Moneda: soles (
PEN). - Tipo de comprobante: según la serie;
F001es factura (01) yB001es boleta (03). - Tipo de operación: venta interna (
0101). - Forma de pago: contado.
- Firmante: los datos del proveedor.
- Tasas: las tasas vigentes de la SUNAT para IGV, ICBPER e IVAP.
Datos de cada ítem
- Unidad de medida (
NIU) y tipo de IGV (10, gravado - operación onerosa). - Precio con y sin impuestos, a partir del que indicaste.
- Base imponible, IGV, ISC, ICBPER y total de impuestos del ítem.
Totales
- Importe sin impuestos, con impuestos e importe total.
- Totales de impuestos por tipo de operación (gravadas, exoneradas, inafectas, gratuitas, exportación, IVAP) e importes de ISC e ICBPER.
Leyendas
Se agregan las leyendas que dependen de los datos del comprobante, por ejemplo cuando hay detracción, percepción u operaciones sujetas a IVAP.
xhandler no agrega la leyenda 1000 (monto en letras). Si la necesitas, agrégala tú en el campo leyendas del comprobante, un mapa de código a texto.
Lo que no se calcula
En el resumen diario, la percepción y la retención los importes no se calculan: debes indicarlos tú. Revisa Resumen diario y Percepciones y retenciones.
Revisar el documento calculado
Crear el XML no modifica tu documento. Para ver los valores calculados sin leer el XML, usa enrich: aplica exactamente los mismos cálculos que se usan al generar el XML.
- Java
- Rust
- Python
- Go
enrich devuelve una copia del documento; el original no cambia.
Invoice enriched = new XBuilder().enrich(invoice);
enriched.getMoneda(); // "PEN"
enriched.getFechaEmision(); // hoy en Perú
enriched.getTipoComprobante(); // "01"
enriched.getTotalImporte().getImporteSinImpuestos(); // 200
enriched.getTotalImporte().getImporte(); // 236.00
enriched.getTotalImpuestos().getTotal(); // 36.00
Detalle detalle = enriched.getDetalles().get(0);
detalle.getIgvTipo(); // "10"
detalle.getPrecioConImpuestos(); // 118.00
detalle.getIgv(); // 36.00
Compara los BigDecimal con compareTo, no con equals: la escala puede variar (200 o 200.00).
En Rust, enrich modifica el documento en su lugar. Debes llamarlo antes de render().
invoice.enrich(&Defaults::new(chrono::Local::now().date_naive()))?;
println!("{:?}", invoice.moneda); // Some("PEN")
println!("{:?}", invoice.tipo_operacion); // Some("0101")
if let Some(total) = &invoice.total_importe {
println!("{} {}", total.importe_sin_impuestos, total.importe);
}
if let Some(impuestos) = &invoice.total_impuestos {
println!("{}", impuestos.total);
}
let detalle = &invoice.detalles[0];
println!("{:?} {:?} {:?}", detalle.igv_tipo, detalle.precio_con_impuestos, detalle.igv);
let xml = invoice.render()?;
Todos los modelos implementan Serialize, así que puedes ver el documento completo como JSON con serde_json.
enrich devuelve un nuevo documento del mismo tipo; el original no cambia.
from decimal import Decimal
from xhandler import xbuilder
enriched = xbuilder.enrich(invoice)
print(enriched.moneda) # PEN
print(enriched.fecha_emision) # hoy en Perú
print(enriched.tipo_comprobante) # 01
print(enriched.forma_pago.tipo) # TipoFormaPago.CONTADO
assert enriched.total_importe.importe == Decimal("236")
assert enriched.total_impuestos.total == Decimal("36")
detalle = enriched.detalles[0]
print(detalle.igv_tipo, detalle.precio_con_impuestos, detalle.igv)
Compara los Decimal por valor (==): la escala puede variar (236 o 236.00).
Enrich devuelve una copia del mismo tipo (*xbuilder.Invoice); el original no cambia.
enriched, err := xbuilder.Enrich(ctx, invoice, xbuilder.Defaults{})
if err != nil {
return err
}
fmt.Println(*enriched.Moneda) // PEN
fmt.Println(*enriched.FechaEmision) // hoy en Perú
fmt.Println(enriched.TotalImporte.Importe) // 236.00
fmt.Println(enriched.TotalImpuestos.GravadoImporte) // 36.00
for _, d := range enriched.Detalles {
fmt.Println(*d.IgvTipo, *d.PrecioConImpuestos, *d.Igv)
}
// Comparar importes
if enriched.TotalImporte.Importe.Equal(xbuilder.MustDecimal("236").Decimal) {
fmt.Println("ok")
}
// Ver todo el documento calculado
b, err := json.MarshalIndent(enriched, "", " ")
if err != nil {
return err
}
fmt.Println(string(b))
Los valores de los comentarios corresponden a un ítem de cantidad 2 y precio 100.00 con IGV del 18 %.
Cambiar la fecha y las tasas: Defaults
Defaults define los valores que se usan cuando el documento no los indica. Tiene cuatro campos:
| Campo | Qué es | Valor por defecto |
|---|---|---|
| Fecha de emisión | Fecha del comprobante | Hoy en Perú (UTC-5) |
| Tasa de IGV | Fracción, 0.18 = 18 % | Tasa vigente de la SUNAT |
| Tasa de ICBPER | Monto en soles por bolsa plástica | Tasa vigente de la SUNAT |
| Tasa de IVAP | Fracción, 0.04 = 4 % | Tasa vigente de la SUNAT |
Escribe 0.18, no 18. La única excepción es la tasa de IGV de los ítems del resumen diario, que es un porcentaje (18).
- Java
- Rust
- Python
- Go
import io.github.project.openubl.xbuilder.models.Defaults;
Defaults defaults = Defaults.builder()
.fechaEmision(LocalDate.of(2026, 11, 15))
.igvTasa(new BigDecimal("0.18"))
.icbTasa(new BigDecimal("0.50"))
.ivapTasa(new BigDecimal("0.04"))
.build(); // todos los campos son opcionales
// Para todos los documentos de un XBuilder (reutilizable y thread-safe)
XBuilder xbuilder = new XBuilder(defaults);
String xml = xbuilder.build(invoice);
// O en cada llamada
String xml2 = new XBuilder().build(invoice, defaults);
Invoice enriched = new XBuilder().enrich(invoice, defaults);
Defaults es obligatorio en Rust. Defaults::new(fecha) usa las tasas vigentes; también puedes indicar todos los campos:
use chrono::NaiveDate;
use rust_decimal_macros::dec;
// Tasas vigentes, con la fecha que indiques
let defaults = Defaults::new(chrono::Local::now().date_naive());
// O todos los valores
let defaults = Defaults {
fecha_emision: NaiveDate::from_ymd_opt(2026, 11, 15).unwrap(),
igv_tasa: dec!(0.18),
icb_tasa: dec!(0.5),
ivap_tasa: dec!(0.04),
};
invoice.enrich(&defaults)?;
let xml = invoice.render()?;
chrono::Local usa la zona horaria del servidor. Si tu servidor no está en hora de Perú, calcula tú la fecha.
from datetime import date
from decimal import Decimal
from xhandler import xbuilder
defaults = xbuilder.Defaults(
fecha_emision=date(2026, 11, 15),
igv_tasa=Decimal("0.18"),
icb_tasa=Decimal("0.50"),
ivap_tasa=Decimal("0.04"),
) # todos los campos son opcionales
xml = xbuilder.build(invoice, defaults)
enriched = xbuilder.enrich(invoice, defaults)
defaults := xbuilder.Defaults{
FechaEmision: xbuilder.Ptr(xbuilder.NewDate(2026, time.November, 15)),
IgvTasa: xbuilder.Ptr(xbuilder.MustDecimal("0.18")),
IcbTasa: xbuilder.Ptr(xbuilder.MustDecimal("0.50")),
IvapTasa: xbuilder.Ptr(xbuilder.MustDecimal("0.04")),
} // todos los campos son opcionales; xbuilder.Defaults{} usa los valores por defecto
xml, err := xbuilder.Build(ctx, invoice, defaults)
if err != nil {
return err
}
enriched, err := xbuilder.Enrich(ctx, invoice, defaults)
Prioridad
Si un valor se indica en varios lugares, gana el más específico:
- El ítem (por ejemplo, la tasa de IGV de un
Detalle). - El documento (la fecha de emisión o la tasa de IGV del
Invoice). Defaults.
Así puedes fijar la fecha o una tasa para un solo comprobante sin cambiar Defaults.
La fecha por defecto depende del reloj. En tus pruebas, fija la fecha de emisión en Defaults o en el documento para obtener siempre el mismo XML.