Facturación

Convenciones de salida y errores: Guía para agentes.

Tool	Propósito	Efecto
`crearFactura`	Emite una factura validada por el SIAT	Emite documento fiscal
`previsualizarFactura`	Montos, IVA, XML y validaciones sin emitir	Lectura (sin efectos)
`listarFacturas`	Lista paginada, más recientes primero	Lectura
`obtenerFactura`	Detalle por UUID	Lectura
`obtenerFacturaPorCuf`	Detalle por CUF	Lectura
`anularFactura`	Anula ante el SIAT	Cambia estado a `CANCELLED`
`revertirAnulacion`	`CANCELLED` → `VALIDATED`	Cambia estado
`verificarEstadoFactura`	Consulta el estado al SIAT y lo actualiza	Lectura contra SIAT
`crearNotaCreditoDebito`	Nota de crédito o débito contra una factura	Emite documento fiscal
`resumenFacturacion`	Totales y desglose por estado y mes	Lectura
`descargarDocumento`	Link temporal de descarga (A4, ticket, ticketsiat, chititicket, XML, ZIP)	Lectura

crearFactura

Parámetro	Tipo	Req	Descripción
`factura`	objeto	Sí	`CreateInvoiceRequest` (mismo body que `POST /api/v3/invoices`), tipado en el `inputSchema`
`idempotencyKey`	string	No	Misma regla que el header `Idempotency-Key`: repetir devuelve la misma factura

Campos de factura (los dominios cerrados llegan como enum en tools/list):

Campo	Tipo	Req	Descripción
`pointOfSaleId`	UUID	Sí	Punto de venta
`clientDocumentType`	int	Sí	`1` CI, `2` CEX, `3` PAS, `4` OD, `5` NIT
`clientDocumentNumber`	string	Sí	Número de documento (NIT `0` = consumidor final)
`clientBusinessName`	string	Sí	Razón social o nombre
`paymentMethodCode`	int	Sí	Catálogo SIAT: `1` Efectivo, `2` Tarjeta, `6` Transferencia…
`details[]`	array	Sí	Mínimo 1 ítem: `activityEconomic`, `codeProductSin`, `description`, `quantity`, `unitMeasure` (`58` Servicio, `1` Unidad, `57` Pieza), `priceUnit`
`clientEmail`	string	No	Destino del correo con PDF y XML
`clientComplement`	string	No	Complemento del CI
`clientCode`	string	No	Código de cliente propio (máx. 100); si falta se usa `clientDocumentNumber`
`cardNumber`	string	No	Para pago con tarjeta
`observations`	string	No	Texto libre
`exchangeRate`	number	No	Tipo de cambio si no es Bs
`isTicket`	boolean	No	Marca el documento como ticket
`documentSectorType`	int	No	Sector; default: el del POS

Salida (JSON en el texto):

{
  "success": true,
  "invoiceId": "a1b2c3d4-...",
  "invoiceNumber": 42,
  "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
  "siatState": "VALIDATED",
  "siatCodeState": 908,
  "siatDescription": "VALIDADA",
  "emissionType": "ONLINE",
  "clientBusinessName": "EMPRESA S.R.L.",
  "clientDocumentNumber": "99001",
  "amountSubtotal": 500.00,
  "amountDiscount": 0,
  "amountTotal": 500.00,
  "amountLiteral": "Quinientos 00/100 Bolivianos",
  "emissionDate": "2026-02-26T12:00:00",
  "qrCode": "https://...",
  "documents": {
    "a4": "https://sandbox.cucu.bo/api/v3/invoices/{id}/documents/a4",
    "ticket": "https://sandbox.cucu.bo/api/v3/invoices/{id}/documents/ticket",
    "ticketsiat": "https://sandbox.cucu.bo/api/v3/invoices/{id}/documents/ticketsiat",
    "xml": "https://sandbox.cucu.bo/api/v3/invoices/{id}/documents/xml",
    "zip": "https://sandbox.cucu.bo/api/v3/invoices/{id}/documents/zip"
  },
  "verificationUrl": "https://siat.impuestos.gob.bo/consulta/QR?nit=...&cuf={cuf}&numero=...&t=2"
}

