API de facturación electrónica en Costa Rica: guía práctica para desarrolladores en 2026

API de facturación electrónica en Costa Rica: guía para desarrolladores

Integrar facturación electrónica en un POS, ERP, tienda en línea o plataforma SaaS no consiste únicamente en enviar un JSON. Una integración confiable debe resolver autenticación, contexto empresarial, generación documental, trazabilidad, reintentos, recepción de respuestas y sincronización de estados.

Esta guía presenta una ruta progresiva para evaluar y construir una integración con AFECR, tomando como marco documental la versión 4.4 de las estructuras de comprobantes electrónicos. La versión 4.4 se utiliza aquí como referencia técnica del material provisto; cualquier obligación, fecha de vigencia, plazo o cambio normativo debe confirmarse directamente en la fuente primaria publicada por el Ministerio de Hacienda. No se atribuyen en este artículo reformas adicionales ni fechas que no estén verificadas.

1. El problema real: conectar la venta con el flujo fiscal

Su sistema ya conoce la venta, el cliente, los productos, los impuestos, el cobro y las reglas comerciales. La API fiscal debe recibir la información necesaria para procesar el comprobante y devolver una referencia que permita continuar el flujo.

Una arquitectura razonable separa responsabilidades:

• POS, ERP, e-commerce o SaaS: ventas, inventario, clientes, pagos, órdenes, usuarios y experiencia de negocio.
• Backend de integración: validación, transformación de datos, control de reintentos, almacenamiento de estados y seguridad.
• AFECR: capa de infraestructura para emisión, recepción, seguimiento, eventos y recuperación según el contrato contratado.
• Ministerio de Hacienda: recepción y procesamiento dentro del flujo fiscal correspondiente.

