> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cucu.bo/llms.txt
> Use this file to discover all available pages before exploring further.
# Crear Factura
> Crea y emite una factura electronica validada por el SIAT.
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](/api/overview#tipos-de-documento-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 |
```bash cURL theme={"system"}
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
}
]
}'
```
```javascript JavaScript theme={"system"}
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();
```
```python Python theme={"system"}
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())
```
```json 201 theme={"system"}
{
"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"
}
```
```json 400 theme={"system"}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"details": "El campo clientBusinessName es requerido"
},
"timestamp": "2026-02-11T12:00:00"
}
```