Crear Factura - CUCU API

curl -X POST https://sandbox.cucu.bo/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "documentSectorType": 1,
    "pointOfSaleId": "660e8400-e29b-41d4-a716-446655440004",
    "clientDocumentType": 5,
    "clientDocumentNumber": "99001",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientEmail": "demo@ejemplo.com",
    "paymentMethodCode": 1,
    "details": [
      {
        "activityEconomic": "620100",
        "codeProductSin": "83141",
        "description": "Servicio de desarrollo de software",
        "quantity": 1,
        "unitMeasure": 58,
        "priceUnit": 500.00
      }
    ]
  }'

const response = await fetch('https://sandbox.cucu.bo/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    documentSectorType: 1,
    pointOfSaleId: '660e8400-e29b-41d4-a716-446655440004',
    clientDocumentType: 5,
    clientDocumentNumber: '99001',
    clientBusinessName: 'EMPRESA DEMO S.R.L.',
    clientEmail: 'demo@ejemplo.com',
    paymentMethodCode: 1,
    details: [{
      activityEconomic: '620100',
      codeProductSin: '83141',
      description: 'Servicio de desarrollo de software',
      quantity: 1,
      unitMeasure: 58,
      priceUnit: 500.00
    }]
  })
});
const data = await response.json();

import requests

response = requests.post(
    'https://sandbox.cucu.bo/api/v1/invoices',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
    },
    json={
        'documentSectorType': 1,
        'pointOfSaleId': '660e8400-e29b-41d4-a716-446655440004',
        'clientDocumentType': 5,
        'clientDocumentNumber': '99001',
        'clientBusinessName': 'EMPRESA DEMO S.R.L.',
        'clientEmail': 'demo@ejemplo.com',
        'paymentMethodCode': 1,
        'details': [{
            'activityEconomic': '620100',
            'codeProductSin': '83141',
            'description': 'Servicio de desarrollo de software',
            'quantity': 1,
            'unitMeasure': 58,
            'priceUnit': 500.00
        }]
    }
)
print(response.json())

{
  "success": true,
  "message": "Factura emitida exitosamente",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoiceNumber": 1,
    "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
    "state": "VALIDATED",
    "emissionType": "NORMAL",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientDocumentNumber": "99001",
    "amountSubtotal": 500.00,
    "amountDiscount": 0.00,
    "amountTotal": 500.00,
    "literal": "Quinientos 00/100 Bolivianos",
    "emissionDate": "2026-02-11T12:00:00",
    "pdfUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/2872F...AF74/pdf",
    "xmlUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/2872F...AF74/xml"
  },
  "timestamp": "2026-02-11T12:00:00"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "details": "El campo clientBusinessName es requerido"
  },
  "timestamp": "2026-02-11T12:00:00"
}

POST

api

invoices

curl -X POST https://sandbox.cucu.bo/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "documentSectorType": 1,
    "pointOfSaleId": "660e8400-e29b-41d4-a716-446655440004",
    "clientDocumentType": 5,
    "clientDocumentNumber": "99001",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientEmail": "demo@ejemplo.com",
    "paymentMethodCode": 1,
    "details": [
      {
        "activityEconomic": "620100",
        "codeProductSin": "83141",
        "description": "Servicio de desarrollo de software",
        "quantity": 1,
        "unitMeasure": 58,
        "priceUnit": 500.00
      }
    ]
  }'

const response = await fetch('https://sandbox.cucu.bo/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    documentSectorType: 1,
    pointOfSaleId: '660e8400-e29b-41d4-a716-446655440004',
    clientDocumentType: 5,
    clientDocumentNumber: '99001',
    clientBusinessName: 'EMPRESA DEMO S.R.L.',
    clientEmail: 'demo@ejemplo.com',
    paymentMethodCode: 1,
    details: [{
      activityEconomic: '620100',
      codeProductSin: '83141',
      description: 'Servicio de desarrollo de software',
      quantity: 1,
      unitMeasure: 58,
      priceUnit: 500.00
    }]
  })
});
const data = await response.json();

import requests

response = requests.post(
    'https://sandbox.cucu.bo/api/v1/invoices',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
    },
    json={
        'documentSectorType': 1,
        'pointOfSaleId': '660e8400-e29b-41d4-a716-446655440004',
        'clientDocumentType': 5,
        'clientDocumentNumber': '99001',
        'clientBusinessName': 'EMPRESA DEMO S.R.L.',
        'clientEmail': 'demo@ejemplo.com',
        'paymentMethodCode': 1,
        'details': [{
            'activityEconomic': '620100',
            'codeProductSin': '83141',
            'description': 'Servicio de desarrollo de software',
            'quantity': 1,
            'unitMeasure': 58,
            'priceUnit': 500.00
        }]
    }
)
print(response.json())

