Quickstart

Bienvenido a CUCU API. En los proximos 5 minutos vas a emitir tu primera factura electronica boliviana, descargar el PDF y tener todo funcionando contra el SIAT Piloto del Servicio de Impuestos Nacionales. Sin configuraciones complicadas, sin certificados digitales, sin tramites. Solo tu API Key de sandbox y una llamada HTTP.

Ambiente sandbox: Las facturas emitidas en sandbox son de prueba y no tienen validez fiscal. El sandbox conecta al SIAT Piloto (ambiente 2) del SIN, asi que el flujo completo es identico a produccion: emision, validacion, CUF, firma digital, PDF y XML.

Requisitos previos

Antes de empezar, asegúrate de tener:

Una API Key de sandbox — necesitas una API Key de sandbox
Un cliente HTTP: curl, JavaScript (fetch), o Python (requests)
5 minutos de tu tiempo

Usaremos YOUR_API_KEY como placeholder en todos los ejemplos. Contrata tu plan con el agente de CUCU por WhatsApp y recibe tu API Key en la misma conversación — o en app.cucu.bo.

Verifica la conexion con un health check

Lo primero es confirmar que puedes conectarte al servidor. El endpoint /ping es publico (no requiere API Key) y te devuelve el estado del servicio:

curl -X GET https://sandbox.cucu.bo/api/v1/ping

const response = await fetch('https://sandbox.cucu.bo/api/v1/ping');
const data = await response.json();
console.log(data);

import requests

response = requests.get('https://sandbox.cucu.bo/api/v1/ping')
print(response.json())

Respuesta esperada (200 OK):

{
  "message": "pong",
  "timestamp": "2026-02-11T12:00:00"
}

Si recibes pong, la conexion esta lista. Si recibes un error de red, verifica que no tengas un proxy o firewall bloqueando sandbox.cucu.bo.

Emite tu primera factura

Ahora vamos a crear una factura electronica real contra el SIAT Piloto. Antes de ver el codigo, estos son los campos que necesitas enviar:

Campo	Tipo	Descripcion
`pointOfSaleId`	UUID	Identificador del punto de venta registrado en SIAT
`clientDocumentType`	int	Tipo de documento del cliente. `5` = NIT, `1` = CI, `4` = Extranjero
`clientDocumentNumber`	string	Numero de documento del cliente (NIT, CI, pasaporte)
`clientBusinessName`	string	Razon social o nombre completo del cliente
`clientEmail`	string	Email donde se envia la factura automaticamente
`paymentMethodCode`	int	Metodo de pago. `1` = Efectivo, `2` = Tarjeta, `6` = Transferencia
`details`	array	Lista de items/productos de la factura (minimo 1)
`details[].activityEconomic`	string	Codigo de actividad economica CAEB del SIN
`details[].codeProductSin`	string	Codigo de producto/servicio del catalogo SIN
`details[].description`	string	Descripcion libre del producto o servicio
`details[].quantity`	number	Cantidad (puede ser decimal: `1.5`)
`details[].unitMeasure`	int	Unidad de medida SIN. `58` = Servicio, `1` = Unidad, `57` = Pieza
`details[].priceUnit`	number	Precio unitario en bolivianos (hasta 2 decimales)

curl -X POST https://sandbox.cucu.bo/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "pointOfSaleId": "660e8400-e29b-41d4-a716-446655440004",
    "clientDocumentType": 5,
    "clientDocumentNumber": "99001",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientEmail": "demo@ejemplo.com",
    "paymentMethodCode": 1,
    "details": [
      {
        "activityEconomic": "620100",
        "codeProductSin": "83141",
        "description": "Servicio de desarrollo de software",
        "quantity": 1,
        "unitMeasure": 58,
        "priceUnit": 500.00
      }
    ]
  }'

const response = await fetch('https://sandbox.cucu.bo/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    pointOfSaleId: '660e8400-e29b-41d4-a716-446655440004',
    clientDocumentType: 5,
    clientDocumentNumber: '99001',
    clientBusinessName: 'EMPRESA DEMO S.R.L.',
    clientEmail: 'demo@ejemplo.com',
    paymentMethodCode: 1,
    details: [
      {
        activityEconomic: '620100',
        codeProductSin: '83141',
        description: 'Servicio de desarrollo de software',
        quantity: 1,
        unitMeasure: 58,
        priceUnit: 500.00
      }
    ]
  })
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    'https://sandbox.cucu.bo/api/v1/invoices',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
    },
    json={
        'pointOfSaleId': '660e8400-e29b-41d4-a716-446655440004',
        'clientDocumentType': 5,
        'clientDocumentNumber': '99001',
        'clientBusinessName': 'EMPRESA DEMO S.R.L.',
        'clientEmail': 'demo@ejemplo.com',
        'paymentMethodCode': 1,
        'details': [
            {
                'activityEconomic': '620100',
                'codeProductSin': '83141',
                'description': 'Servicio de desarrollo de software',
                'quantity': 1,
                'unitMeasure': 58,
                'priceUnit': 500.00
            }
        ]
    }
)

