Información general

Toda factura en Bolivia se valida en línea en el SIAT del SIN antes de tener validez fiscal: firma digital con certificado del SIN, CUF (Código Único de Facturación), validación y XML firmado. CUCU hace todo eso detrás de POST /api/v1/invoices y además genera el PDF, envía el correo al cliente 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, bodies y respuestas en ambos; cambian solo la URL y la key. Detalle en Ambientes.

Autenticación

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

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

Formato de respuesta

Wrapper ApiResponse en todas las respuestas. 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. Content-Type: application/json en todo request con body. La versión va en la URL (/api/v1/); un cambio incompatible se publica como /api/v2/ con aviso previo.

Paginación

GET /api/v1/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 efectivamente servidos (size puede ser menor al pedido).

Flujo de emisión

Validación (HTTP 400 si falla): campos requeridos (NIT, razón social, método de pago, detalles), formato de NIT (7-15 dígitos, algoritmo del SIN), códigos SIAT (actividad, producto, unidad de medida), montos positivos y coherentes (subtotal = cantidad × precio − descuento).
La respuesta sale apenas el SIN acepta. PDF (A4 y ticket), subida a storage, correo y notificación por chat se entregan después, por una cola con reintentos. Las URLs pdfUrl / ticketUrl / xmlUrl ya son válidas: si pedís el PDF antes de que esté guardado, se genera en el momento (tarda más, nunca 404). El webhook invoice.emitted puede llegar antes que el correo.
Cada cambio de estado dispara un webhook si hay un endpoint suscrito.

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 contra el SIAT: GET /api/v1/invoices/{id}/status (Estado de factura).

Tipos de documento sector

Todos los tipos de documento (excepto notas de crédito/débito) usan POST /api/v1/invoices. El sector se elige con documentSectorType (numérico) en el body, validado contra los sectores autorizados de tu empresa; si se omite, se usa el sector por defecto del punto de venta. Las notas usan POST /api/v1/invoices/{id}/credit-note (Crear nota).

`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	✅
`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	✅
`22`	Telecomunicaciones	✅
`23`	Prevalorada	✅
`24` / `47` / `48`	Nota Crédito-Débito (estándar / Descuento / ICE)	✅
`28`	Exportación de Servicios	✅
`34`	Seguros	—
`35`	Bonificaciones	✅
`36`	Prevalorada Sin Derecho a Crédito Fiscal	—
`55`	Venta de Combustible	✅

✅ = implementado y emitiendo. — = en el catálogo SIAT pero no habilitado: la emisión responde 422 SECTOR_NOT_SUPPORTED. Los campos adicionales de cada sector están en su página.