Facturación

El ciclo completo de facturación electrónica en 10 herramientas.

crearFactura

Emite una factura electrónica completa. Firma digital, CUF, validación SIAT, PDF/XML y email al cliente. Soporta contingencia automática.

listarFacturas

Lista facturas con filtros por fecha, estado, NIT, número. Paginación incluida. Ideal para reportes y conciliaciones.

obtenerFactura

Detalle completo de una factura: datos fiscales, CUF, estado SIAT, items, montos, impuestos y metadata.

anularFactura

Anula una factura ante el SIAT con motivo del catálogo SIN. Registra la anulación y notifica al cliente.

revertirAnulacion

Revierte la anulación de una factura: CANCELLED → VALIDATED. No aplica a facturas emitidas en modo offline.

obtenerFacturaPorCuf

Obtiene una factura por su CUF (Código Único de Factura), el identificador único ante el SIN.

verificarEstadoFactura

Verifica el estado actual de una factura directamente con el SIAT. Estados: VALIDATED, REJECTED, CANCELLED, PENDING, CONTINGENCY.

crearNotaCreditoDebito

Emite nota de crédito o débito contra una factura validada. Devoluciones parciales o totales con validación SIAT sector 24.

resumenFacturacion

Dashboard de facturación: total facturas, montos, estados, facturas recientes y métricas del periodo.

descargarDocumento

Descarga PDF (A4 o ticket) o XML de una factura como base64. Busca primero en CDN, genera al vuelo si no existe.

crearFactura \

Crea y emite una factura electrónica validada por el SIAT. Firma digital, CUF, validación fiscal, generación de PDF/XML y envío de email al cliente — todo en una sola llamada.

Parámetro	Tipo	Requerido	Descripción
`requestJson`	String	Sí	JSON con los datos de la factura

Requiere autenticación: Sí Ejemplo de uso con AI:

“Emite una factura a DEMO S.R.L. con NIT 99001 por Bs. 500 de servicio de desarrollo”

Show Estructura del JSON de request

{
  "pointOfSaleId": "UUID del POS",
  "clientDocumentType": 5,
  "clientDocumentNumber": "99001",
  "clientBusinessName": "EMPRESA S.R.L.",
  "clientEmail": "email@ejemplo.com",
  "paymentMethodCode": 1,
  "details": [{
    "activityEconomic": "620100",
    "codeProductSin": "83141",
    "description": "Servicio",
    "quantity": 1,
    "unitMeasure": 58,
    "priceUnit": 100.00
  }]
}

Campo	Tipo	Descripción
`pointOfSaleId`	UUID	Identificador del punto de venta registrado en SIAT
`clientDocumentType`	int	`5` = NIT, `1` = CI, `4` = Extranjero
`clientDocumentNumber`	String	Número de documento del cliente
`clientBusinessName`	String	Razón social o nombre completo
`clientEmail`	String	Email para envío automático de factura
`paymentMethodCode`	int	`1` = Efectivo, `2` = Tarjeta, `6` = Transferencia
`details`	Array	Lista de items (mínimo 1)
`details[].activityEconomic`	String	Código CAEB del SIN
`details[].codeProductSin`	String	Código producto/servicio catálogo SIN
`details[].description`	String	Descripción libre del item
`details[].quantity`	Number	Cantidad (acepta decimales)
`details[].unitMeasure`	int	`58` = Servicio, `1` = Unidad, `57` = Pieza
`details[].priceUnit`	Number	Precio unitario en bolivianos

Show Estructura de la respuesta

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoiceNumber": 42,
    "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
    "state": "VALIDATED",
    "clientBusinessName": "EMPRESA S.R.L.",
    "amountTotal": 500.00,
    "literal": "Quinientos 00/100 Bolivianos",
    "emissionDate": "2026-02-26T12:00:00",
    "emissionType": "NORMAL",
    "pdfUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/{cuf}/pdf",
    "xmlUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/{cuf}/xml"
  }
}

Campo	Descripción
`id`	UUID interno de la factura en CUCU
`invoiceNumber`	Número secuencial dentro del punto de venta
`cuf`	Código Único de Facturación — identificador ante el SIN
`state`	`VALIDATED`, `REJECTED`, `ANNULLED`
`amountTotal`	Monto total en bolivianos
`literal`	Monto en texto literal (requerido por normativa)
`emissionType`	`NORMAL` (online) o `CONTINGENCY` (offline)
`pdfUrl`	URL pública para descargar el PDF
`xmlUrl`	URL pública para descargar el XML firmado

listarFacturas \

Lista facturas emitidas por el tenant autenticado, paginadas y ordenadas por fecha de emisión descendente.

