Información General

Facturación Electrónica

Bolivia implementó la facturación electrónica a través del SIAT (Sistema Integrado de Administración Tributaria) del SIN (Servicio de Impuestos Nacionales). Toda factura emitida debe validarse en tiempo real por el SIAT antes de tener validez fiscal. El proceso involucra:

Firma digital con certificado emitido por el SIN
Generación del CUF (Código Único de Facturación)
Validación en línea contra el SIAT
Generación de PDF y XML firmado

CUCU abstrae toda esta complejidad en una sola API REST:

Emite facturas

Un solo POST /api/v1/invoices. CUCU firma, valida con el SIAT, genera CUF, PDF, XML y envía el email al cliente.

15 tipos de documento

Compra-venta, exportación, zona franca, educación, salud, hoteles, aerolíneas y más. Mismo endpoint, distinto invoiceType.

Notas de crédito/débito

Documentos de ajuste fiscal con cálculo automático de montos contra la factura original.

Contingencia offline

Cuando el SIAT no está disponible, CUCU emite con CUF offline y sincroniza al reconectarse.

URL Base

CUCU opera en dos ambientes completamente aislados. Mismo formato de respuesta, mismas validaciones, misma lógica. La única diferencia es la conexión al SIAT.

Sandbox

https://sandbox.cucu.bo

SIAT Piloto — facturas de desarrollo, sin validez fiscal. Incluido en tu plan.

Producción

https://api.cucu.bo

SIAT Producción — facturas fiscalmente válidas ante el SIN.

Característica	Sandbox	Producción
API Key	`sk_test_...`	`sk_live_...`
Ambiente SIAT	Piloto (ambiente 2)	Producción (ambiente 1)
Validez fiscal	No — facturas de prueba	Sí — reportadas al SIN
Certificado digital	Demo (preconfigurado)	Requerido (emitido por el SIN)
PDF	Con marca “SIN VALOR LEGAL”	Sin marca de agua

Cambiar de ambiente requiere solo dos variables: la URL base y la API Key. Todos los endpoints, request bodies y response formats son idénticos.

Si tu integración funciona en sandbox, funciona en producción con solo cambiar la URL y la key.

Autenticación

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"

Prefijo	Ambiente	Validez fiscal
`sk_test_...`	Sandbox (SIAT Piloto)	No
`sk_live_...`	Producción (SIAT real)	Sí

Las keys sk_live_ nunca deben exponerse en código frontend, repos públicos ni apps móviles. Solo en tu backend, vía variables de entorno o secret manager.

HTTP	Código	Causa
`401`	`UNAUTHORIZED`	API Key ausente, inválida o revocada
`403`	`FORBIDDEN`	Key válida pero sin permisos al recurso

Formato de Respuesta

Todas las respuestas usan el wrapper estándar ApiResponse:

Respuesta exitosa
Respuesta con error

{
  "success": true,
  "message": "Operación exitosa",
  "data": { },
  "error": null,
  "timestamp": "2026-02-22T12:00:00"
}

{
  "success": false,
  "message": null,
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "details": "El campo 'nitCliente' es requerido"
  },
  "timestamp": "2026-02-22T12:00:00"
}

Campo	Tipo	Descripción
`success`	boolean	`true` si la operación fue exitosa
`message`	string	Mensaje descriptivo (puede ser null)
`data`	object	Datos del recurso o resultado
`error`	object	Detalle del error (null si éxito)
`timestamp`	string	Fecha/hora ISO 8601

Paginación

Los endpoints de listado usan paginación basada en offset:

GET /api/v1/invoices?page=0&size=20

Parámetro	Tipo	Default	Descripción
`page`	integer	`0`	Número de página (base 0)
`size`	integer	`20`	Elementos por página (máx 50)

{
  "success": true,
  "data": {
    "content": [ ],
    "page": 0,
    "size": 20,
    "totalElements": 150,
    "totalPages": 8,
    "first": true,
    "last": false
  }
}

Campo	Tipo	Descripción
`content`	array	Elementos de la página actual
`totalElements`	integer	Total de elementos en el conjunto
`totalPages`	integer	Total de páginas
`first` / `last`	boolean	Si es la primera o última página

​Facturación Electrónica

Emite facturas

15 tipos de documento

Notas de crédito/débito

Contingencia offline

​URL Base

Sandbox

Producción

​Autenticación

​Formato de Respuesta

​Paginación

Facturación Electrónica

URL Base

Autenticación

Formato de Respuesta

Paginación