Referencia de Tools

Resumen

Herramienta	Auth	Descripcion
`crearFactura`	Si	Emitir factura electronica completa
`listarFacturas`	Si	Listar facturas paginadas
`obtenerFactura`	Si	Detalle de factura por UUID
`obtenerFacturaPorCuf`	Si	Detalle de factura por CUF
`anularFactura`	Si	Anular factura ante el SIAT
`verificarEstadoFactura`	Si	Estado actual en el SIAT
`crearNotaCreditoDebito`	Si	Emitir nota credito/debito
`resumenFacturacion`	Si	Dashboard de facturacion
`descargarDocumento`	Si	Descargar PDF, ticket o XML como base64
`verificarFormatoNit`	No	Validar formato NIT
`historialCliente`	Si	Historial de facturacion por NIT
`buscarNormativa`	No	RAG normativa SIAT
`erroresComunesSiat`	No	Errores comunes y soluciones
`buscarContingencias`	No	RAG contingencias
`calcularMontoLiteral`	No	Monto numerico a texto literal

Herramientas de Facturacion

crearFactura

Crea y emite una factura electronica validada por el SIAT. Firma digital, CUF, validacion fiscal, generacion de PDF/XML y envio de email al cliente — todo en una sola llamada.

Parametro	Tipo	Requerido	Descripcion
`requestJson`	String	Si	JSON con los datos de la factura

Requiere autenticacion: Si 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	Descripcion
`pointOfSaleId`	UUID	Identificador del punto de venta registrado en SIAT
`clientDocumentType`	int	`5` = NIT, `1` = CI, `4` = Extranjero
`clientDocumentNumber`	String	Numero de documento del cliente
`clientBusinessName`	String	Razon social o nombre completo
`clientEmail`	String	Email para envio automatico de factura
`paymentMethodCode`	int	`1` = Efectivo, `2` = Tarjeta, `6` = Transferencia
`details`	Array	Lista de items (minimo 1)
`details[].activityEconomic`	String	Codigo CAEB del SIN
`details[].codeProductSin`	String	Codigo producto/servicio catalogo SIN
`details[].description`	String	Descripcion 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	Descripcion
`id`	UUID interno de la factura en CUCU
`invoiceNumber`	Numero secuencial dentro del punto de venta
`cuf`	Codigo Unico de Facturacion — 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 publica para descargar el PDF
`xmlUrl`	URL publica para descargar el XML firmado

listarFacturas

Lista facturas emitidas por el tenant autenticado, paginadas y ordenadas por fecha de emision descendente.

Parametro	Tipo	Requerido	Descripcion
`page`	int	No	Pagina (inicia en 0, default: 0)
`size`	int	No	Elementos por pagina (max 50, default: 10)

Requiere autenticacion: Si Ejemplo de uso con AI:

“Lista mis ultimas 5 facturas”

obtenerFactura

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

Parametro	Tipo	Requerido	Descripcion
`id`	String	Si	UUID de la factura

Requiere autenticacion: Si 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 (Codigo Unico de Factura), el identificador unico ante el SIN.

Parametro	Tipo	Requerido	Descripcion
`cuf`	String	Si	Codigo Unico de Factura

Requiere autenticacion: Si Ejemplo de uso con AI:

“Busca la factura con CUF 2872F729450…”

anularFactura

Anula una factura electronica emitida. La anulacion es irreversible ante el SIAT.

Parametro	Tipo	Requerido	Descripcion
`id`	String	Si	UUID de la factura
`codigoMotivo`	int	Si	1=Error datos, 2=Devolucion, 3=Periodo posterior, 4=Otro

Requiere autenticacion: Si Ejemplo de uso con AI:

“Anula la factura a1b2c3d4… por error de datos”

verificarEstadoFactura

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

Parametro	Tipo	Requerido	Descripcion
`id`	String	Si	UUID de la factura

Requiere autenticacion: Si Ejemplo de uso con AI:

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

crearNotaCreditoDebito

Crea y emite una Nota de Credito o Debito contra una factura original validada. La nota se envia al SIAT para validacion con documento sector 24.

Parametro	Tipo	Requerido	Descripcion
`requestJson`	String	Si	JSON con los datos de la nota

Requiere autenticacion: Si Ejemplo de uso con AI:

“Emite una nota de credito contra la factura a1b2c3d4… por devolucion de Bs. 100”

Show Estructura del JSON de request

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

Campo	Tipo	Descripcion
`pointOfSaleId`	UUID	Punto de venta registrado en SIAT
`originalInvoiceId`	UUID	Factura original contra la que se emite la nota
`notaType`	String	`CREDITO` (devolucion) o `DEBITO` (cargo adicional)
`paymentMethodCode`	int	Metodo de pago
`returnedDetails`	Array	Items devueltos o cargados

resumenFacturacion

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

Parametro	Tipo	Requerido	Descripcion
(ninguno)	-	-	No requiere parametros

Requiere autenticacion: Si Ejemplo de uso con AI:

“Dame un resumen de mi facturacion”

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.

Parametro	Tipo	Requerido	Descripcion
`cuf`	String	Si	Codigo Unico de Factura
`formato`	String	Si	`a4` (PDF A4), `ticket` (PDF 80mm) o `xml`