AFECR describe su servicio como una capa REST para integrar sistemas existentes, con ambientes separados, emisión, recepción, webhooks, idempotencia y herramientas auxiliares. Estas capacidades deben contrastarse con el contrato y la documentación técnica aplicables a cada implementación. (afecr.com

2. Entienda el modelo jerárquico antes de programar

En el contrato AFECR, la jerarquía operativa es:

Integrador > Empresa > Sucursal > Terminal

Esta estructura no es un detalle administrativo. Determina dónde vive cada configuración y cómo debe asociarse un documento.

Ejemplo de asignación

• El integrador administra la integración para varios clientes.
• La empresa representa al obligado o entidad que emite.
• La sucursal identifica el establecimiento o ubicación operativa.
• La terminal representa el punto de venta, caja, dispositivo o proceso emisor.

Antes de enviar documentos, defina en su base de datos una relación explícita entre el identificador comercial interno y el contexto AFECR correspondiente. Evite resolver esta relación con nombres libres como “tienda centro” o “caja 2”; use identificadores estables.

{
  "integrador_id": "int_001",
  "empresa_id": "emp_045",
  "sucursal_id": "suc_003",
  "terminal_id": "term_008",
  "referencia_interna": "orden_98431"
}

El ejemplo es conceptual. Los nombres exactos, campos obligatorios y valores aceptados deben tomarse del contrato versionado de la integración, no de este artículo.

3. Comprobantes y flujos que debe modelar

El material público de AFECR contempla, entre otros, los siguientes tipos y procesos:

• FE (01): Factura Electrónica.
• ND (02): Nota de Débito Electrónica.
• NC (03): Nota de Crédito Electrónica.
• TE (04): Tiquete Electrónico.
• FEC (08): Factura Electrónica de Compra.
• FEE (09): Factura Electrónica de Exportación.
• REP (10): Recibo Electrónico de Pago.
• Recepción de documentos y Mensaje Receptor, cuando corresponda al flujo.

La documentación oficial del Ministerio de Hacienda para las estructuras 4.4 identifica los tipos documentales y sus esquemas XML. En una integración JSON, esto no significa que su aplicación deba construir directamente el XML: significa que debe mapear correctamente la información requerida por el contrato que finalmente produce y procesa el comprobante. (hacienda.go.cr

Caso de uso: una venta en un POS

1. El POS registra la venta localmente.

2. El backend crea una solicitud fiscal con una referencia única.

3. El backend envía la solicitud a AFECR.

4. AFECR procesa el documento según el contexto configurado.

5. El sistema guarda el identificador de operación y el estado inicial.

6. Un webhook o una consulta de recuperación actualiza el estado.

7. El POS muestra el resultado apropiado: recibido, pendiente, aceptado, rechazado o requiere revisión, según los estados definidos por el contrato.

No conviene marcar una venta como “aceptada por Hacienda” únicamente porque la API respondió correctamente. Un HTTP 202 indica recepción o procesamiento diferido de la solicitud; no equivale por sí mismo a aceptación del Ministerio de Hacienda.

4. REST y JSON: diseñe una frontera clara

El patrón público de referencia de AFECR utiliza un punto de envío como:

POST /api/v1/documentos
Content-Type: application/json

La ruta anterior debe verificarse contra el contrato vigente de su cuenta o proyecto. El PDF, un payload exportado o una página comercial no necesariamente reflejan todos los endpoints disponibles en la versión contratada.

Un payload conceptual para una FE podría organizarse así:

{
  "tipo": "FE",
  "referencia_interna": "orden_98431",
  "contexto": {
    "empresa_id": "emp_045",
    "sucursal_id": "suc_003",
    "terminal_id": "term_008"
  },
  "emisor": {
    "identificacion": "310100000000",
    "nombre": "Empresa de Ejemplo"
  },
  "receptor": {
    "identificacion": "101010101",
    "nombre": "Cliente de Ejemplo"
  },
  "lineas": [
    {
      "codigo": "SKU-100",
      "descripcion": "Servicio mensual",
      "cantidad": 1,
      "precio_unitario": 25000
    }
  ]
}

Este JSON es ilustrativo y no pretende sustituir el esquema OpenAPI, los ejemplos canónicos ni las validaciones del contrato AFECR. En producción, debe definir con precisión monedas, impuestos, descuentos, unidades de medida, referencias, consecutivos, información de pago y demás campos exigidos por el flujo aplicable.

5. Autenticación: la clave API vive en el backend

La clave API no debe exponerse en el navegador, una aplicación móvil, un JavaScript público, una terminal POS sin protección o un repositorio. El patrón recomendado es:

1. El cliente llama a su backend.

2. El backend valida autorización, empresa, sucursal y terminal.

3. El backend construye y valida el payload.

4. El backend agrega la credencial AFECR.

5. El backend envía la solicitud y guarda la respuesta.

Frontend/POS -> Backend propio -> AFECR -> Flujo fiscal

Use variables de entorno o un gestor de secretos para la credencial. Registre request IDs, referencias internas y estados, pero no escriba claves, certificados, PIN, tokens ni credenciales fiscales en logs.

La configuración fiscal del emisor —incluidos los datos que correspondan al ambiente— debe administrarse de acuerdo con el procedimiento contratado. La página pública de acceso de AFECR indica que la configuración previa puede incluir credenciales del Ministerio de Hacienda y certificado, pero esos datos deben permanecer protegidos y fuera del código fuente. (afecr.com

6. Sandbox no es producción

Mantenga ambientes separados desde el primer commit:

• Credenciales distintas.
• Base de datos o partición lógica separada.
• Empresas, sucursales y terminales de prueba diferenciadas.
• Webhooks de prueba separados de los productivos.
• Indicadores visibles de ambiente en logs y paneles.

Una prueba útil no es solo “la API respondió 200”. Debe comprobar el ciclo completo: solicitud, respuesta inicial, consulta o webhook posterior, persistencia del documento, manejo de error y recuperación.

Matriz mínima de pruebas

| Escenario | Resultado que debe verificar |

|---|---|

| FE válida | Se crea una operación trazable y se recibe su estado posterior |

| Payload incompleto | El sistema identifica el error y no duplica la venta |

| Timeout de red | La operación puede recuperarse sin reenviar a ciegas |

| Webhook repetido | El consumidor procesa el evento una sola vez |

| Rechazo fiscal | El sistema conserva motivo, referencia y acción pendiente |

| Caída temporal | Existe una cola o estado pendiente para reintento controlado |

7. Idempotencia: cómo evitar facturas duplicadas

Un timeout no significa que la solicitud no haya sido recibida. Si el POS reintenta sin una clave idempotente o referencia estable, puede generar duplicidad.

El patrón básico es:

clave_idempotencia = hash(empresa + terminal + venta_interna)

Antes de enviar:

1. Busque si ya existe una operación con esa clave.

2. Si existe un resultado definitivo, devuélvalo al sistema origen.

3. Si existe una operación pendiente, consulte o espere el evento.

4. Si no existe, cree el registro como “en proceso” y envíe.

5. Guarde la respuesta, request ID y referencias relacionadas.

La idempotencia del contrato AFECR debe usarse junto con una restricción única en su propia base de datos. No delegue toda la protección al proveedor: su sistema también debe impedir que dos procesos creen simultáneamente la misma operación.

8. Webhooks firmados y consumidores resistentes

Los webhooks permiten sincronizar cambios sin consultar permanentemente. AFECR soporta webhooks firmados e idempotencia según el contrato; implemente el receptor con estas reglas:

• Verifique la firma antes de confiar en el contenido.
• Valide timestamp o ventana de tolerancia si el contrato lo establece.
• Guarde el identificador único del evento.
• Responda rápido y procese el trabajo pesado en una cola.
• Devuelva éxito solo cuando el evento haya quedado registrado de forma segura.
• Ignore de manera controlada eventos repetidos.
• Mantenga un proceso de recuperación para eventos perdidos.

Webhook recibido
      |
Verificar firma
      |
¿Evento procesado?
  |             |
 Sí            No
  |             |
Ignorar     Guardar y encolar
                |
        Actualizar documento

No exponga en la respuesta del webhook información sensible ni permita que el endpoint ejecute instrucciones recibidas como código. El evento debe tratarse como datos no confiables.

9. Estados: separe recepción técnica de resultado fiscal

Una API puede aceptar técnicamente una solicitud, procesarla de forma diferida o devolver un rechazo de validación. Por eso conviene guardar, como mínimo:

• Estado interno de su sistema.
• Estado de la operación AFECR.
• Estado fiscal cuando esté disponible.
• Identificador del documento.
• Referencia interna.
• Fecha y hora de cada transición.
• Motivo o detalle del error.
• Ambiente utilizado.
• Request ID y event ID.

Ejemplo de estados internos:

CREADO -> ENVIADO -> PENDIENTE -> ACEPTADO
                         |
                         -> RECHAZADO
                         |
                         -> REQUIERE_REINTENTO

Estos nombres son una convención de aplicación. No sustituyen los estados definidos en el contrato ni deben presentarse como estados oficiales de Hacienda sin respaldo documental.

10. Checklist técnico antes de Producción

Arquitectura

• [ ] La clave API se usa solo desde backend.
• [ ] La jerarquía integrador, empresa, sucursal y terminal está modelada.
• [ ] Sandbox y Producción están aislados.
• [ ] Cada venta tiene una referencia interna estable.

Documentos

• [ ] Se identificaron los flujos FE, ND, NC, TE, FEC, FEE y REP que aplican.
• [ ] Se contemplan recepción y Mensaje Receptor cuando correspondan.
• [ ] El mapeo JSON está alineado con el contrato AFECR vigente.
• [ ] Los datos tributarios no se calculan con valores hardcodeados sin validación.

Resiliencia

• [ ] Hay idempotencia en API y base de datos.
• [ ] Los timeouts no generan reenvíos automáticos ciegos.
• [ ] Existe cola o estado pendiente para recuperación.
• [ ] Los webhooks firmados se verifican y se procesan de forma idempotente.
• [ ] Se puede consultar o recuperar una operación pendiente.

Seguridad y soporte

• [ ] No se registran claves, tokens, certificados ni PIN en logs.
• [ ] Los eventos y respuestas tienen trazabilidad.
• [ ] Los errores se muestran de forma útil, sin filtrar secretos.
• [ ] Existe una ruta para revisar rechazos y corregir documentos.
• [ ] El equipo sabe que HTTP 202 no equivale a aceptación fiscal.

Conclusión

Una API de facturación electrónica en Costa Rica debe incorporarse como una frontera controlada entre el dominio comercial y la operación fiscal. El desarrollo más sólido empieza por el modelo de contexto, continúa con JSON validado y autenticación en backend, y se completa con estados, idempotencia, webhooks firmados, recuperación y pruebas separadas por ambiente.

AFECR puede encajar como una opción de infraestructura cuando un POS, ERP, e-commerce o SaaS necesita incorporar estos flujos sin convertir la lógica fiscal en el centro de su producto. La decisión debe basarse en el contrato, la documentación técnica, los flujos requeridos y las pruebas de su propio caso de uso.

Para revisar la ruta de integración, consulte la documentación pública para desarrolladores en afecr.com/desarrolladores. También puede revisar la información de la API de facturación electrónica SaaS.

Fuentes y fecha de consulta

Consultadas el 13 de octubre de 2026:

• Ministerio de Hacienda: Anexos y estructuras de comprobantes electrónicos versión 4.4.
• Ministerio de Hacienda: disposiciones técnicas de comprobantes electrónicos.
• AFECR: API de facturación electrónica para Costa Rica.
• AFECR: documentación para desarrolladores.
• AFECR: documentación pública v2.
• AFECR: integraciones para POS, ERP, e-commerce y software.

La información normativa debe verificarse siempre en la publicación primaria correspondiente. Esta pieza es material editorial para revisión y no sustituye asesoría tributaria, legal ni la documentación contractual de una integración específica.