Skip to main content
REST API v1

​
Facturacion electronica
en una sola API

JSON. Paginada. Versionada. Conectada al SIAT del SIN Bolivia. Emite facturas, notas de credito/debito, y 15 tipos de documento sector.

​
URL Base

Sandbox

https://sandbox.cucu.bo
SIAT Piloto — facturas de prueba, sin validez fiscal. Gratis, sin limites.

Produccion

https://api.cucu.bo
SIAT Produccion — facturas fiscalmente validas ante el SIN.

​
Autenticacion

Todas las llamadas autenticadas requieren el header X-API-Key: 
curl -X GET https://sandbox.cucu.bo/api/v1/invoices \
  -H "X-API-Key: YOUR_API_KEY"
Registrate en app.cucu.bo/signup para obtener tu API Key de sandbox gratuita. Ver Autenticacion para mas detalles.

​
Formato de respuesta

Todas las respuestas usan el wrapper estandar ApiResponse: 
{
  "success": true,
  "message": "Operacion exitosa",
  "data": {
    // Datos del recurso
  },
  "error": null,
  "timestamp": "2026-02-22T12:00:00"
}
CampoTipoDescripcion
successbooleantrue si la operacion fue exitosa
messagestringMensaje descriptivo (puede ser null)
dataobjectDatos del recurso o resultado
errorobjectDetalle del error (null si exito)
timestampstringFecha/hora ISO 8601

​
Paginacion

Los endpoints de listado usan paginacion con page y size: 
GET /api/v1/invoices?page=0&size=20

{
  "success": true,
  "data": {
    "content": [ /* ... array de recursos ... */ ],
    "page": 0,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8,
    "first": true,
    "last": false
  }
}
ParametroTipoDefaultDescripcion
pageinteger0Numero de pagina (base 0)
sizeinteger20Elementos por pagina (max 50)

​
Content-Type

Todas las peticiones con body requieren: 
Content-Type: application/json

​
Versionado

La API usa versionado en la URL: /api/v1/. Cambios breaking se anuncian con anticipacion y se introducen en una nueva version (/api/v2/).

​
Endpoints disponibles

​
Facturas

El ciclo completo de facturacion electronica.

Crear Factura

Emite una factura electronica validada por el SIAT. Firma digital, CUF, PDF/XML y email automatico.

Listar Facturas

Lista facturas con filtros por fecha, estado, NIT y numero. Paginacion incluida.

Obtener Factura

Detalle completo de una factura: datos fiscales, CUF, estado SIAT, items y montos.

Anular Factura

Anula una factura ante el SIAT. Operacion irreversible con motivo justificado.

​
Notas de Credito/Debito

Documentos de ajuste fiscal para devoluciones parciales o totales.

Crear Nota

Emite una nota de credito o debito contra una factura validada. Endpoint dedicado con calculo automatico de montos.

Anular Nota

Anula una nota de credito/debito emitida. Operacion irreversible ante el SIAT.

​
Utilidades y Soporte

Estado de Factura

Verifica el estado actual de una factura directamente con el SIAT.

Reenviar Email

Reenvia la factura por email al cliente o a otra direccion.

Contingencia

Manejo de eventos offline cuando el SIAT no esta disponible.

Codigos SIAT

Verificacion de NIT, CUFD y comunicacion con el SIAT.

Catalogos

Sincronizacion y consulta de catalogos del SIN.

Acceso publico

Descarga publica de PDF, XML, ticket y pagina de verificacion por CUF.

AI y RAG

Chat inteligente, validacion AI y resolucion de errores SIAT.

Storage

Gestion de archivos en S3: logo empresa, certificado digital.

​
Tipos de documento sector

Todos los tipos de documento (excepto notas credito/debito) usan el endpoint unificado POST /api/v1/invoices con el campo invoiceType en el body.
codigoDocumentoSectorinvoiceTypeDocumento Sector
1ELECTRONIC_SALECompra Venta
2NOTE_CREDIT_DEBITNota Credito-Debito
3ELECTRONIC_EXPORTExportacion
4ELECTRONIC_FREE_ZONEZona Franca
5ELECTRONIC_DUTY_FREETasa Cero
8ELECTRONIC_SECTOR_EDUCATIONSector Educativo
10ELECTRONIC_HEALTH_SERVICEServicios de Salud
11ELECTRONIC_BASIC_SERVICEServicios Basicos
13ELECTRONIC_AIRLINEAerolineas
14ELECTRONIC_HOTELAlojamiento
15ELECTRONIC_HOSPITALHospitales y Clinicas
16ELECTRONIC_GAMES_LUCKJuegos de Azar
18ELECTRONIC_TELECOMTelecomunicaciones
23ELECTRONIC_FINANCIALEntidades Financieras
24ELECTRONIC_INSURANCESeguros
Las notas de credito/debito usan un endpoint dedicado: POST /api/v1/invoices/{id}/credit-note. Los demas tipos usan el endpoint unificado POST /api/v1/invoices.
Cada tipo de documento sector puede requerir campos adicionales en el request body. Ver la referencia de cada sector en la seccion Documentos Sector para los campos especificos.

​
MCP Server

Ademas de la API REST, CUCU ofrece un MCP Server con 14 herramientas que permiten a asistentes de IA operar la facturacion con lenguaje natural.

Documentacion MCP

Conecta Claude, Cursor, Windsurf o cualquier cliente MCP. 14 herramientas, Streamable HTTP, sin codigo.