cucuEmitirFactura

Descripción

Emite una factura electrónica de Bolivia con CUCU (SIAT del SIN): valida los datos, calcula el CUF, firma y la envía al SIAT. Admite 20 sectores (compra-venta, alquiler, exportación, educación, hospedaje, minerales…). Devuelve la factura, su CUF y los enlaces al PDF, XML y tickets. Protege contra duplicados con la clave de idempotencia.

Forma parte del Hub Fiscal de Bolivia como alternativa a la conexión directa con el SIAT: CUCU es un proveedor autorizado que se ocupa de la firma, los códigos CUIS/CUFD y el envío al SIN. Nodo: «Emitir factura».

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Sí	Credencial cucu
point_of_sale_id	text	No	Punto de venta (UUID) — Sale en Sucursales y puntos de venta de CUCU. Vacío = el «punto de venta por defecto» de la credencial
document_sector	select	No	Sector — Los datos propios de cada sector van en «Campos del sector». Obligatorios por sector → 2 Alquiler de inmuebles: billedPeriod · 3 Exportación de bienes: buyerAddress, incoterm, incotermDetail, destinationPort, destinationPlace, codeCountry, details[].codeNandina · 5 Zona franca: receptionPartyNumber · 9 Compra-venta de moneda extranjera: currencyOperationType, currencyCode, exchangeRate, officialExchangeRate · 11 Sector educativo: studentName, billedPeriod · 13 Servicios básicos: month, gestation, city, zone, meterNumber, customerAddress, consumptionPeriod · 16 Alojamiento: qtyGuests, qtyRooms, dateEntryLodging · 17 Hospitales y clínicas: details[].specialty, details[].doctorSpecialty, details[].doctorName, details[].doctorDocument, details[].doctorRegistrationNumber · 20 Exportación de minerales: buyerAddress, bulkConcentrate, origin, destinationPort, codeCountry, incoterm, lotNumber, netWetKilos, netDryKilos, exchangeRate, exchangeRateAnb, realizationExpenses, details[].codeNandina, details[].gradeDescription, details[].extractionQuantity, details[].extractionUnitMeasure · 21 Venta interna de minerales: buyerAddress, bulkConcentrate, origin, incoterm, lotNumber, netWetKilos, netDryKilos, exchangeRate, exchangeRateAnb, realizationExpenses, details[].codeNandina, details[].gradeDescription, details[].extractionQuantity, details[].extractionUnitMeasure · 28 Exportación de servicios: buyerAddress, destinationPlace, codeCountry · `1`, `2`, `3`, `5`, `8`, `9`, `11`, `13`, `15`, `16`, `17`, `20`, `21`, `22`, `28`, `34`, `35`, `ELECTRONIC_HEALTH_SERVICE`, `ELECTRONIC_AIRLINE`, `ELECTRONIC_GAMES_LUCK`
client_document_type	select	No	Tipo de documento del cliente — `5`, `1`, `2`, `3`, `4`
client_document_number	text	Sí	Número de documento — NIT: 7 a 15 dígitos (se aceptan puntos y guiones)
client_business_name	text	Sí	Razón social / nombre — Con el padrón de CUCU puedes obtener el nombre oficial a partir del NIT
client_email	text	No	Email del cliente — Si se indica, CUCU le envía la factura por correo
client_complement	text	No	Complemento del documento
client_code	text	No	Código de cliente — Tu código interno (se envía al SIAT). Vacío = el número de documento
exception_code	select	No	Código de excepción (solo NIT) — “, `0`, `1`
payment_method_code	number	No	Método de pago (código SIAT) — 1 = efectivo, 2/3 = tarjeta (catálogo payment-methods, hasta 308)
card_number	text	No	Número de tarjeta — Solo con método de pago 2 o 3. CUCU conserva los 4 primeros y 4 últimos dígitos
details	json	Sí	Líneas de la factura (JSON) — Array de líneas: description, quantity, priceUnit y opcionales amountDiscount, codeProduct, unitMeasure, activityEconomic, codeProductSin. Acepta también cantidad, precio_unitario, descuento… Los campos que falten se toman de los valores por defecto de abajo
default_activity_economic	text	No	Actividad económica por defecto (CAEB) — Se aplica a las líneas que no traen activityEconomic
default_code_product_sin	text	No	Código de producto SIN por defecto — Se aplica a las líneas que no traen codeProductSin
default_unit_measure	number	No	Unidad de medida por defecto — 58 = Servicio, 1 = Unidad, 57 = Pieza (catálogo unit-measures)
sector_fields	json	No	Campos del sector (JSON) — Datos de cabecera propios del sector elegido, con los nombres de CUCU. Se validan antes de enviar
additional_discount	number	No	Descuento adicional — Descuento global en Bs. El SIAT valida total = Σ subtotales − descuento adicional
gift_card_amount	number	No	Monto pagado con gift card
currency_code	number	No	Código de moneda — Solo para moneda extranjera (1 = bolivianos)
exchange_rate	number	No	Tipo de cambio
observations	text	No	Observaciones — Hasta 500 caracteres; salen en el PDF
is_ticket	boolean	No	Adjuntar ticket de 80 mm al email
idempotency_mode	select	No	Protección contra duplicados — Con clave, un reintento tras un corte no duplica la factura: CUCU devuelve la ya emitida. Para dos facturas idénticas en un bucle usa una clave manual (p. ej. el id del pedido) · `auto`, `manual`, `off`
idempotency_key	text	No	Clave de idempotencia — 1–255 caracteres visibles, sin espacios. Recomendado: el id de la venta
include_raw	boolean	No	Incluir la respuesta cruda
output_key	text	No	Clave de salida — El resultado se añade a data[clave] sin perder el resto de datos

