API de facturación electrónica multiempresa en Costa Rica

La pregunta correcta no es “¿cómo envío una factura?”

En un SaaS con múltiples empresas, la dificultad real no está únicamente en construir un XML o consumir un endpoint. Está en garantizar que cada comprobante sea emitido por la empresa correcta, con su identificación tributaria, certificado, sucursal, terminal, consecutivo y trazabilidad independientes.

Por eso, una API de facturación electrónica multiempresa en Costa Rica debe diseñarse como una capa de infraestructura fiscal, no como una pantalla adicional del sistema administrativo.

La versión 4.4 debe tratarse como el marco documental de referencia para las estructuras y documentos descritos en este artículo. El documento oficial de especificaciones identifica, entre otros aspectos, la estructura de la clave y el consecutivo, la identificación del proveedor de sistemas y los tipos de comprobante disponibles. (hacienda.go.cr

1. Diferencie el SaaS de un facturador tradicional

Un facturador tradicional suele operar alrededor de un único contribuyente, una configuración relativamente fija y una emisión desde una interfaz centralizada. En cambio, un SaaS puede tener:

cientos o miles de empresas;
varias cédulas jurídicas o físicas por cuenta comercial;
sucursales con reglas operativas distintas;
terminales de punto de venta conectadas en paralelo;
ERP, POS, comercio electrónico y aplicaciones móviles emitiendo documentos;
integradores que necesitan una API estable, auditable e idempotente.

La diferencia principal está en el modelo de aislamiento. El sistema no debe preguntar únicamente “¿qué factura se va a emitir?”, sino también “¿en nombre de cuál empresa, desde cuál sucursal y qué terminal?”.

2. Modele la jerarquía fiscal desde el inicio

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

Integrador > Empresa > Sucursal > Terminal

Esta jerarquía debe reflejarse en la base de datos, en los permisos y en cada solicitud de emisión. Una estructura práctica puede separar:

Integrador: dueño de la integración, configuración técnica, límites y auditoría global.
Empresa: contribuyente emisor, con su identificación tributaria y credenciales fiscales.
Sucursal: ubicación o unidad operativa que participa en la numeración y operación.
Terminal: origen concreto de la transacción, como una caja POS, tienda web o módulo ERP.

No conviene guardar la cédula, el certificado o el consecutivo como variables globales del sistema. Deben pertenecer a una empresa o a la unidad que contractualmente corresponda. Así se evita que una configuración de prueba, una sucursal recién creada o una migración sobrescriba datos de otra entidad.

Regla de aislamiento recomendada

Cada comando de emisión debe resolver explícitamente el contexto fiscal:

integrador_id → empresa_id → sucursal_id → terminal_id

Si falta cualquiera de los identificadores requeridos por el contrato, el sistema debería rechazar la operación antes de construir el comprobante. Esto es preferible a generar un documento y descubrir después que se utilizó la cédula equivocada.

3. Cédulas, certificados y secretos: separación estricta

La identificación tributaria no es un dato decorativo. Participa en la identidad del emisor y debe estar vinculada a la configuración fiscal correcta.

El componente que firma y envía comprobantes debe ejecutarse en backend. Las claves API, llaves criptográficas, contraseñas, certificados y cualquier secreto no deben exponerse en el navegador, una aplicación móvil ni un POS distribuido.

El Ministerio de Hacienda documenta mecanismos de firma XAdES-EPES y opciones de autenticación asociadas a firma digital o llaves criptográficas. La documentación también explica que el XML firmado se envía mediante la API de comprobantes electrónicos. (hacienda.go.cr

Buenas prácticas para un SaaS:

1. almacenar secretos en un gestor de secretos, no en tablas de configuración sin protección;

2. cifrar los certificados en reposo;

3. restringir el acceso por empresa y ambiente;

4. registrar quién cambió una credencial, sin guardar el secreto en los logs;

5. separar pruebas y producción;

6. planificar rotación, revocación y recuperación;

7. probar la firma con el XSD y las estructuras correspondientes a la versión implementada.

El certificado de una empresa no debe reutilizarse automáticamente para otra empresa, aunque ambas pertenezcan al mismo cliente comercial.

4. Consecutivos: no los deje en manos de la concurrencia

En un sistema multiempresa, varias terminales pueden solicitar emisión al mismo tiempo. Si el consecutivo se genera con un simple contador en memoria, aparecerán duplicados, saltos no explicados o cruces entre sucursales.

El diseño debe definir, con base en el contrato y la estructura aplicable:

qué entidad administra la secuencia;
cómo se reservan números;
qué ocurre cuando una operación falla después de reservarlos;
cómo se relacionan tipo de comprobante, sucursal y terminal;
cómo se audita cada consecutivo;
cómo se impide que una empresa consuma la secuencia de otra.

AFECR contempla los documentos FE(01), ND(02), NC(03), TE(04), FEC(08), FEE(09) y REP(10), además de recepción y Mensaje Receptor. La implementación debe conservar el tipo de comprobante como parte del registro transaccional, no únicamente como texto generado al final.

5. Estados: recibido no significa aceptado

La API pública del Ministerio de Hacienda describe que la recepción correcta deja pendiente la validación y la respuesta posterior. En su documentación aparece un estado HTTP de recepción que no equivale por sí mismo a la validación final del comprobante. (hacienda.go.cr

Esta distinción es fundamental para el diseño de estados internos. Un flujo recomendable separa al menos:

`creado`: existe una orden fiscal, pero aún no se firma;
`firmado`: el XML fue firmado correctamente;
`enviado`: la plataforma recibió la solicitud de envío;
`recibido`: existe acuse técnico de recepción;
`aceptado`: se recibió una respuesta de aceptación;
`rechazado`: existe una respuesta de rechazo;
`error_reintento`: la operación puede reintentarse bajo reglas controladas;
`cancelado`: la operación fue detenida antes de completar el envío.

En AFECR, un HTTP 202 no debe interpretarse automáticamente como aceptación del Ministerio de Hacienda. El producto debe comunicar al usuario la diferencia entre aceptación por AFECR, recepción técnica y resultado fiscal definitivo.

6. Webhooks e idempotencia para no duplicar facturas

Los webhooks firmados permiten que el SaaS reciba cambios de estado sin consultar continuamente. Sin embargo, un webhook puede repetirse, llegar fuera de orden o ser procesado después de un reintento.

Por eso, el receptor debe:

validar la firma del webhook;
conservar el identificador del evento;
procesar cada evento de manera idempotente;
validar que el evento pertenece a la empresa esperada;
aceptar reintentos sin duplicar asientos ni notificaciones;
mantener una bitácora de eventos recibidos y procesados;
separar el estado de la factura del estado de la entrega del webhook.

Un ejemplo: si llega dos veces un evento de rechazo para la misma clave, el sistema puede registrar ambas entregas, pero solo debe aplicar una transición de negocio.

7. Arquitectura recomendada por capas

Una integración mantenible suele separar:

1. Dominio comercial: pedidos, clientes, productos, impuestos y pagos.

2. Orquestador fiscal: decide qué documento corresponde y valida el contexto empresa-sucursal-terminal.

3. Adaptador AFECR: transforma el modelo interno al contrato de AFECR.

4. Firma y seguridad: opera exclusivamente en backend.

5. Cola de envío: desacopla la venta de la comunicación externa.

6. Procesador de respuestas: interpreta recepción, aceptación, rechazo y Mensaje Receptor.

7. Auditoría: conserva XML, respuestas, claves, eventos y decisiones relevantes según la política de retención del producto.

No conviene asumir que un PDF o un payload exportado representa todos los endpoints de la versión vigente. El equipo debe validar el contrato efectivo, los esquemas, los tipos de documento y los cambios publicados antes de cerrar una implementación.

8. Costos de escalabilidad: mida componentes, no solo documentos

El costo de una plataforma multiempresa no depende únicamente del número de facturas. También crece con:

cantidad de empresas y certificados administrados;
volumen de XML y respuestas almacenadas;
retención de archivos y respaldos;
procesamiento de firmas;
colas, reintentos y monitoreo;
tráfico de webhooks;
soporte de sucursales y terminales;
pruebas de regresión por versión;
ambientes separados para desarrollo, pruebas y producción.

Para evitar sorpresas, defina métricas por empresa, sucursal, terminal y tipo de documento. Un precio variable debe poder explicar qué unidad está generando el consumo. No atribuya a Hacienda ni a AFECR tarifas o plazos que no estén expresamente publicados o contratados.

9. Casos de uso frecuentes

SaaS contable con varias razones sociales

Cada empresa debe tener configuración, certificados, consecutivos y permisos aislados. El usuario administrativo puede cambiar de empresa, pero una sesión no debería conservar silenciosamente el contexto fiscal anterior.

POS con varias cajas

Cada terminal debe identificarse de forma consistente. La emisión debe ser tolerante a desconexiones, pero no debe confirmar al cajero una aceptación fiscal que todavía no existe.

Marketplace o plataforma con vendedores

La plataforma debe definir quién es el emisor y quién administra las credenciales. No se debe mezclar la factura de la plataforma con la factura del vendedor sin una regla contractual y tributaria clara.

Integración ERP

El ERP puede originar la factura, pero AFECR debe recibir el contexto completo. La clave de idempotencia debe conservarse desde el sistema origen hasta la respuesta final.

Checklist antes de salir a producción

[ ] La jerarquía Integrador > Empresa > Sucursal > Terminal está implementada.
[ ] Cada empresa tiene cédula, ambiente y credenciales independientes.
[ ] Las claves API y certificados solo se usan en backend.
[ ] La firma y validación XML fueron probadas con la versión 4.4 aplicable.
[ ] FE, ND, NC, TE, FEC, FEE y REP están diferenciados en el modelo.
[ ] Recepción, aceptación, rechazo y Mensaje Receptor son estados distintos.
[ ] Los consecutivos tienen control transaccional y auditoría.
[ ] Los webhooks verifican firma e idempotencia.
[ ] Los reintentos no duplican documentos ni efectos contables.
[ ] El sistema no interpreta HTTP 202 como aceptación de Hacienda.
[ ] Hay separación entre pruebas y producción.
[ ] Los costos de almacenamiento, firma, soporte y eventos están medidos.
[ ] Se verificó el contrato vigente y no solo un PDF o payload exportado.

Cuándo puede encajar AFECR

AFECR puede encajar cuando el producto necesita centralizar una integración multiempresa, operar con una jerarquía explícita de integrador, empresa, sucursal y terminal, y recibir eventos mediante webhooks firmados con manejo de idempotencia según contrato. La decisión final debe considerar requisitos técnicos, seguridad, soporte, costos y alcance documental del proyecto.

Para revisar la documentación de integración, consulte AFECR para desarrolladores o la información de su API de facturación electrónica para SaaS.

Fuentes y fecha de consulta

Consulta editorial: 13 de octubre de 2026. El marco documental utilizado es la versión 4.4 publicada por el Ministerio de Hacienda; el documento de especificaciones indica su régimen de aplicación y describe las estructuras de comprobantes. La documentación oficial de la API explica la recepción de comprobantes y su validación posterior. Las afirmaciones sobre jerarquía, webhooks, idempotencia y estados propios de AFECR se basan en el contrato suministrado para este encargo y deben contrastarse con la documentación contractual vigente antes de publicar.

¿Desea integrar facturación electrónica en su software?

Conozca la infraestructura de AFECR y su documentación para desarrolladores.

Explorar AFECR →

Cómo integrar facturación electrónica en un SaaS multiempresa con múltiples cédulas en Costa Rica