documents se descarga con la API Key (documentos); para un link que una persona pueda abrir, descargarDocumento. Errores: Error parseando JSON: <detalle> (texto) · {"success": false, "error": "[<CODIGO>] <mensaje>"} para validación y rechazos SIAT (VALIDATION_ERROR, SIAT_ERROR, SECTOR_NOT_SUPPORTED, etc.; catálogo). Efecto: emite un documento fiscal. Tras un timeout no reintentar a ciegas: buscar primero con listarFacturas u obtenerFacturaPorCuf.

previsualizarFactura

Como crearFactura pero sin emitir: no numera, no guarda, no toca el SIN.

Parámetro	Tipo	Req	Descripción
`factura`	objeto	Sí	El mismo `CreateInvoiceRequest` que `crearFactura`

Salida: JSON igual a data de POST /api/v3/invoices/preview. Errores: Error: <mensaje> con los mismos códigos que crearFactura.

listarFacturas

Parámetro	Tipo	Req	Descripción
`page`	int	Sí	Base 0; negativo → `0`
`size`	int	Sí	Máximo 50 (mayor → `50`); `0` o negativo → `20`

Salida (texto): Facturas (pagina P, n de T total): y una línea por factura - #<nro> | CUF: <cuf> | Estado: <estado> | Cliente: <nombre> (<doc>) | Total: <monto> Bs | Fecha: <fecha>. Sin resultados: No se encontraron facturas. Total: 0. Orden: fecha de emisión descendente.

obtenerFactura

Parámetro	Tipo	Req	Descripción
`id`	string	Sí	UUID de la factura

Salida (texto): Factura #<nro> y líneas - ID, - CUF, - Estado SIAT: <estado> (codigo: <n>, desc: <texto>), - Tipo emision, - Cliente: <nombre> (Doc: <doc>, Email: <email>), - Subtotal, - Descuento, - Total, - Literal, - Fecha emision, - QR. Errores: Error: UUID invalido: <id> · Factura no encontrada con ID: <id> (también para facturas de otro tenant).

obtenerFacturaPorCuf

Parámetro	Tipo	Req	Descripción
`cuf`	string	Sí	Código Único de Facturación

Salida: igual que obtenerFactura. Error: Factura no encontrada con CUF: <cuf>.

anularFactura

Anula ante el SIAT una factura o una nota de crédito/débito (gemela de POST /invoices/{id}/cancel): cada documento va al servicio del SIAT que le corresponde. Solo sobre VALIDATED/ACCEPTED.

Parámetro	Tipo	Req	Descripción
`id`	string	Sí	UUID de la factura o de la nota
`codigoMotivo`	int	Sí	`1` error de datos, `2` devolución, `3` período posterior, `4` otros

Salida (texto): Factura anulada exitosamente: + detalle de la factura (mismo formato que obtenerFactura). Errores: Error: UUID invalido: <id> · [<CODIGO>] <mensaje> (p. ej. factura inexistente o en estado no anulable). Efecto: estado CANCELLED ante el SIAT; se deshace con revertirAnulacion.

revertirAnulacion

Parámetro	Tipo	Req	Descripción
`id`	string	Sí	UUID de la factura en `CANCELLED`

Salida: Anulacion revertida exitosamente: + detalle. Aplica también a facturas emitidas offline (contingencia / CAFC). Efecto: vuelve a VALIDATED.

verificarEstadoFactura

Gemela de GET /api/v3/invoices/{id}/status: sirve para facturas y notas de crédito/débito.

Parámetro	Tipo	Req	Descripción
`id`	string	Sí	UUID de la factura o de la nota

Salida: Estado verificado: + detalle. Un [924] en la descripción SIAT significa que el SIN no tiene la factura (ver regularizarFacturasFueraDeEvento).