Requiere autenticacion: Si 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	Descripcion
`formato`	Formato solicitado: `a4`, `ticket` o `xml`
`fileName`	Nombre sugerido para guardar el archivo
`mimeType`	`application/pdf` o `application/xml`
`sizeBytes`	Tamano del documento en bytes
`contentBase64`	Contenido del documento codificado en base64

Herramientas de Utilidades SIAT

verificarFormatoNit

Valida el formato de un NIT boliviano. Los NITs validos tienen 7-15 digitos. El NIT 0 es valido (consumidor final).

Parametro	Tipo	Requerido	Descripcion
`nit`	String	Si	NIT a validar (solo digitos)

Requiere autenticacion: No Ejemplo de uso con AI:

“Verifica si el NIT 1023456789 es valido”

historialCliente

Obtiene el historial de facturacion de un cliente por NIT. Muestra razon social, email, telefono y cantidad de facturas emitidas.

Parametro	Tipo	Requerido	Descripcion
`nit`	String	Si	NIT del cliente

Requiere autenticacion: Si Ejemplo de uso con AI:

“Cual es el historial de facturacion del cliente con NIT 99001?”

buscarNormativa

Busqueda semantica (RAG) en la normativa oficial del SIAT sobre facturacion electronica boliviana.

Parametro	Tipo	Requerido	Descripcion
`consulta`	String	Si	Pregunta o termino de busqueda

Requiere autenticacion: No Ejemplo de uso con AI:

“Como funciona el CUFD segun la normativa?”

erroresComunesSiat

Lista los errores mas comunes del SIAT con sus codigos, descripciones y soluciones recomendadas.

Parametro	Tipo	Requerido	Descripcion
(ninguno)	-	-	No requiere parametros

Requiere autenticacion: No Ejemplo de uso con AI:

“Cuales son los errores mas comunes del SIAT?”

buscarContingencias

Busqueda semantica (RAG) en el historial de contingencias y eventos significativos. Encuentra caidas del SIAT, puntos de venta con problemas, duracion y patrones.

Parametro	Tipo	Requerido	Descripcion
`consulta`	String	Si	Pregunta sobre contingencias

Requiere autenticacion: No Ejemplo de uso con AI:

“Cuantas caidas del SIAT hubo este mes?”

calcularMontoLiteral

Convierte un monto numerico a su representacion en texto literal (requerido por el SIAT en cada factura).

Parametro	Tipo	Requerido	Descripcion
`monto`	double	Si	Monto numerico a convertir

Requiere autenticacion: No Retorno ejemplo: "Quinientos 50/100 Bolivianos" Ejemplo de uso con AI:

“Convierte 1500.75 a texto literal”

Conceptos clave

CUF — Codigo Unico de Facturacion

El CUF es un codigo alfanumerico de ~50 caracteres generado por el SIAT que identifica univocamente cada factura electronica ante el SIN. Es el equivalente a un “DNI” de la factura.

Se genera al momento de emision y no cambia
Es necesario para anulaciones, consultas y descargas publicas
Los endpoints publicos /public/invoice/{cuf}/pdf y /public/invoice/{cuf}/xml usan el CUF como identificador
Ejemplo: 2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74

Contingencia — Facturacion offline

Cuando el SIAT no esta disponible (caida, mantenimiento, problemas de red), CUCU activa el modo contingencia automaticamente:

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 automaticamente 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.

NIT — Formato y validacion

El NIT (Numero de Identificacion Tributaria) boliviano tiene estas reglas:

Longitud: 7 a 15 digitos (solo numeros)
NIT 0: Valido — representa “consumidor final” (Sin nombre)
Validacion: Usa verificarFormatoNit antes de emitir para evitar rechazos del SIAT
Documento tipo 5: En clientDocumentType, el valor 5 = NIT
Los NITs se validan contra el algoritmo oficial del SIN (modulo 11)

Codigos de producto SIN

Cada item en una factura requiere un codeProductSin del catalogo oficial del SIN. Ejemplos comunes:

Codigo	Descripcion
`83141`	Servicios de consultoria en tecnologia
`86101`	Servicios de consultoria en gestion
`46211`	Venta de software
`73119`	Servicios de publicidad
`85960`	Servicios de capacitacion

Usa la herramienta buscarNormativa para consultar codigos especificos.

Unidades de medida SIAT

El campo unitMeasure usa codigos numericos del catalogo SIN:

Codigo	Descripcion
`1`	Unidad
`2`	Kilogramo
`14`	Metro
`57`	Pieza
`58`	Servicio

La unidad mas comun para servicios es 58. Para productos fisicos, usa la unidad que corresponda.

MCP Server

​Resumen

​Herramientas de Facturacion

​crearFactura

​listarFacturas

​obtenerFactura

​obtenerFacturaPorCuf

​anularFactura

​verificarEstadoFactura

​crearNotaCreditoDebito

​resumenFacturacion

​descargarDocumento

​Herramientas de Utilidades SIAT

​verificarFormatoNit

​historialCliente

​buscarNormativa

​erroresComunesSiat

​buscarContingencias

​calcularMontoLiteral

​Conceptos clave

Resumen

Herramientas de Facturacion

crearFactura

listarFacturas

obtenerFactura

obtenerFacturaPorCuf

anularFactura

verificarEstadoFactura

crearNotaCreditoDebito

resumenFacturacion

descargarDocumento

Herramientas de Utilidades SIAT

verificarFormatoNit

historialCliente

buscarNormativa

erroresComunesSiat

buscarContingencias

calcularMontoLiteral

Conceptos clave