Parámetro	Tipo	Requerido	Descripción
`page`	int	No	Página (inicia en 0, default: 0)
`size`	int	No	Elementos por página (max 50, default: 10)

Requiere autenticación: Sí Ejemplo de uso con AI:

“Lista mis últimas 5 facturas”

obtenerFactura \

Obtiene los detalles completos de una factura por UUID, incluyendo datos del cliente, montos, estado SIAT, CUF y código QR.

Parámetro	Tipo	Requerido	Descripción
`id`	String	Sí	UUID de la factura

Requiere autenticación: Sí Ejemplo de uso con AI:

“Muestra los detalles de la factura a1b2c3d4-e5f6-7890-abcd-ef1234567890”

obtenerFacturaPorCuf \

Obtiene los detalles de una factura por su CUF (Código Único de Factura), el identificador único ante el SIN.

Parámetro	Tipo	Requerido	Descripción
`cuf`	String	Sí	Código Único de Factura

Requiere autenticación: Sí Ejemplo de uso con AI:

“Busca la factura con CUF 2872F729450…”

anularFactura \

Anula una factura electrónica emitida. La anulación es irreversible ante el SIAT.

Parámetro	Tipo	Requerido	Descripción
`id`	String	Sí	UUID de la factura
`codigoMotivo`	int	Sí	1=Error datos, 2=Devolución, 3=Período posterior, 4=Otro

Requiere autenticación: Sí Ejemplo de uso con AI:

“Anula la factura a1b2c3d4… por error de datos”

revertirAnulacion \

Revierte la anulación de una factura ante el SIAT. Solo funciona con facturas en estado CANCELLED: la factura vuelve a VALIDATED. No funciona con facturas emitidas en modo offline (contingencia).

Parámetro	Tipo	Requerido	Descripción
`id`	String	Sí	UUID de la factura cuya anulación se quiere revertir

Requiere autenticación: Sí Ejemplo de uso con AI:

“Revierte la anulación de la factura a1b2c3d4…”

verificarEstadoFactura \

Verifica el estado actual de una factura directamente con el SIAT. Estados posibles: VALIDATED, REJECTED, CANCELLED, PENDING, CONTINGENCY.

Parámetro	Tipo	Requerido	Descripción
`id`	String	Sí	UUID de la factura

Requiere autenticación: Sí Ejemplo de uso con AI:

“Verifica el estado de la factura a1b2c3d4… en el SIAT”

crearNotaCreditoDebito \

Crea y emite una Nota de Crédito o Débito contra una factura original validada. Soporta tres sectores de documento de ajuste: 24 (estándar), 47 (Descuento) y 48 (ICE), seleccionados con documentSectorType.

Parámetro	Tipo	Requerido	Descripción
`requestJson`	String	Sí	JSON con los datos de la nota

Requiere autenticación: Sí Ejemplo de uso con AI:

“Emite una nota de crédito contra la factura a1b2c3d4… por devolución de Bs. 100”

Las líneas originales SIEMPRE se clonan de la base de datos — no las re-envíes. Enviar tus propias líneas originales causaba rechazos SIAT [1049] (detalle diferente) y [1030] (monto original erróneo). Solo mandas returnedDetails (los items devueltos).

Show Estructura del JSON de request

{
  "pointOfSaleId": "UUID del POS",
  "originalInvoiceId": "UUID de la factura original",
  "notaType": "CREDITO",
  "documentSectorType": 24,
  "paymentMethodCode": 1,
  "returnedDetails": [{
    "activityEconomic": "620100",
    "codeProductSin": "83141",
    "description": "Devolucion servicio",
    "quantity": 1,
    "unitMeasure": 58,
    "priceUnit": 100.00
  }]
}

Campo	Tipo	Descripción
`pointOfSaleId`	UUID	Punto de venta registrado en SIAT
`originalInvoiceId`	UUID	Factura original contra la que se emite la nota
`notaType`	String	`CREDITO` (devolución) o `DEBITO` (cargo adicional)
`documentSectorType`	int	`24` estándar (default), `47` Descuento, `48` ICE
`paymentMethodCode`	int	Método de pago
`returnedDetails`	Array	Items devueltos o cargados
`originalDetails`	Array	Solo sector 48: overlay ICE minimal por línea original (`nroItem` + `marcaIce` + montos ICE). En 24/47 se ignora

Show Sector 48 (ICE) — overlay minimal

En el sector 48, la base de cada línea original se clona de la BD; en originalDetails solo mandas los datos ICE (la compra-venta original no los almacena):

{
  "documentSectorType": 48,
  "originalDetails": [
    { "nroItem": 1, "marcaIce": 2, "montoIceEspecifico": 0, "montoIcePorcentual": 0 }
  ]
}

