Información general

POST /api/v3/invoices firma, obtiene el CUF, valida en el SIAT, genera el PDF, envía el correo y avisa por webhook.

URL base

	Sandbox	Producción
URL	`https://sandbox.cucu.bo`	`https://api.cucu.bo`
API Key	`sk_test_...`	`sk_live_...`
SIAT	Piloto (ambiente 2), sin validez fiscal	Producción (ambiente 1)
Certificado	Demo preconfigurado	Emitido por el SIN
PDF	Marca “SIN VALOR LEGAL”	Sin marca

Mismos endpoints en ambos; cambian la URL y la key. Ver Ambientes.

Autenticación

Header X-API-Key en cada request. 401 (key ausente, inválida o tenant inactivo), 403 (sin alcance) y 429 (más de 20 credenciales inválidas por minuto desde tu IP; espera Retry-After), con { "error": true, "message": "..." }. Ver Autenticación.

curl https://sandbox.cucu.bo/api/v3/invoices -H "X-API-Key: YOUR_API_KEY"

Formato de respuesta

Wrapper ApiResponse; los campos nulos no se serializan.

Éxito
Error

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

{
  "success": false,
  "message": "createInvoice.request.clientBusinessName: no debe estar vacio",
  "error": { "code": "VALIDATION_ERROR" },
  "timestamp": "2026-02-22T12:00:00"
}

Campo	Tipo	Descripción
`success`	boolean	`true` si la operación fue exitosa
`message`	string	Mensaje descriptivo; en un error, la causa legible
`data`	object	Resultado (se omite en un error)
`error`	object	`{ "code", "details" }`; se omite en éxito. `details` solo viene en `INTERNAL_ERROR` (`ref=<uuid>`)
`timestamp`	string	ISO 8601

Códigos en Errores. Versión en la URL (/api/v3/).

Paginación

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

Parámetro	Default	Descripción
`page`	`0`	Página base 0; un valor negativo se trata como `0`
`size`	`20`	Elementos por página. Máximo 100: un valor mayor no es error, se sirve `100`; `0` o negativo → `20`

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

page y size de la respuesta son los servidos (size puede ser menor al pedido).

Flujo de emisión

Validación (400): campos requeridos, NIT (7-15 dígitos), códigos SIAT y montos coherentes.
Respuesta apenas el SIN acepta; PDF, correo y chat van después (detalle).
Cada cambio de estado dispara un webhook.

Estados de una factura

Estado	Descripción	¿Final?
`PENDING`	Creada, pendiente de envío al SIAT	No
`VALIDATED`	Validada por el SIAT, con validez fiscal	Sí, salvo anulación
`REJECTED`	Rechazada por el SIAT	Sí
`CANCELLED`	Anulada ante el SIAT con motivo del catálogo; se puede revertir	Sí
`CONTINGENCY`	Emitida offline, en cola de reenvío; pasa a `VALIDATED` al reenviarse	No

Estado actual: GET /api/v3/invoices/{id}/status.

Tipos de documento sector

Todos usan POST /api/v3/invoices con documentSectorType (si se omite, el sector por defecto del punto de venta). Las notas usan POST /api/v3/invoices/{id}/credit-note.

`documentSectorType`	Documento sector	Disponible
`1`	Compra Venta	✅
`2`	Alquiler de Bienes Inmuebles	✅
`3`	Comercial de Exportación (bienes, excluye minerales)	✅
`5`	Zona Franca	✅
`8`	Tasa Cero por venta de libros y transporte internacional de carga	✅
`10`	Duty Free	—
`9`	Compra-Venta Moneda Extranjera	✅
`11`	Sector Educativo	—
`13`	Servicios Básicos	✅
`15`	Entidades Financieras	✅
`16`	Hoteles	✅
`17`	Hospitales y Clínicas	✅
`20`	Comercial de Exportación de Minerales	✅
`21`	Venta Interna de Minerales	✅
`18`	Juegos de Azar	—
`22`	Telecomunicaciones	✅
`23`	Prevalorada	✅
`24` / `47` / `48`	Nota Crédito-Débito (estándar / Descuento / ICE)	✅
`28`	Exportación de Servicios	✅
`30`	Boleto Aéreo	—
`34`	Seguros	—
`35`	Bonificaciones	✅
`36`	Prevalorada Sin Derecho a Crédito Fiscal	—
`55`	Comercialización de Combustible	✅

✅ = implementado. — = no habilitado: 422 SECTOR_NOT_SUPPORTED.

Empezar

Planes

Referencia

Endpoints

Documentos Sector

Utilidades y Soporte

Información general

URL base

Autenticación

Formato de respuesta

Paginación

Flujo de emisión

Estados de una factura

Tipos de documento sector

​URL base

​Autenticación

​Formato de respuesta

​Paginación

​Flujo de emisión

​Estados de una factura

​Tipos de documento sector

URL base

Autenticación

Formato de respuesta

Paginación

Flujo de emisión

Estados de una factura

Tipos de documento sector