cucuEmitirFactura

Description

Issues a Bolivian electronic invoice with CUCU (SIN SIAT): validates the data, builds the CUF, signs and sends it to the SIAT. Supports 20 sectors (sales, rental, export, education, lodging, minerals…). Returns the invoice, its CUF and links to the PDF, XML and tickets. Protects against duplicates with the idempotency key.

Part of the Bolivia Fiscal Hub as an alternative to connecting directly to SIAT: CUCU is an authorised provider handling signing, CUIS/CUFD codes and submission to the SIN. Node: “Emitir factura”.

Configuration

Field	Type	Required	Description
credentials_id	credentials	Yes	cucu credential
point_of_sale_id	text	No	Point of sale (UUID) — Shown in CUCU Branches and points of sale. Empty = the credential default point of sale
document_sector	select	No	Sector — Sector-specific data goes in “Sector fields”. Required per sector → 2 Property rental: billedPeriod · 3 Goods export: buyerAddress, incoterm, incotermDetail, destinationPort, destinationPlace, codeCountry, details[].codeNandina · 5 Free zone: receptionPartyNumber · 9 Foreign currency exchange: currencyOperationType, currencyCode, exchangeRate, officialExchangeRate · 11 Education: studentName, billedPeriod · 13 Utilities: month, gestation, city, zone, meterNumber, customerAddress, consumptionPeriod · 16 Lodging: qtyGuests, qtyRooms, dateEntryLodging · 17 Hospitals and clinics: details[].specialty, details[].doctorSpecialty, details[].doctorName, details[].doctorDocument, details[].doctorRegistrationNumber · 20 Minerals export: buyerAddress, bulkConcentrate, origin, destinationPort, codeCountry, incoterm, lotNumber, netWetKilos, netDryKilos, exchangeRate, exchangeRateAnb, realizationExpenses, details[].codeNandina, details[].gradeDescription, details[].extractionQuantity, details[].extractionUnitMeasure · 21 Domestic minerals sale: buyerAddress, bulkConcentrate, origin, incoterm, lotNumber, netWetKilos, netDryKilos, exchangeRate, exchangeRateAnb, realizationExpenses, details[].codeNandina, details[].gradeDescription, details[].extractionQuantity, details[].extractionUnitMeasure · 28 Services export: 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	Client document type — 5, 1, 2, 3, 4
client_document_number	text	Yes	Document number — NIT: 7 to 15 digits (dots and dashes accepted)
client_business_name	text	Yes	Business name — The CUCU registry gives the official name from the NIT
client_email	text	No	Client email — If set, CUCU emails the invoice to the client
client_complement	text	No	Document complement
client_code	text	No	Client code — Your internal code (sent to SIAT). Empty = the document number
exception_code	select	No	Exception code (NIT only) — “, 0, 1
payment_method_code	number	No	Payment method (SIAT code) — 1 = cash, 2/3 = card (payment-methods catalog, up to 308)
card_number	text	No	Card number — Only with payment method 2 or 3. CUCU keeps the first and last 4 digits
details	json	Yes	Invoice lines (JSON) — Array of lines: description, quantity, priceUnit and optional amountDiscount, codeProduct, unitMeasure, activityEconomic, codeProductSin. Also accepts cantidad, precio_unitario, descuento… Missing fields come from the defaults below
default_activity_economic	text	No	Default economic activity (CAEB) — Applied to lines without activityEconomic
default_code_product_sin	text	No	Default SIN product code — Applied to lines without codeProductSin
default_unit_measure	number	No	Default unit of measure — 58 = Service, 1 = Unit, 57 = Piece (unit-measures catalog)
sector_fields	json	No	Sector fields (JSON) — Header data of the chosen sector, with CUCU names. Validated before sending
additional_discount	number	No	Additional discount — Global discount in Bs. SIAT validates total = Σ subtotals − additional discount
gift_card_amount	number	No	Gift card amount
currency_code	number	No	Currency code — Foreign currency only (1 = bolivianos)
exchange_rate	number	No	Exchange rate
observations	text	No	Observations — Up to 500 characters; shown on the PDF
is_ticket	boolean	No	Attach 80 mm ticket to the email
idempotency_mode	select	No	Duplicate protection — With a key, a retry after a failure does not duplicate the invoice: CUCU returns the one already issued. For two identical invoices in a loop use a manual key (e.g. the order id) · auto, manual, off
idempotency_key	text	No	Idempotency key — 1–255 visible characters, no spaces. Recommended: the sale id
include_raw	boolean	No	Include raw response
output_key	text	No	Output key — The result is added to data[key] keeping the rest of the data

Credentials

This module requires a credential of type cucu with the fields:

• API key: starts with sk_test_ (sandbox) or sk_live_ (production); the environment is inferred from the prefix
• Environment: automatic, testing or production (if it contradicts the key, nothing is sent)
• Default point of sale (UUID): used when the node does not specify one
• Company ID (UUID): for branches and certificate status
• Webhook secret (whsec_…): to verify event signatures

Output

{
  "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": []
}

The output is stored under the configured key (output_key, default cucu) and the rest of data is kept. On error: error.message, error.type and, where applicable, status, code and siat_code.

Usage Example

{
  "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"
}

Notes

• Issues one invoice per call. The idempotency key is derived from the body: if the workflow is retried CUCU returns the same invoice instead of duplicating it (replayed: true).
• Everything is validated before calling the API: tax ID, document types, payment method, sector-specific fields and lines. If something is missing the error says what and nothing is sent.
• A sk_test_ key means sandbox (no fiscal validity). If the key and the “Environment” field contradict each other nothing is sent.
• If SIAT is down the invoice may end up in contingency (OFFLINE_PENDING): reported in warnings.
• Sectors 3 (export) and 9 (multi-currency) are listed as sandbox-only in the CUCU documentation.

Related Nodes

• 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