Facturar en Bolivia con CUCU

Esta guía te lleva desde la credencial hasta un flujo completo de venta → factura → PDF para el cliente, usando los nodos cucu*. Si prefieres hablar directo con el SIN, mira la página de Bolivia.

Antes de empezar

1. Crea tu cuenta en CUCU y genera una API key. Empieza con sk_test_ (sandbox) o sk_live_ (producción).
2. En Floogos crea una credencial de tipo Bolivia CUCU y pega la clave. El entorno lo marca el prefijo de la clave: si el campo Entorno de la credencial lo contradice, el nodo se detiene sin enviar nada.
3. Pulsa Probar credencial. Si responde bien, ya puedes usarla en cualquier nodo cucu*.
4. Opcional: indica el punto de venta por defecto y el secreto de webhooks (webhook_secret) si vas a recibir eventos.

Consejo

Empieza siempre con una clave sk_test_: el sandbox usa el SIAT piloto y las facturas no tienen validez tributaria.

Caso 1: emitir una factura de venta

Flujo mínimo: Webhook / Formulario → cucuEmitirFactura → cucuDocumento.

En cucuEmitirFactura:

Campo	Valor de ejemplo
document_sector	1 (compra y venta)
client_document_number	{{nit_cliente}}
client_business_name	{{razon_social}}
details	[{"description":"Servicio de desarrollo","quantity":1,"priceUnit":500}]
default_activity_economic	620100 (tu CAEB)
default_code_product_sin	83141
default_unit_measure	58 (servicio)
idempotency_mode	auto
output_key	cucu

El nodo valida los datos antes de llamar a la API y, si todo es correcto, devuelve en data.cucu:

• invoice.cuf, invoice.invoiceNumber y invoice.state (VALIDATED cuando el SIN la aceptó).
• urls.pdf, urls.xml y urls.verify (enlace público de verificación).
• totals_check: compara el total que esperabas con el que calculó el SIAT.
• replayed: true si fue un reintento y CUCU devolvió la factura ya emitida.

Para enviar el PDF, añade cucuDocumento con operation: email y cuf: {{data.cucu.invoice.cuf}}, o usa download si quieres el archivo para adjuntarlo por otro canal. También puedes rellenar client_email en la emisión y CUCU le envía la factura por correo.

Caso 2: usar el nombre oficial del padrón

Si el cliente solo da su NIT, valida antes de emitir para que la razón social coincida con la del padrón:

1. cucuValidarCliente con operation: padron, document_type: 5, document_number: {{nit_cliente}} y output_key: cliente.
2. En cucuEmitirFactura, usa client_business_name: {{data.cliente.business_name}}.

Caso 3: no duplicar facturas en los reintentos

Cada emisión lleva una cabecera Idempotency-Key:

• auto (recomendado): la clave se calcula con la ejecución, el nodo y el contenido de la factura. Si el workflow se reintenta tras un corte de red, CUCU devuelve la factura ya emitida (replayed: true).
• manual: escribe tú la clave, por ejemplo el id del pedido ({{pedido_id}}). Úsala dentro de un bucle, donde dos facturas pueden ser idénticas.
• off: sin clave. Un timeout o un error 5xx no se reintenta, porque podría duplicar la factura. Solo se reintenta ante un 429 (límite de peticiones).

Caso 4: devolución parcial (nota de crédito)

Usa cucuNotaCreditoDebito:

• cuf: la factura original.
• nota_type: CREDITO o DEBITO.
• document_sector: 24 para la nota de crédito/débito.
• returned_details: solo las líneas devueltas.
• precheck: true comprueba las cifras antes de enviar al SIAT.

Caso 5: anular una factura

cucuAnular con el cuf de la factura y un motivo del catálogo cancellation-reasons (consúltalo con cucuCatalogo).

Caso 6: lotes y emisión masiva

• cucuEmitirLote: varias facturas en una sola llamada.
• cucuEmisionMasiva: grandes volúmenes; consulta el resultado después con cucuConsultar.

Separa siempre los dos pasos (emitir y consultar) en el workflow y guarda qué quedó emitido para reintentar solo lo pendiente. Más patrones en Emisión masiva.

Caso 7: el SIAT está caído

Con cucuContingencia registras el evento de contingencia, emites en modo offline y envías el paquete cuando el SIN vuelva. Los eventos 5, 6 y 7 exigen un CAFC, que se solicita al SIN. cucuCufd permite consultar o renovar la CUFD del punto de venta.

Caso 8: recibir webhooks de CUCU

1. Crea un workflow con un disparador Webhook y registra su URL en CUCU (también puedes hacerlo con cucuWebhooks). Guarda el secreto del webhook en la credencial.
2. Como primer nodo, pon cucuVerificarWebhook: sin configurar nada usa las cabeceras y el cuerpo originales de la petición recibida y comprueba la firma (Standard Webhooks).
3. Continúa solo si la firma es válida. Con tolerance_seconds puedes rechazar eventos demasiado antiguos (0 = no comprobar).

Errores frecuentes

Síntoma	Causa y solución
El nodo se detiene sin enviar	La clave (sk_test_/sk_live_) contradice el entorno de la credencial. Corrige uno de los dos.
Rechazo del SIAT por totales	Revisa totals_check y additional_discount: el SIAT valida total = Σ subtotales − descuento adicional.
Faltan campos del sector	Cada sector exige sus propios datos en sector_fields (alquiler, servicio básico, hospital…). El mensaje del nodo indica cuáles faltan.
Sectores 3 y 9	La documentación de CUCU los marca solo para sandbox.

Nodos de esta guía

cucuEmitirFactura · cucuDocumento · cucuValidarCliente · cucuNotaCreditoDebito · cucuAnular · cucuEmitirLote · cucuEmisionMasiva · cucuConsultar · cucuContingencia · cucuCufd · cucuCatalogo · cucuAdministrar · cucuWebhooks · cucuVerificarWebhook