Identidad fiscal independiente
El certificado y las credenciales fiscales pertenecen al emisor correspondiente, con acceso sujeto a permisos.
API fiscal para plataformas SaaS · Costa Rica
Integre facturación electrónica en su SaaS sin perder el control de sus empresas.
Una sola integración para administrar distintos emisores, cada uno con sus propias cédulas, sucursales, terminales y documentos. Su plataforma conserva su marca y su lógica de negocio.
01 · Estructura multiempresa
Su plataforma crece. Las cédulas permanecen separadas.
El sistema de ventas no tiene que convertirse en un facturador fiscal. AFECR se conecta cuando su operación necesita emitir o consultar un comprobante.
Su SaaS / IntegradorUna integración · permisos y entornos controlados
Empresa A
01 · 02Empresa B
01 · 03Empresa C
01 · 01
Cada emisor administra identidad fiscal, consecutivos, sucursales, terminales y documentos en su propio contexto.01 · 02Empresa B
01 · 03Empresa C
01 · 01
Consecutivos por terminal
El control de secuencias respeta la estructura empresa, sucursal y terminal.
Documentos aislados
Un usuario autorizado para una empresa no debe recibir información de otra.
02 · Puesta en marcha
De la venta a la respuesta fiscal, sin duplicar su operación.
- Configure su contextoSeleccione cuenta, emisor y ambiente; prepare sucursales, terminales y credenciales.
- Conecte su backendTransmita la operación fiscal por API REST utilizando una clave con permisos mínimos.
- Controle la respuestaRegistre la referencia interna, el identificador fiscal y el estado del procesamiento.
- Sincronice eventosReciba webhooks verificados y consulte el estado cuando una respuesta se retrase.
Importante: recibir una respuesta HTTP 202 significa que AFECR recibió el documento, no que Hacienda lo haya aceptado. La aceptación se confirma consultando su estado fiscal.
03 · Integradores
Dos modalidades. Usted decide cuánto controla.
Integrador
Para administrar múltiples clientes y sus documentos mediante una integración principal, con estructura y soporte de la plataforma.
- Empresas independientes y asignación de capacidad
- Operación en Sandbox y Producción
- Seguimiento de estados y archivos
- Webhooks, trazabilidad e idempotencia
Integrador Externo
Para SaaS, ERP y proveedores que conservan su propia interfaz comercial y experiencia de usuario.
- Marca y experiencia propias
- Integración fiscal desacoplada
- Firma y transporte externo según permisos contratados
- Crece con la cantidad de emisores y volumen requerido
04 · Confiabilidad
Prepare su SaaS para errores, demoras y reintentos.
Idempotencia
La misma operación conserva una clave estable en los reintentos para evitar emitir dos documentos por una venta.
Webhooks seguros
Los eventos firmados notifican cambios de estado. Su backend valida firma, timestamp y evita procesar el mismo evento dos veces.
Recuperación
Consulte por identificador o clave fiscal y concilie resultados incluso cuando haya interrupciones externas.
05 · Integración verificable
Una API que devuelve el control a su software.
Los ejemplos utilizan datos ficticios. La base URL y las operaciones disponibles dependen del ambiente y permisos de la cuenta; confirme ambos en la documentación autenticada.
La clave API se guarda únicamente en el servidor; nunca en una página pública o aplicación JavaScript.
Ver guía de integraciónPOST /documents
Authorization: Bearer [API_KEY_DEL_SERVIDOR]
Idempotency-Key: operacion-123
Content-Type: application/json
{
"document_type": "01",
"processing_mode": "managed",
"external_reference": "VENTA-123",
"currency": "CRC",
"sale_condition": "01",
"exchange_rate": 1,
"payment_methods": [{"type": "01"}],
"lines": [{
"cabys": "8315200000100",
"quantity": 1,
"unit_measure": "Sp",
"detail": "Servicio de ejemplo",
"unit_price": 1000,
"tax_category": "taxed",
"taxes": [{"code": "01", "rate_code": "08", "rate": 13}]
}],
"receiver": {
"name": "CLIENTE DEMO",
"identification_type": "02",
"identification_number": "3101123456"
}
}Ejemplo ilustrativo: para emitir, utilice un payload completo según el tipo documental y el contrato vigente.
06 · Alcance documental
Los flujos fiscales que acompañan su operación.
Emisión comercial
Factura electrónica (FE), tiquete (TE), notas de crédito (NC) y débito (ND).
Operaciones especiales
Factura de compra (FEC), factura de exportación (FEE) y recibo electrónico de pago (REP).
Recepción y consulta
XML recibidos, mensajes de receptor y seguimiento ante Hacienda según el alcance autorizado.
07 · Modelo comercial
El costo se ajusta a empresas, volumen y estructura.
Evalúe la inversión inicial, cantidad de emisores, sucursales, terminales, recargas y complementos. Para SaaS con decenas o cientos de clientes existe configuración personalizada.
El precio final y condiciones corresponden a la cotización vigente. No asuma que un cupo de empresas equivale a mensualidad por cada cédula.
MultiempresaUna cuenta con emisores independientes
Marca propiaModalidad Integrador Externo
SandboxPruebas aisladas de la producción
Toolkit fiscalCatálogos y servicios auxiliares
08 · Preguntas frecuentes
Respuestas antes de comenzar
¿Puedo administrar varias cédulas desde una misma integración?
AFECR contempla modalidades para integradores con múltiples empresas independientes. Cada empresa conserva sus sucursales, terminales, consecutivos y configuración fiscal, conforme a la capacidad contratada.
¿Mi SaaS debe utilizar el panel de AFECR?
No necesariamente. La modalidad Integrador Externo está orientada a desarrolladores que mantienen su propia interfaz y marca mientras utilizan la infraestructura fiscal de AFECR.
¿Cómo conozco el costo cuando agrego empresas?
Los planes publicados indican documentos y empresas incluidas. AFECR también ofrece configuración personalizada para ampliar empresas, sucursales, terminales y volumen documental. Consulte la cotización vigente y las condiciones de recarga antes de contratar.
¿Puedo probar antes de emitir documentos reales?
AFECR separa el entorno de Sandbox de Producción. Los planes publicados especifican la capacidad documental incluida para pruebas.
¿Cómo recibe mi aplicación los resultados de Hacienda?
La integración contempla eventos webhook y consulta de respaldo para que el software recupere estados y documentos cuando corresponda.
Consulte también las guías del blog o los recursos de documentación.
SaaS multiempresa
¿Cómo escalar emisores sin mezclar datos, consecutivos ni autorizaciones?
Alta del cliente
Asocie cada emisor a su identidad fiscal y configuración autorizada. Una empresa no hereda automáticamente certificados, consecutivos ni permisos de otra.
Operación diaria
Su SaaS conserva usuarios, suscripciones y lógica comercial. AFECR gestiona el contexto fiscal y le permite consultar estados sin mostrar a un cliente los documentos de otro.
Crecimiento comercial
Integre el servicio en su software y comercialice los servicios propios conforme al plan. Multiempresa no autoriza por sí misma a revender API Keys ni a sublicenciar accesos independientes.
Consulte el alcance contractual y los planes vigentes. Para el tratamiento técnico de eventos, consulte la guía de webhooks.