> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.

# Facturación

> Las 9 herramientas MCP para el ciclo completo de facturación electrónica boliviana.

## Facturación

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

<CardGroup cols={2}>
  <Card title="crearFactura" icon="file-invoice" href="#crearfactura">
    Emite una factura electrónica completa. Firma digital, CUF, validación SIAT,
    PDF/XML y email al cliente. Soporta contingencia automática.
  </Card>

  <Card title="listarFacturas" icon="list" href="#listarfacturas">
    Lista facturas con filtros por fecha, estado, NIT, número.
    Paginación incluida. Ideal para reportes y conciliaciones.
  </Card>

  <Card title="obtenerFactura" icon="magnifying-glass" href="#obtenerfactura">
    Detalle completo de una factura: datos fiscales, CUF, estado SIAT,
    items, montos, impuestos y metadata.
  </Card>

  <Card title="anularFactura" icon="ban" href="#anularfactura">
    Anula una factura ante el SIAT con motivo del catálogo SIN.
    Registra la anulación y notifica al cliente.
  </Card>

  <Card title="obtenerFacturaPorCuf" icon="qrcode" href="#obtenerfactuporcuf">
    Obtiene una factura por su CUF (Código Único de Factura),
    el identificador único ante el SIN.
  </Card>

  <Card title="verificarEstadoFactura" icon="circle-check" href="#verificarestadofactura">
    Verifica el estado actual de una factura directamente con el SIAT.
    Estados: VALIDATED, REJECTED, CANCELLED, PENDING, CONTINGENCY.
  </Card>

  <Card title="crearNotaCreditoDebito" icon="file-circle-minus" href="#crearnota">
    Emite nota de crédito o débito contra una factura validada.
    Devoluciones parciales o totales con validación SIAT sector 24.
  </Card>

  <Card title="resumenFacturacion" icon="chart-pie" href="#resumenfacturacion">
    Dashboard de facturación: total facturas, montos, estados,
    facturas recientes y métricas del periodo.
  </Card>

  <Card title="descargarDocumento" icon="download" href="#descargardocumento">
    Descarga PDF (A4 o ticket) o XML de una factura como base64.
    Busca primero en CDN, genera al vuelo si no existe.
  </Card>
</CardGroup>

***

<h2 id="crearfactura\">
  crearFactura \\
</h2>

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"

<Expandable title="Estructura del JSON de request">
  ```json theme={"system"}
  {
    "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                       |
</Expandable>

<Expandable title="Estructura de la respuesta">
  ```json theme={"system"}
  {
    "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               |
</Expandable>

***

<h2 id="listarfacturas\">
  listarFacturas \\
</h2>

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"

***

<h2 id="obtenerfactura\">
  obtenerFactura \\
</h2>

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"

***

<h2 id="obtenerfactuporcuf\">
  obtenerFacturaPorCuf \\
</h2>

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

***

<h2 id="anularfactura\">
  anularFactura \\
</h2>

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"

***

<h2 id="verificarestadofactura\">
  verificarEstadoFactura \\
</h2>

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"

***

<h2 id="crearnota\">
  crearNotaCreditoDebito \\
</h2>

Crea y emite una Nota de Crédito o Débito contra una factura original validada. La nota se envía al SIAT para validación con documento sector 24.

| 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"

<Expandable title="Estructura del JSON de request">
  ```json theme={"system"}
  {
    "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   | 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) |
  | `paymentMethodCode` | int    | Método de pago                                      |
  | `returnedDetails`   | Array  | Items devueltos o cargados                          |
</Expandable>

***

<h2 id="resumenfacturacion\">
  resumenFacturacion \\
</h2>

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"

***

<h2 id="descargardocumento\">
  descargarDocumento \\
</h2>

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

<Expandable title="Estructura de la respuesta">
  ```json theme={"system"}
  {
    "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 |
</Expandable>

***

## Conceptos clave

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="Contingencia — Facturación offline">
    Cuando el SIAT no está disponible (caída, mantenimiento, problemas de red), CUCU activa
    el modo contingencia automáticamente:

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

    El AI no necesita hacer nada especial — la contingencia es transparente.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>