Hacienda Costa Rica — Electronic Invoicing (receipts v4.4)

Overview

The Hacienda nodes connect your workflows with Costa Rica’s electronic invoicing (electronic receipts v4.4). Floogos builds the XML, computes the numeric key (50 digits), signs it and sends it to Hacienda’s REST API with OAuth2, querying the status.

Node	What it does
Hacienda: Issue invoice (haciendaEmitirFactura)	Issues an Electronic Invoice (01)
Hacienda: Credit/debit note (haciendaEmitirNota)	Issues CN (03) or DN (02) referencing the original
Hacienda: Query status (haciendaConsultarEstado)	Status of a document by its numeric key
Hacienda: Representation / QR (haciendaRepresentacion)	Generates the printable representation with QR

REST + OAuth2, not SOAP

Unlike other countries, Costa Rica uses a REST API with OAuth2. Floogos gets a token from Hacienda’s IDP (with your ATV user/password), does a POST to /recepcion with the signed document and queries the status with GET /recepcion/{key}. The document is valid when Hacienda ACCEPTS it (received/processing is intermediate). The general VAT rate is 13%.

Credential

The nodes use a Hacienda credential. Create it under Credentials → Add → Costa Rica Hacienda with:

Field	Description
Certificate (.p12)	Hacienda’s cryptographic key, base64.
Password (PIN)	The .p12 PIN.
ID and Type	The issuer’s identification (individual/legal/DIMEX/NITE).
ATV user and password	Hacienda environment OAuth2 credentials.
Environment	Sandbox or Production.
Branch and Terminal	The codes (e.g. 001 / 00001).
Economic activity	The activity code.

The full flow

1. Prepare the document as JSON (recipient, items with precioUnitario and codigoTarifa).

2. Issue with Issue invoice. Floogos builds the XML, computes the key, signs, gets the OAuth2 token, does the reception POST and queries the status.

3. If left processing, reconcile it with Query status.

4. Generate the representation with Representation / QR.

Issuing an invoice

Node: Hacienda: Issue invoice. Example:

{
  "receptor": { "cedula": "3101999999", "tipoCedula": "02", "nombre": "Cliente SA" },
  "items": [
    { "detalle": "Product", "cantidad": 2, "precioUnitario": 50, "codigoTarifa": "08" }
  ]
}

codigoTarifa: 08 = 13% (general), 01 = 0%, 02 = 1%, 03 = 2%, 04 = 4%. precioUnitario is without VAT. The sequential is auto-numbered if not provided.

Credit and debit notes

Credit/debit note issues a CN (03) or DN (02) that references the original document with referencia (50-digit numeric key, reason code and reason):

{
  "tipo": "03",
  "referencia": { "clave": "506...", "tipoDoc": "01", "fecha": "2026-07-20", "codigo": "01", "razon": "Return" },
  "receptor": { "cedula": "3101999999" },
  "items": [ { "detalle": "Product", "cantidad": 1, "precioUnitario": 100, "codigoTarifa": "08" } ]
}

Querying status

Query status queries a document by its numeric key and returns whether it is accepted, rejected, received or processing, updating the status in the database.

Printable representation (QR)

Representation / QR generates the printable representation in HTML (exportable to PDF), with the numeric key and the QR that contains it.

Error handling

Situation	Retryable	What to do
Reception rejected	No	Hacienda returned an error (recipient ID, structure). Fix the document.
Status rejected	No	Hacienda did not accept it; check the message detail.
Expired certificate	No	Renew the .p12 and update the credential.
Network / Timeout	Yes	Transient issue; retried automatically.

XAdES-EPES signature and sandbox

Hacienda requires XAdES-EPES signing (with a signature policy). Before production, test in Hacienda’s sandbox and validate the signature (QualifyingProperties) and the XML structure against the v4.4 XSD.

See also

• Retry queue (DLQ) — how failed executions are retried.
• HTTP node — for services not covered by these nodes.