{
  "success": true,
  "message": "Factura emitida exitosamente",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoiceNumber": 1,
    "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
    "state": "VALIDATED",
    "emissionType": "NORMAL",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientDocumentNumber": "99001",
    "amountSubtotal": 500.00,
    "amountDiscount": 0.00,
    "amountTotal": 500.00,
    "literal": "Quinientos 00/100 Bolivianos",
    "emissionDate": "2026-02-11T12:00:00",
    "pdfUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/2872F...AF74/pdf",
    "xmlUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/2872F...AF74/xml"
  },
  "timestamp": "2026-02-11T12:00:00"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "details": "El campo clientBusinessName es requerido"
  },
  "timestamp": "2026-02-11T12:00:00"
}

Crea una nueva factura electronica, la firma digitalmente, la envia al SIAT para validacion, genera PDF (A4 y ticket), XML, y opcionalmente envia por email al cliente.

Headers

Header	Tipo	Req	Descripcion
`X-API-Key`	string	Si	Tu API Key de sandbox (`sk_test_`) o produccion (`sk_live_`)
`Content-Type`	string	Si	`application/json`

Request Body

Campo	Tipo	Req	Descripcion
`documentSectorType`	integer	No	Codigo del documento sector (ver Documentos Sector). Si se omite, se usa el sector por defecto del punto de venta. Default: `1` (Compra-Venta)
`pointOfSaleId`	string	Si	UUID del punto de venta. Ejemplo: `660e8400-e29b-41d4-a716-446655440004`
`clientDocumentType`	integer	Si	Tipo de documento del cliente. Valores: `1` (CI), `2` (CEX), `3` (PAS), `4` (OD), `5` (NIT)
`clientDocumentNumber`	string	Si	Numero de documento del cliente (max 50 caracteres)
`clientBusinessName`	string	Si	Razon social del cliente (max 255 caracteres)
`clientEmail`	string	No	Email del cliente. Si se proporciona, se envia automaticamente la factura por correo
`clientComplement`	string	No	Complemento del documento de identidad
`exceptionCode`	integer	No	Código de excepción SIAT (`codigoExcepcion`). `0` = NIT validado (default), `1` = NIT no validable online. Solo aplica a `clientDocumentType = 5` (NIT). Ver nota abajo
`paymentMethodCode`	integer	Si	Codigo de metodo de pago del catalogo SIAT (1-308). Consultar catalogo sincronizado: `GET /api/v1/siat/sync/catalogs/payment-methods`. Ejemplos: `1` = Efectivo, `2` = Tarjeta credito, `5` = Transferencia, `27` = Gift-Card
`cardNumber`	string	No	Numero de tarjeta (solo si `paymentMethodCode` = 2 o 3). Se ofusca automaticamente antes de guardar y emitir — ver nota de seguridad abajo
`exchangeRate`	number	No	Tipo de cambio (solo si la factura es en moneda extranjera)
`descuentoAdicional`	number	No	Descuento global sobre el total de la factura. Default: `0`. El SIAT valida: `montoTotal = Σ(subTotal) - descuentoAdicional`
`montoGiftCard`	number	No	Monto pagado con gift card. Default: `0`. Requiere `paymentMethodCode` de tipo gift card (ej: `27`, `35`). Error SIAT [1050] si el metodo de pago no corresponde
`observations`	string	No	Observaciones o notas (max 500 caracteres). Aparece en el PDF A4 y ticket
`isTicket`	boolean	No	Si `true`, adjunta tambien el formato ticket (80mm) en el email. Default: `false`
`details`	array	Si	Lista de items de la factura (minimo 1). Ver tabla siguiente

Items del detalle (`details[]`)

Campo	Tipo	Req	Descripcion
`activityEconomic`	string	Si	Codigo de actividad economica (CAEB)
`codeProductSin`	string	Si	Codigo de producto/servicio del SIN
`codeProduct`	string	No	Codigo interno de tu producto
`description`	string	Si	Descripcion del producto/servicio (max 500 caracteres)
`quantity`	number	Si	Cantidad (mayor a 0.00001)
`unitMeasure`	integer	Si	Unidad de medida. `58` = Servicio, `1` = Unidad, `57` = Pieza, etc.
`priceUnit`	number	Si	Precio unitario (mayor a 0.00001)
`amountDiscount`	number	No	Monto de descuento por item. Default: `0`
`serialNumber`	string	No	Numero de serie del producto
`imeiNumber`	string	No	Numero IMEI (solo para telecomunicaciones)

exceptionCode (código de excepción NIT). Indica al SIAT si el NIT del cliente se pudo validar contra el padrón del SIN: 0 = validado (normal), 1 = no validable online (NIT nuevo / no registrado). Reglas:

