cucuNotaCreditoDebito

Descripción

Emite una nota de crédito o de débito sobre una factura VALIDADA (sectores 24 estándar, 47 con descuento, 48 con ICE). Solo envías las líneas devueltas o ajustadas: CUCU clona las originales. Las facturas de exportación (3) y de moneda extranjera (9) no admiten notas.

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: «Nota de crédito/débito».

Configuración

Campo	Tipo	Requerido	Descripción
credentials_id	credentials	Sí	Credencial cucu
invoice_id	text	No	ID de la factura (UUID) — El id que devuelve CUCU al emitir. Si lo dejas vacío, indica el CUF
cuf	text	No	CUF — Código Único de Factura. Se usa si no indicas el ID
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
nota_type	select	Sí	Tipo de nota — CREDITO, DEBITO
document_sector	select	No	Sector de la nota — 24, 47, 48
returned_details	json	Sí	Líneas devueltas (JSON) — Mismas claves que las líneas de una factura. En sectores 47 y 48 cada línea lleva nroItem (el lineNumber de la línea original, de «Consultar → obtener»)
original_details	json	No	Líneas originales con ICE (JSON, sector 48) — [{“nroItem”:1,“marcaIce”:2,“montoIceEspecifico”:0,“montoIcePorcentual”:0}]
payment_method_code	number	No	Método de pago (código SIAT)
card_number	text	No	Número de tarjeta
observations	text	No	Observaciones
is_ticket	boolean	No	Generar también ticket de 80 mm
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)
precheck	boolean	No	Comprobar antes que la factura está VALIDADA — Una consulta extra que evita un rechazo del SIAT
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
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,
  "original_invoice_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "note": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "invoiceNumber": 10,
    "cuf": "NOTACUF…",
    "state": "VALIDATED"
  },
  "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…"
  },
  "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",
  "cuf": "2872F7294502332E637FABFBC3654EA82202AD48E0969F14EBEB8AF74",
  "nota_type": "CREDITO",
  "returned_details": [
    {
      "description": "Devolución parcial",
      "quantity": 1,
      "priceUnit": 200
    }
  ],
  "idempotency_key": "nc-pedido-77"
}

Notas

• Solo se envían las líneas devueltas (returnedDetails); CUCU deduce las originales. Los sectores 47 y 48 exigen nroItem y el 48 también originalDetails (marca ICE 1 o 2).
• Antes de emitir se comprueba que la factura original esté VALIDATED (desactivable con «Comprobar antes»).
• Hay sectores que no admiten notas (CREDIT_DEBIT_NOTE_NOT_ALLOWED); en ese caso hay que anular la factura.

Nodos Relacionados

• cucuEmitirFactura - Emitir factura
• cucuAnular - Anular o revertir factura
• cucuConsultar - Consultar facturas