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.

Webhooks en tiempo real

Suscríbete a invoice.*, contingency.* y eventos de conexión SIAT. Entrega firmada (HMAC-SHA256) con reintentos automáticos.

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"

const response = await fetch('https://sandbox.cucu.bo/api/v1/invoices', {
  headers: { 'X-API-Key': process.env.CUCU_API_KEY }
});

import requests
response = requests.get(
    'https://sandbox.cucu.bo/api/v1/invoices',
    headers={'X-API-Key': os.environ['CUCU_API_KEY']}
)

req, _ := http.NewRequest("GET", "https://sandbox.cucu.bo/api/v1/invoices", nil)
req.Header.Set("X-API-Key", os.Getenv("CUCU_API_KEY"))
resp, _ := http.DefaultClient.Do(req)

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

Flujo completo

Cuando creas una factura a traves de la API, este es el proceso interno:

Cada cambio de estado de la factura (y eventos de contingencia SIAT) dispara un webhook si tienes un endpoint suscrito. Ver Webhooks para el catálogo completo de eventos, la verificación de firma y la política de reintentos.

1. Validacion de datos

La API valida:

Campos requeridos: NIT, razon social, metodo de pago, detalles
Formato de NIT: 7-15 digitos, algoritmo de verificacion SIN
Codigos SIAT: Actividad economica, producto SIN, unidad de medida
Montos: Positivos y coherentes (subtotal = cantidad x precio - descuento)

Si la validacion falla, se retorna HTTP 400 con detalle del error.

Estados de una factura

Estado	Descripcion	Final?
`PENDING`	Creada, pendiente de envio al SIAT	No
`VALIDATED`	Validada por el SIAT — tiene validez fiscal	Si (a menos que se anule)
`REJECTED`	Rechazada por el SIAT — revisar errores	Si
`CANCELLED`	Anulada ante el SIAT — irreversible	Si
`CONTINGENCY`	Emitida offline, en cola de reenvio	No

Puedes consultar el estado actual de cualquier factura con GET /api/v1/invoices/{id}/status. Ver Estado de factura.

​Facturación Electrónica

Emite facturas

15 tipos de documento

Notas de crédito/débito

Contingencia offline

Webhooks en tiempo real

​URL Base

Sandbox

Producción

​Autenticación

​Formato de Respuesta

​Paginación

​Flujo completo

​1. Validacion de datos

​Estados de una factura

Facturación Electrónica

URL Base

Autenticación

Formato de Respuesta

Paginación

Flujo completo

1. Validacion de datos

Estados de una factura