Solo válido con clientDocumentType = 5 (NIT). Con CI/pasaporte/otros siempre es 0; enviar 1 con otro tipo de documento devuelve 400.
En contingencia (emisión offline) con NIT, la API lo fuerza a 1 automáticamente — no hace falta enviarlo. En emisión online normal, déjalo en 0 (default).

Seguridad — ofuscacion de tarjeta. Si envias cardNumber, la API conserva solo los 4 primeros y 4 ultimos digitos y reemplaza el resto por ceros antes de persistir y emitir el XML SIAT (ej: 4111111111111111 → 4111000000001111). El numero completo (PAN) nunca se guarda en la base de datos ni viaja al SIAT. Numeros de 8 digitos o menos se dejan tal cual (ej: enviar solo los ultimos 4 sigue siendo valido).

Response

Campo	Tipo	Descripcion
`success`	boolean	`true` si la factura fue emitida exitosamente
`data.id`	string	UUID de la factura
`data.invoiceNumber`	integer	Numero correlativo de factura
`data.cuf`	string	Codigo Unico de Factura (CUF). Identificador ante el SIN
`data.state`	string	Estado SIAT: `VALIDATED`, `REJECTED`, `PENDING`
`data.emissionType`	string	`NORMAL` o `CONTINGENCY`
`data.clientBusinessName`	string	Razon social del cliente
`data.amountTotal`	number	Monto total de la factura
`data.literal`	string	Monto en literal (requerido por SIAT)
`data.emissionDate`	string	Fecha y hora de emision
`data.pdfUrl`	string	URL publica del PDF
`data.xmlUrl`	string	URL publica del XML

curl -X POST https://sandbox.cucu.bo/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "documentSectorType": 1,
    "pointOfSaleId": "660e8400-e29b-41d4-a716-446655440004",
    "clientDocumentType": 5,
    "clientDocumentNumber": "99001",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientEmail": "demo@ejemplo.com",
    "paymentMethodCode": 1,
    "details": [
      {
        "activityEconomic": "620100",
        "codeProductSin": "83141",
        "description": "Servicio de desarrollo de software",
        "quantity": 1,
        "unitMeasure": 58,
        "priceUnit": 500.00
      }
    ]
  }'

const response = await fetch('https://sandbox.cucu.bo/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    documentSectorType: 1,
    pointOfSaleId: '660e8400-e29b-41d4-a716-446655440004',
    clientDocumentType: 5,
    clientDocumentNumber: '99001',
    clientBusinessName: 'EMPRESA DEMO S.R.L.',
    clientEmail: 'demo@ejemplo.com',
    paymentMethodCode: 1,
    details: [{
      activityEconomic: '620100',
      codeProductSin: '83141',
      description: 'Servicio de desarrollo de software',
      quantity: 1,
      unitMeasure: 58,
      priceUnit: 500.00
    }]
  })
});
const data = await response.json();

import requests

response = requests.post(
    'https://sandbox.cucu.bo/api/v1/invoices',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': 'YOUR_API_KEY'
    },
    json={
        'documentSectorType': 1,
        'pointOfSaleId': '660e8400-e29b-41d4-a716-446655440004',
        'clientDocumentType': 5,
        'clientDocumentNumber': '99001',
        'clientBusinessName': 'EMPRESA DEMO S.R.L.',
        'clientEmail': 'demo@ejemplo.com',
        'paymentMethodCode': 1,
        'details': [{
            'activityEconomic': '620100',
            'codeProductSin': '83141',
            'description': 'Servicio de desarrollo de software',
            'quantity': 1,
            'unitMeasure': 58,
            'priceUnit': 500.00
        }]
    }
)
print(response.json())

{
  "success": true,
  "message": "Factura emitida exitosamente",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoiceNumber": 1,
    "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
    "state": "VALIDATED",
    "emissionType": "NORMAL",
    "clientBusinessName": "EMPRESA DEMO S.R.L.",
    "clientDocumentNumber": "99001",
    "amountSubtotal": 500.00,
    "amountDiscount": 0.00,
    "amountTotal": 500.00,
    "literal": "Quinientos 00/100 Bolivianos",
    "emissionDate": "2026-02-11T12:00:00",
    "pdfUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/2872F...AF74/pdf",
    "xmlUrl": "https://sandbox.cucu.bo/api/v1/public/invoice/2872F...AF74/xml"
  },
  "timestamp": "2026-02-11T12:00:00"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "details": "El campo clientBusinessName es requerido"
  },
  "timestamp": "2026-02-11T12:00:00"
}

Versionado Listar Facturas

​Headers

​Request Body

​Items del detalle (details[])

​Response

Headers

Request Body

Items del detalle (`details[]`)

Response