Hacienda Costa Rica — Facturación electrónica (comprobantes v4.4)

Descripción

Los nodos Hacienda conectan tus workflows con la facturación electrónica de Costa Rica (comprobantes electrónicos v4.4). Floogos arma el XML, calcula la clave numérica (50 dígitos), lo firma y lo envía al API REST de Hacienda con OAuth2, consultando el estado.

Nodo	Qué hace
Hacienda: Emitir factura (haciendaEmitirFactura)	Emite una Factura Electrónica (01)
Hacienda: Nota de crédito/débito (haciendaEmitirNota)	Emite NC (03) o ND (02) referenciando el original
Hacienda: Consultar estado (haciendaConsultarEstado)	Estado de un comprobante por su clave numérica
Hacienda: Representación / QR (haciendaRepresentacion)	Genera la representación impresa con QR

REST + OAuth2, no SOAP

A diferencia de otros países, Costa Rica usa una API REST con OAuth2. Floogos obtiene un token del IDP de Hacienda (con tu usuario/clave del ATV), hace un POST a /recepción con el comprobante firmado y consulta el estado con GET /recepcion/{clave}. El comprobante es válido cuando Hacienda lo ACEPTA (recibido/procesando es intermedio). El IVA general es 13%.

Credencial

Los nodos usan una credencial de tipo Hacienda. Creala en Credenciales → Agregar → Costa Rica Hacienda con:

Campo	Descripción
Certificado (.p12)	La llave criptográfica de Hacienda, base64.
Contraseña (PIN)	El PIN del .p12.
Cédula y Tipo	La identificación del emisor (física/jurídica/DIMEX/NITE).
Usuario y clave del ATV	Credenciales OAuth2 del ambiente de Hacienda.
Ambiente	Sandbox o Producción.
Sucursal y Terminal	Los códigos (ej. 001 / 00001).
Actividad económica	El código de actividad.

El flujo completo

1. Preparás el comprobante como JSON (receptor, ítems con precioUnitario y codigoTarifa).

2. Emitís con Emitir factura. Floogos arma el XML, calcula la clave, firma, obtiene el token OAuth2, hace el POST de recepción y consulta el estado.

3. Si quedó procesando, lo reconciliás con Consultar estado.

4. Generás la representación con Representación / QR.

Emitir una factura

Nodo: Hacienda: Emitir factura. Ejemplo:

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

codigoTarifa: 08 = 13% (general), 01 = 0%, 02 = 1%, 03 = 2%, 04 = 4%. El precioUnitario va sin IVA. El secuencial se autonumera si no lo pasás.

Notas de crédito y débito

Nota de crédito/débito emite una NC (03) o ND (02) que referencia el documento original con referencia (clave numérica de 50 díg, código de motivo y razón):

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

Consultar el estado

Consultar estado consulta un comprobante por su clave numérica y devuelve si está aceptado, rechazado, recibido o procesando, actualizando el estado en la base.

Representación impresa (QR)

Representación / QR genera la representación imprimible en HTML (exportable a PDF), con la clave numérica y el QR que la contiene.

Manejo de errores

Situación	Reintentable	Qué hacer
Recepción rechazada	No	Hacienda devolvió un error (RUC receptor, estructura). Corregí el comprobante.
Estado rechazado	No	Hacienda no aceptó; revisá el detalle del mensaje.
Certificado vencido	No	Renová el .p12 y actualizá la credencial.
Red / Timeout	Sí	Problema pasajero; se reintenta automáticamente.

Firma XAdES-EPES y sandbox

Hacienda exige firma XAdES-EPES (con política de firma). Antes de producción, probá en el sandbox de Hacienda y validá la firma (QualifyingProperties) y la estructura XML contra el XSD v4.4.

Ver también

• Cola de reintentos (DLQ) — cómo se reintentan las ejecuciones que fallan.
• Nodo HTTP — para servicios no cubiertos por estos nodos.