Facturar en Bolivia con factura.bo

Esta guía recorre el uso de los nodos facturaBo* (proveedor factura.bo de SimplifyIT S.R.L.): desde la credencial hasta emitir, corregir, anular y conciliar. La referencia de cada campo está en la ficha de cada nodo y el resumen del país en la página de Bolivia.

Antes de empezar

1. En app.factura.bo → Más → API Key genera tu clave.
2. En Floogos crea una credencial Bolivia factura.bo con la clave, el entorno (sandbox o producción), tu NIT y el código de sistema del SIAT. Opcional: sucursal y punto de venta por defecto (0 = casa matriz / punto principal) y el secreto de webhooks (whsec_…).
3. Pulsa Probar credencial.

Precaución

La clave de factura.bo no delata el entorno: lo decide el campo Entorno de la credencial, que por defecto es sandbox. Revísalo antes de pasar a producción. En sandbox nunca se envían emails.

Caso 1: emitir una factura

Flujo: Disparador → facturaBoEmitirFactura → facturaBoDocumento.

Campo	Valor de ejemplo
document_sector	1 (compra y venta)
client_document_number	{{nit_cliente}}
client_business_name	{{razon_social}}
client_email	{{email}} (factura.bo envía el PDF al cliente)
items	[{"codigo_producto":"SERV-1","codigo_sin":83141,"descripcion":"Servicio de desarrollo","cantidad":1,"precio_unitario":500,"unidad_medida":58}]
idempotency_mode	auto
output_key	facturabo

Resultado en data.facturabo: invoice.cuf, invoice.invoice_number, invoice.state (EMITIDA) y los enlaces url_public, url_pdf, url_xml y url_ticket. Para reenviar el PDF más tarde, usa facturaBoDocumento con operation: email y cuf: {{data.facturabo.invoice.cuf}}.

Las líneas aceptan los nombres de factura.bo (descripcion, cantidad, precio_unitario…) y también sus equivalentes en inglés. Lo que falte lo completan los valores por defecto del nodo (default_codigo_sin, default_unit_measure, default_activity).

Caso 2: elegir el sector

factura.bo tiene un endpoint por cada uno de sus 12 sectores y el nodo valida los datos propios de cada uno antes de llamar a la API. Van en sector_fields, salvo los del comprador:

Sector	Datos propios
1 Compra y venta	—
2 Alquiler de inmueble	periodo_facturado
6 Turismo y hospedaje, 16 Hotel	fecha_ingreso, cantidad_huespedes, cantidad_habitaciones
13 Servicio básico	mes, gestion, numero_medidor, domicilio_cliente, consumo_periodo
3, 4, 28 Exportaciones	client_country_code y client_address del comprador
8, 11, 14, 17	Tasa cero, educativo, ICE, hospital y clínica

La ficha de facturaBoEmitirFactura lista los campos obligatorios de cada sector.

Caso 3: facturar en dólares

1. facturaBoTipoCambio con operation: current y output_key: tc.
2. En la emisión: currency_code: 2 y exchange_rate: {{data.tc.data.USD}}.

Caso 4: validar el NIT antes de emitir

facturaBoValidarNit con nit: {{nit_cliente}} comprueba el NIT. Si no es válido, deriva el flujo a una rama de error en lugar de emitir y recibir un rechazo.

Caso 5: no duplicar facturas

Cada emisión lleva X-Idempotency-Key (hasta 128 caracteres; las claves se recuerdan 30 días):

• auto: derivada de la ejecución, el nodo y el contenido. Un reintento devuelve la factura ya emitida.
• manual: tu propia clave, p. ej. {{pedido_id}}; imprescindible en bucles con facturas idénticas.
• off: sin clave, un timeout o un 5xx no se reintenta para no duplicar.

Caso 6: nota de crédito/débito

facturaBoNota:

• operation: from_invoice con el cuf de la factura y note_sector: 24. En returned_items indica solo lo devuelto, p. ej. [{"nro_item_original":1,"cantidad":1}]. El monto efectivo de la nota es el 13 % de lo devuelto.
• available lista las facturas sobre las que se puede emitir una nota.
• manual crea la nota sin partir de una factura.
• La clave de idempotencia es obligatoria en este endpoint; con el modo auto el nodo la genera por ti.

Caso 7: anular

facturaBoAnular con operation: cancel, el cuf y un motivo del catálogo motivos_anulacion (lo obtienes con facturaBoCatalogo). La operación revert está disponible para revertir una anulación.

Caso 8: lotes, consultas y reportes

• facturaBoEmitirLote para varias facturas.
• facturaBoConsultar para listar o recuperar facturas.
• facturaBoReportes para el Libro de Ventas (RCV) y el respaldo mensual.

Caso 9: el SIAT está caído (contingencia)

Con facturaBoContingencia, en cuatro pasos:

1. start_event después del corte: la fecha de fin del evento no puede estar en el futuro en hora de Bolivia ni solaparse con otro evento.
2. Emite con contingency activado: las facturas quedan OFFLINE.
3. send_package (máximo 500 facturas).
4. validate_package con el código de recepción. Solo entonces pasan a EMITIDA y descuentan crédito.

Los eventos 5, 6 y 7 exigen un CAFC que se pide al SIN; se indica en el campo cafc de la emisión. Con list_events consultas los eventos registrados.

Caso 10: webhooks

1. Registra la URL de un disparador Webhook con facturaBoWebhooks (create; la URL debe ser https y responder 2xx en menos de 10 s). Con rotate_secret y test rotas el secreto y pruebas la entrega.
2. Primer nodo del workflow: facturaBoVerificarWebhook. Sin configurar nada usa el secreto de la credencial y la petición recibida.
3. Sigue solo si la firma es válida.

Consejos ante errores del SIAT

El nodo traduce los códigos más habituales del SIAT a una indicación concreta:

Código	Qué hacer
123	CUFD vencido (dura 24 h): sincroniza.
981	Evento con fecha de fin futura o solapado: regístralo después del corte y sin solapes.
984	La CUFD no corresponde a la ventana del evento: sincroniza y reintenta.
902	Falta el CAFC (eventos 5, 6 y 7).
1040	La fecha de emisión está fuera del rango del evento.
1047	El número de factura excede el rango del CAFC: pide uno nuevo al SIN.
954	El paquete supera las 500 facturas.
1002 / 1006	El CUF o la CUFD del paquete no coinciden: no mezcles eventos ni CUFD.
1049	En una nota, la línea con codigo_detalle_transaccion=1 debe replicar exactamente la original.

Nodos de esta guía

facturaBoEmitirFactura · facturaBoEmitirLote · facturaBoNota · facturaBoAnular · facturaBoConsultar · facturaBoDocumento · facturaBoValidarNit · facturaBoCatalogo · facturaBoAdministrar · facturaBoContingencia · facturaBoWebhooks · facturaBoVerificarWebhook · facturaBoTipoCambio · facturaBoReportes