Credenciales

Este módulo requiere una credencial de tipo cucu con los campos:

API key: empieza por sk_test_ (sandbox) o sk_live_ (producción); el entorno se deduce del prefijo
Entorno: automático, pruebas o producción (si contradice la clave, no se envía nada)
Punto de venta por defecto (UUID): se usa si el nodo no indica uno
ID de empresa (UUID): para sucursales y estado del certificado
Secreto de webhooks (whsec_…): para verificar la firma de los eventos

Salida

{
  "success": true,
  "replayed": false,
  "environment": "production",
  "invoice": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invoiceNumber": 1,
    "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
    "state": "VALIDATED",
    "amountTotal": 500
  },
  "urls": {
    "pdf": "https://api.cucu.bo/api/v1/public/invoice/2872F…/pdf",
    "xml": "https://api.cucu.bo/api/v1/public/invoice/2872F…/xml",
    "verify": "https://api.cucu.bo/f/2872F…"
  },
  "totals_check": {
    "expected": 500,
    "actual": 500,
    "match": true
  },
  "warnings": []
}

La salida se guarda en la clave configurada (output_key, por defecto cucu) y se conserva el resto de data. En error: error.message, error.type y, si aplica, status, code y siat_code.

Ejemplo de Uso

{
  "credentials_id": "cred-cucu",
  "document_sector": "1",
  "client_document_number": "1023456789",
  "client_business_name": "EMPRESA DEMO S.R.L.",
  "details": [
    {
      "description": "Servicio de desarrollo",
      "quantity": 1,
      "priceUnit": 500
    }
  ],
  "output_key": "cucu"
}

Notas

Emite una factura por llamada. La clave de idempotencia se genera sola a partir del cuerpo: si el workflow se reintenta, CUCU devuelve la misma factura en lugar de duplicarla (replayed: true).
Todo se valida antes de llamar a la API: NIT, tipos de documento, método de pago, campos propios del sector y las líneas. Si algo falta, el error dice qué y no se envía nada.
Con una clave sk_test_ el entorno es sandbox (sin validez fiscal). Si la clave y el campo «Entorno» se contradicen, no se envía nada.
Si el SIAT está caído la factura puede quedar en contingencia (OFFLINE_PENDING): se avisa en warnings.
Los sectores 3 (exportación) y 9 (multimoneda) figuran como solo sandbox en la documentación de CUCU.

Nodos Relacionados

cucuEmitirLote - Emitir facturas en lote
cucuNotaCreditoDebito - Nota de crédito/débito
cucuAnular - Anular o revertir factura
cucuValidarCliente - Validar cliente (padrón / NIT)
cucuDocumento - Descargar o enviar documento