> ## 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. # Quickstart > Emite tu primera factura electronica en 5 minutos. Tutorial paso a paso con codigo real. CUCU 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](https://wa.me/59160522508) y recibe tu API Key en la misma conversación — o en [app.cucu.bo](https://app.cucu.bo/signup). *** 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: ```bash cURL theme={"system"} curl -X GET https://sandbox.cucu.bo/api/v1/ping ``` ```javascript JavaScript theme={"system"} const response = await fetch('https://sandbox.cucu.bo/api/v1/ping'); const data = await response.json(); console.log(data); ``` ```python Python theme={"system"} import requests response = requests.get('https://sandbox.cucu.bo/api/v1/ping') print(response.json()) ``` Respuesta esperada (`200 OK`): ```json theme={"system"} { "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`. 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) | ```bash cURL theme={"system"} 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 } ] }' ``` ```javascript JavaScript theme={"system"} 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); ``` ```python Python theme={"system"} 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`): ```json theme={"system"} { "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" } ``` | 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. 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: ```bash cURL theme={"system"} # Reemplaza {cuf} con el CUF real del paso anterior curl -O https://sandbox.cucu.bo/api/v1/public/invoice/{cuf}/pdf ``` ```javascript JavaScript theme={"system"} // 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(); ``` ```python Python theme={"system"} 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. 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`): ```json theme={"system"} { "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](/mcp/overview) para ver todas las herramientas disponibles. *** ## Que sigue? Explora todos los endpoints: emision, anulacion, consultas, sincronizaciones SIAT, y mas. Conecta tu IA directamente a facturacion electronica con 41 herramientas disponibles. Aprende a emitir facturas offline cuando el SIAT no esta disponible y sincronizarlas despues. 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](/mcp/overview) — es la forma mas rapida.