Modo estructural: si la factura original no tenía ICE, envía marcaIce: 2 con montos en 0 — la nota se emite con la estructura ICE que exige el XSD pero sin monto ICE real.

resumenFacturacion \

Obtiene un resumen tipo dashboard de la facturación del tenant: total facturas, montos, estados, facturas recientes.

Parámetro	Tipo	Requerido	Descripción
(ninguno)	-	-	No requiere parámetros

Requiere autenticación: Sí Ejemplo de uso con AI:

“Dame un resumen de mi facturación”

descargarDocumento \

Descarga el PDF (A4 o ticket) o XML de una factura como contenido base64. Busca primero en S3 (CDN), si no existe genera el documento al vuelo.

Parámetro	Tipo	Requerido	Descripción
`cuf`	String	Sí	Código Único de Factura
`formato`	String	Sí	`a4` (PDF A4), `ticket` (PDF 80mm) o `xml`

Requiere autenticación: Sí Ejemplo de uso con AI:

“Descarga el PDF de la factura con CUF 2872F729…”

Show Estructura de la respuesta

{
  "success": true,
  "invoiceNumber": 42,
  "cuf": "2872F729...",
  "formato": "a4",
  "fileName": "factura_591164023_42.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 45230,
  "contentBase64": "JVBERi0xLjQK..."
}

Campo	Descripción
`formato`	Formato solicitado: `a4`, `ticket` o `xml`
`fileName`	Nombre sugerido para guardar el archivo
`mimeType`	`application/pdf` o `application/xml`
`sizeBytes`	Tamaño del documento en bytes
`contentBase64`	Contenido del documento codificado en base64

Conceptos clave

CUF — Código Único de Facturación

El CUF es un código alfanumérico de ~50 caracteres generado por el SIAT que identifica unívocamente cada factura electrónica ante el SIN. Es el equivalente a un “DNI” de la factura.

Se genera al momento de emisión y no cambia
Es necesario para anulaciones, consultas y descargas públicas
Los endpoints públicos /public/invoice/{cuf}/pdf y /public/invoice/{cuf}/xml usan el CUF como identificador
Ejemplo: 2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74

Contingencia — Facturación offline

Cuando el SIAT no está disponible (caída, mantenimiento, problemas de red), CUCU activa el modo contingencia automáticamente:

La factura se emite localmente con un CUF temporal
Se almacena en la base de datos con estado CONTINGENCY
Cuando el SIAT vuelve, CUCU sincroniza automáticamente las facturas pendientes
El CUF temporal se reemplaza por el CUF definitivo del SIAT

El AI no necesita hacer nada especial — la contingencia es transparente.

Códigos de producto SIN

Cada item en una factura requiere un codeProductSin del catálogo oficial del SIN. Ejemplos comunes:

Código	Descripción
`83141`	Servicios de consultoría en tecnología
`86101`	Servicios de consultoría en gestión
`46211`	Venta de software
`73119`	Servicios de publicidad
`85960`	Servicios de capacitación

Usa la herramienta buscarNormativa para consultar códigos específicos.

Unidades de medida SIAT

El campo unitMeasure usa códigos numéricos del catálogo SIN:

Código	Descripción
`1`	Unidad
`2`	Kilogramo
`14`	Metro
`57`	Pieza
`58`	Servicio

La unidad más común para servicios es 58. Para productos físicos, usa la unidad que corresponda.

Información General

Las 41 herramientas

Facturación

Facturación

crearFactura

listarFacturas

obtenerFactura

anularFactura

revertirAnulacion

obtenerFacturaPorCuf

verificarEstadoFactura

crearNotaCreditoDebito

resumenFacturacion

descargarDocumento

crearFactura \

listarFacturas \

obtenerFactura \

obtenerFacturaPorCuf \

anularFactura \

revertirAnulacion \

verificarEstadoFactura \

crearNotaCreditoDebito \

resumenFacturacion \

descargarDocumento \

Conceptos clave

​Facturación

crearFactura

listarFacturas

obtenerFactura

anularFactura

revertirAnulacion

obtenerFacturaPorCuf

verificarEstadoFactura

crearNotaCreditoDebito

resumenFacturacion

descargarDocumento

​crearFactura \

​listarFacturas \

​obtenerFactura \

​obtenerFacturaPorCuf \

​anularFactura \

​revertirAnulacion \

​verificarEstadoFactura \

​crearNotaCreditoDebito \

​resumenFacturacion \

​descargarDocumento \

​Conceptos clave

Facturación

crearFactura \

listarFacturas \

obtenerFactura \

obtenerFacturaPorCuf \

anularFactura \

revertirAnulacion \

verificarEstadoFactura \

crearNotaCreditoDebito \

resumenFacturacion \

descargarDocumento \

Conceptos clave