print(response.json())

Respuesta exitosa (201 Created):

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

Show Detalle de cada campo en la respuesta

Campo	Descripcion
`id`	UUID interno de la factura en CUCU. Usalo para consultas posteriores via API.
`invoiceNumber`	Numero secuencial de la factura dentro del punto de venta.
`cuf`	Codigo Unico de Facturacion — identificador unico generado por el SIAT. Es el “DNI” de tu factura ante el SIN. Lo necesitas para consultas, anulaciones y descargas publicas.
`state`	Estado de la factura: `VALIDATED` (aceptada por el SIAT), `REJECTED` (rechazada), `ANNULLED` (anulada).
`clientBusinessName`	Razon social del cliente tal como quedo registrada en la factura.
`amountTotal`	Monto total de la factura en bolivianos, con 2 decimales.
`literal`	Monto total expresado en palabras (requerido por normativa boliviana).
`emissionDate`	Fecha y hora de emision en formato ISO 8601.
`emissionType`	Tipo de emision: `NORMAL` (online contra SIAT) o `CONTINGENCY` (offline, sincronizada despues).
`pdfUrl`	URL publica para descargar el PDF de la factura. No requiere autenticacion.
`xmlUrl`	URL publica para descargar el XML firmado digitalmente. No requiere autenticacion.

Guarda el cuf — lo necesitaras para descargar el PDF, consultar el estado, o anular la factura. El CUF es el identificador universal de la factura ante el SIN.

Descarga el PDF de la factura

Usa el CUF devuelto en el paso anterior para descargar el PDF. Este endpoint es publico (no requiere API Key), asi que puedes compartir la URL directamente con tu cliente:

# Reemplaza {cuf} con el CUF real del paso anterior
curl -O https://sandbox.cucu.bo/api/v1/public/invoice/{cuf}/pdf

// Abrir el PDF en una nueva pestana del navegador
const cuf = '2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74';
window.open(`https://sandbox.cucu.bo/api/v1/public/invoice/${cuf}/pdf`);

// O descargarlo programaticamente
const response = await fetch(
  `https://sandbox.cucu.bo/api/v1/public/invoice/${cuf}/pdf`
);
const blob = await response.blob();

import requests

cuf = '2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74'

response = requests.get(
    f'https://sandbox.cucu.bo/api/v1/public/invoice/{cuf}/pdf'
)

with open('factura.pdf', 'wb') as f:
    f.write(response.content)

print(f'PDF guardado: factura.pdf ({len(response.content)} bytes)')

Tambien puedes descargar el XML firmado digitalmente cambiando /pdf por /xml en la URL. El XML contiene la firma digital y es el documento con validez legal ante el SIN.

Bonus: Conecta tu AI con MCP

CUCU incluye un MCP Server (Model Context Protocol) que permite a asistentes de IA como Claude, Cursor o Windsurf emitir facturas, consultar estados y manejar errores del SIAT directamente desde tu IDE o chat.Agrega esta configuracion a tu Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cucu-facturacion": {
      "url": "https://sandbox.cucu.bo/mcp",
      "headers": {
        "X-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Despues de reiniciar Claude Desktop, puedes pedirle cosas como:

“Emite una factura a EMPRESA DEMO por Bs. 500 por servicio de software”
“Muestra las facturas emitidas hoy”
“Anula la ultima factura emitida”
“Que codigos de producto SIN existen para consultoria?”

El MCP Server expone 41 herramientas que cubren todo el ciclo de facturacion, incluyendo notas de credito/debito. Consulta la documentacion MCP completa para ver todas las herramientas disponibles.

Que sigue?

API Reference

Explora todos los endpoints: emision, anulacion, consultas, sincronizaciones SIAT, y mas.

MCP Server

Conecta tu IA directamente a facturacion electronica con 41 herramientas disponibles.

Contingencia

Aprende a emitir facturas offline cuando el SIAT no esta disponible y sincronizarlas despues.

Planes y precios

Revisa los planes disponibles para pasar de sandbox a produccion.

Sandbox incluido en tu plan. Desarrolla y valida tu integracion completa contra el SIAT Piloto. Cuando estes listo, pasa a produccion. O conecta tu AI via MCP Server — es la forma mas rapida.

Información General

Endpoints Disponibles

Documentos Sector

Utilidades y Soporte

Requisitos previos

Que sigue?

API Reference

MCP Server

Contingencia

Planes y precios

​Requisitos previos

​Que sigue?

API Reference

MCP Server

Contingencia

Planes y precios

Requisitos previos

Que sigue?