crearNotaCreditoDebito

Nota de crédito o débito contra una factura VALIDATED. Sectores 24 (estándar, default), 47 (Descuento) y 48 (ICE).

Parámetro	Tipo	Req	Descripción
`nota`	objeto	Sí	`CreateCreditDebitNoteRequest` (mismo body que `POST /api/v3/invoices/{id}/credit-note`, con `originalInvoiceId`)
`idempotencyKey`	string	No	Igual que en `crearFactura`

Campo	Tipo	Req	Descripción
`originalInvoiceId`	UUID	Sí	Factura original
`pointOfSaleId`	UUID	Sí	Punto de venta
`notaType`	string	Sí	`CREDITO` o `DEBITO`
`paymentMethodCode`	int	Sí	Catálogo SIAT
`documentSectorType`	int	No	`24` (default), `47`, `48`
`returnedDetails[]`	array	Sí	Ítems devueltos/cargados: `activityEconomic`, `codeProductSin`, `description`, `quantity`, `unitMeasure`, `priceUnit`, `amountDiscount`; `marcaIce` si sector 48
`originalDetails[]`	array	Solo 48	Overlay ICE por línea original, por posición: `{ nroItem, marcaIce (1 considera ICE, 2 no), montoIceEspecifico, montoIcePorcentual }`

No reenvíes las líneas originales: se clonan de la base (si no, rechazos [1049] y [1030]). Sector 48 sin ICE: marcaIce: 2 y montos 0. Salida (texto): Nota Credito/Debito creada exitosamente: + Nota <CREDITO|DEBITO> #<nro> con líneas - ID, - CUF, estado, montos. Errores: Error parseando JSON: ... · [<CODIGO>] <mensaje>. Efecto: emite un documento fiscal.

resumenFacturacion

Sin parámetros. Salida (texto): === Resumen de Facturacion === con Total facturas, Facturas este mes, Monto total este mes, Monto total este anio, Offline pendientes, Anuladas este mes, bloque --- Por estado --- (<ESTADO>: <n>) y --- Montos por mes (ultimos 6) --- (<yyyy-MM>: <monto> Bs).

descargarDocumento

Parámetro	Tipo	Req	Descripción
`cuf`	string	Sí	CUF de la factura
`formato`	string	No	`a4` (default; alias `pdf`, `A4 PDF`), `ticket`, `ticketsiat`, `chititicket`, `xml`, `zip`. Sin distinguir mayúsculas

Devuelve un link temporal: descarga el archivo con GET al download_url (sin credencial) y adjúntalo. Salida (JSON):

{ "success": true, "invoiceNumber", "cuf", "formato", "fileName", "mimeType", "download_url" (absoluta), "expires_at" (ISO-8601 UTC), "max_uses" }

. Vence a los 300 s y admite 3 usos (link temporal). Errores (JSON { "success": false, "error" }): Formato no soportado: <X>. Validos: … · Factura no encontrada con CUF: <cuf> · La factura no tiene documento en su estado actual (<ESTADO>). Efecto: lectura; emite un link nuevo en cada llamada.

Conexión

Herramientas

Facturación

crearFactura

previsualizarFactura

listarFacturas

obtenerFactura

obtenerFacturaPorCuf

anularFactura

revertirAnulacion

verificarEstadoFactura

crearNotaCreditoDebito

resumenFacturacion

descargarDocumento

​crearFactura

​previsualizarFactura

​listarFacturas

​obtenerFactura

​obtenerFacturaPorCuf

​anularFactura

​revertirAnulacion

​verificarEstadoFactura

​crearNotaCreditoDebito

​resumenFacturacion

​descargarDocumento

crearFactura

previsualizarFactura

listarFacturas

obtenerFactura

obtenerFacturaPorCuf

anularFactura

revertirAnulacion

verificarEstadoFactura

crearNotaCreditoDebito

resumenFacturacion

descargarDocumento