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

# Primera factura desde tu agente

> Un pedido en lenguaje natural y las cuatro llamadas MCP que hace el agente: listarPuntosVenta, previsualizarFactura, crearFactura y descargarDocumento.

Con el agente [conectado](https://docs.cucu.bo/mcp/overview.md) a sandbox, escríbele:

> Factúrale a EMPRESA DEMO S.R.L., NIT 99001, un servicio de desarrollo de software por Bs 500, pagado en efectivo. Después pásame el PDF.

Abajo están las cuatro llamadas que hace por debajo, con el cuerpo JSON-RPC que manda a `POST /mcp` y el `structuredContent` que recibe. Los UUID y el token son de ejemplo.

**1. Elegir el punto de venta**

`crearFactura` pide un `pointOfSaleId`. El agente lo saca de [`listarPuntosVenta`](https://docs.cucu.bo/mcp/herramientas-facturacion#listarpuntosventa):

```json tools/call listarPuntosVenta theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "listarPuntosVenta", "arguments": {} }
}
```

La respuesta JSON-RPC completa trae el mismo objeto dos veces: como texto en `content[0].text` y como JSON en `structuredContent`. El agente lee `structuredContent`:

```json Respuesta theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": false,
    "content": [{ "type": "text", "text": "{\"content\":[{\"id\":\"b2c3d4e5-f6a7-8901-bcde-f12345678901\", ...}" }],
    "structuredContent": {
      "content": [
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "Caja 1",
          "siatCode": 0,
          "siatType": 5,
          "defaultDocumentSector": 1,
          "authorizedSectors": [1],
          "branchOfficeId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "branchOfficeSiatCode": 0,
          "branchOfficeName": "Casa Matriz",
          "companyId": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "companyNit": "1020304050",
          "companyBusinessName": "MI EMPRESA S.R.L.",
          "siatModality": 1,
          "modality": "ELECTRONICA",
          "siatVersion": "v2"
        }
      ],
      "page": 0,
      "size": 20,
      "totalElements": 1,
      "totalPages": 1,
      "first": true,
      "last": true
    }
  }
}
```

Con más de un punto de venta, el agente te pregunta cuál usar.

**2. Previsualizar**

[`previsualizarFactura`](https://docs.cucu.bo/mcp/herramientas-facturacion#previsualizarfactura) arma el XML y lo valida contra el XSD del SIN sin emitir ni numerar. Si `valid` es `false`, el agente corrige antes de emitir.

```json tools/call previsualizarFactura theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "previsualizarFactura",
    "arguments": {
      "factura": {
        "pointOfSaleId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "clientDocumentType": 5,
        "clientDocumentNumber": "99001",
        "clientBusinessName": "EMPRESA DEMO S.R.L.",
        "paymentMethodCode": 1,
        "details": [
          {
            "activityEconomic": "620100",
            "codeProductSin": "83141",
            "description": "Servicio de desarrollo de software",
            "quantity": 1,
            "unitMeasure": 58,
            "priceUnit": 500.00
          }
        ]
      }
    }
  }
}
```

```json structuredContent theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "siatVersion": "v2",
  "documentSectorType": 1,
  "siatModality": 1,
  "valid": true,
  "amounts": {
    "amountSubtotal": 500.00,
    "amountDiscount": 0.00,
    "amountTotal": 500.00,
    "amountLiteral": "Quinientos 00/100 Bolivianos"
  },
  "items": [
    { "line": 1, "description": "Servicio de desarrollo de software", "quantity": 1,
      "priceUnitRequested": 500.00, "priceUnit": 500.00, "amountDiscount": 0.00, "subtotal": 500.00 }
  ],
  "validations": [
    { "rule": "sector autorizado para la company", "ok": true, "detail": "sector 1, modalidad 1" },
    { "rule": "códigos del SIN en el catálogo del contribuyente", "ok": true, "detail": "actividad, producto y unidad de medida conocidos" },
    { "rule": "XSD oficial del SIN (xsd/computarized/facturaComputarizadaCompraVenta.xsd)", "ok": true, "detail": "estructura válida (la firma se valida al emitir)" },
    { "rule": "subTotal = cantidad × precio − descuento (por ítem, HALF-UP)", "ok": true, "detail": "1 ítem(s) cuadran" }
  ],
  "notes": ["Nada se emitió: número de factura y CUF son provisorios."],
  "xmlPreview": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><facturaElectronicaCompraVenta>...</facturaElectronicaCompraVenta>"
}
```

**3. Emitir**

[`crearFactura`](https://docs.cucu.bo/mcp/herramientas-facturacion#crearfactura) recibe el mismo objeto `factura`. El agente agrega `idempotencyKey`: si la conexión se corta y repite la llamada, recibe la misma factura en vez de emitir otra.

```json tools/call crearFactura theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "crearFactura",
    "arguments": {
      "factura": { "pointOfSaleId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "...": "el mismo objeto del paso 2" },
      "idempotencyKey": "venta-2026-000123"
    }
  }
}
```

```json structuredContent theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoiceNumber": 1,
  "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
  "emissionDate": "2026-11-18T12:00:00.000-04:00",
  "emissionType": "ONLINE",
  "siatState": "VALIDATED",
  "idempotencyKey": "venta-2026-000123",
  "pointOfSaleId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "documentSectorType": 1,
  "clientDocumentNumber": "99001",
  "clientBusinessName": "EMPRESA DEMO S.R.L.",
  "amountSubtotal": 500.00,
  "amountDiscount": 0.00,
  "amountTotal": 500.00,
  "amountLiteral": "Quinientos 00/100 Bolivianos",
  "siatVersion": "v2",
  "siatCodeState": 908,
  "documents": {
    "a4": "https://sandbox.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/a4",
    "ticket": "https://sandbox.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/ticket",
    "ticketsiat": "https://sandbox.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/ticketsiat",
    "xml": "https://sandbox.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/xml",
    "zip": "https://sandbox.cucu.bo/api/v3/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/documents/zip"
  },
  "verificationUrl": "https://pilotosiat.impuestos.gob.bo/consulta/QR?nit=1020304050&cuf=2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74&numero=1&t=2"
}
```

Si el SIN la rechaza, la respuesta llega con `isError: true`, el texto `[SIAT_REJECTED] ...` y la factura con su `diagnosis` en `structuredContent` ([ejemplo](https://docs.cucu.bo/mcp/para-agentes.md#rechazo-del-sin)).

**4. Pasar el PDF**

Las URLs de `documents` exigen la API Key. Para que el agente adjunte el archivo en un chat o un correo, pide un link temporal con [`descargarDocumento`](https://docs.cucu.bo/mcp/herramientas-facturacion#descargardocumento):

```json tools/call descargarDocumento theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "descargarDocumento",
    "arguments": { "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74", "tipo": "a4" }
  }
}
```

```json structuredContent theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "invoiceNumber": 1,
  "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
  "tipo": "a4",
  "fileName": "factura_1_A4.pdf",
  "mimeType": "application/pdf",
  "downloadUrl": "https://sandbox.cucu.bo/api/v3/documents/t/EJEMPLO_TOKEN_OPACO",
  "expiresAt": "2026-11-18T16:05:00Z",
  "maxUses": 3
}
```

`GET downloadUrl` baja el PDF sin credencial hasta `expiresAt` o hasta agotar `maxUses`. Después responde `410`.

## Siguientes pasos

* [Facturación](https://docs.cucu.bo/mcp/herramientas-facturacion.md): anular, notas de crédito/débito, consultas.
* [Errores y respuestas](https://docs.cucu.bo/mcp/para-agentes.md): qué hacer con `isError` y con `[CONFIRMATION_REQUIRED]`.
* [Contingencia](https://docs.cucu.bo/mcp/herramientas-eventos.md): emitir con el SIN caído.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.