Su plataforma
Origina la operación, conserva la referencia comercial y decide cuándo actualizar el estado de la venta.
Centro de documentación · API V2
Encuentre las rutas de la API, ejemplos de solicitudes, estados de comprobantes, webhooks y guías para implementar facturación electrónica desde su sistema.
Conecte AFECR a su POS, ERP, tienda en línea o plataforma. Los pedidos, clientes y cobros permanecen en su sistema; AFECR recibe la información para generar y dar seguimiento al comprobante electrónico.
Origina la operación, conserva la referencia comercial y decide cuándo actualizar el estado de la venta.
Valida la solicitud, procesa el comprobante y registra su estado para consultas posteriores.
Los eventos y las consultas permiten distinguir documentos pendientes, aceptados o rechazados.
Realice la primera conexión desde su servidor, utilizando las credenciales de Sandbox de su cuenta.
Seleccione cuenta, emisor, sucursal, terminal y ambiente. Utilice una credencial con los permisos necesarios.
Prepare los campos según el tipo de comprobante 4.4 y conserve su referencia comercial.
La recepción de la solicitud no equivale a aceptación por Hacienda; espere un estado verificable.
Reciba eventos firmados y disponga de consultas de respaldo para recuperar pendientes.
POST {BASE_URL_DEL_ENTORNO}/documents
Authorization: Bearer {CLAVE_PRIVADA_DE_SU_BACKEND}
Idempotency-Key: venta-123
Content-Type: application/json
{
"document_type": "01",
"processing_mode": "managed",
"external_reference": "VENTA-123",
"currency": "CRC",
"exchange_rate": 1,
"sale_condition": "01",
"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}]
}]
}
La dirección base de API V2 es https://service.afecr.com/api/v2. Verifique el ambiente asignado a su credencial antes de enviar documentos; Sandbox y Producción tienen configuraciones independientes.
Utilice Authorization: Bearer con una credencial AFECR privada. El encabezado X-API-KEY se admite por compatibilidad. Nunca exponga la clave en JavaScript público, aplicaciones de navegador ni repositorios.
Cada operación aplica scopes, cuenta, empresa, sucursal, terminal y ambiente cuando corresponda. Una Master Key de administración no equivale a una Key hija autorizada para emitir documentos.
GET https://service.afecr.com/api/v2/context
Authorization: Bearer <API_KEY_PRIVADA>
Accept: application/jsonExplore algunas operaciones habituales para su primera integración. Todas las rutas utilizan el prefijo /api/v2 y requieren los permisos correspondientes. La documentación completa, los modelos de solicitud y las funciones de administración de su cuenta están disponibles en su panel.
| Método | Ruta | Permiso | Uso |
|---|---|---|---|
| GET | /context | core:read | Compruebe con qué empresa y ambiente está conectado. |
| GET | /meta/contracts | core:read | Consulte la versión del contrato disponible para su credencial. |
| Método | Ruta | Permiso | Uso |
|---|---|---|---|
| POST | /documents | documents:create | Envíe un comprobante con una referencia e Idempotency-Key estables. |
| GET | /documents/{id} | documents:read | Consulte un comprobante de su empresa. |
| GET | /documents/{id}/status | documents:read | Confirme su estado fiscal y la respuesta disponible. |
| GET | /documents/{id}/relations | documents:read | Revise las notas y documentos relacionados. |
| GET | /documents/{id}/files/{file} | documents:download | Descargue los archivos a los que tiene acceso. |
| Método | Ruta | Permiso | Uso |
|---|---|---|---|
| GET | /reception/documents | reception:read | Consulte comprobantes recibidos por su empresa. |
| POST | /reception/documents | reception:write | Registre un comprobante recibido cuando corresponda. |
| POST | /reception/messages | receiver_messages:create | Envíe una confirmación o rechazo autorizado. |
| GET | /reception/messages/{id}/status | receiver_messages:read | Consulte el estado del mensaje de receptor. |
| Método | Ruta | Permiso | Uso |
|---|---|---|---|
| GET | /external-client/me/fiscal-profile | external_client:fiscal:read | Key hija consulta ubicación efectiva y permisos. |
| GET | /external-client/me/toolkit/locations | external_client:fiscal:read | Key hija consulta ubicaciones del Toolkit central. |
| PATCH | /external-client/me/fiscal-location | external_client:fiscal:write + autorización de integrador | Corregir ubicación fiscal con permiso delegable. |
| GET | /external-client/me/sequences | external_client:fiscal:read | Ver último consecutivo emitido, reservas y siguiente. |
| PATCH | /external-client/me/sequences/{type} | external_client:fiscal:write + autorización de integrador | Editar consecutivo seguro, sin retroceder historia. |
| GET | /external-saas/delegation-plans | external_saas:manage | Master Key consulta planes de permisos. |
| PUT | /external-saas/clients/{id}/delegation | external_saas:manage | Master Key asigna plan/excepciones a un cliente. |
| Método | Ruta | Permiso | Uso |
|---|---|---|---|
| GET | /tools/cabys | core:read | Busque la clasificación de bienes y servicios. |
| GET | /tools/taxpayer/{identification} | core:read | Consulte información de un contribuyente. |
| GET | /tools/exchange-rate | core:read | Obtenga el tipo de cambio de referencia. |
| GET | /tools/locations | core:read | Consulte ubicaciones para su configuración fiscal. |
| GET | /tools/catalogs | core:read | Consulte catálogos disponibles para su cuenta. |
Estas rutas son una referencia de orientación, no una garantía de acceso. Consulte en su panel el contrato OpenAPI y los recursos habilitados para su modalidad y ambiente.
AFECR contempla factura electrónica (FE), tiquete (TE), notas de crédito y débito (NC/ND), factura de compra (FEC), factura de exportación (FEE) y recibo electrónico de pago (REP), además de recepción y Mensaje Receptor cuando corresponda.
La solicitud ingresó a AFECR. Un código HTTP 202 no confirma aceptación de Hacienda.
El resultado fiscal debe provenir de una respuesta verificable de Hacienda.
Su sistema debe conservar el error y orientar la corrección correspondiente.
Las notas de crédito y débito se emiten como documentos independientes, vinculados al comprobante que modifican.
Para un medicamento que posee registro sanitario, se mantiene el mismo endpoint de emisión. En su línea de producto deben incluirse el registro del Ministerio de Salud y el código de la forma farmacéutica. Consulte los Anexos y Estructuras 4.4, páginas 28–29 y Nota 19.
medicine_registrationNúmero real de registro sanitario del medicamento, hasta 100 caracteres. Corresponde a RegistroMedicamento en el XML 4.4.
pharmaceutical_formCódigo de 2–3 dígitos de forma farmacéutica. Corresponde a FormaFarmaceutica. Ejemplo: 04 = Cápsula; consulte el catálogo vigente.
{
"cabys": "3562112010200",
"quantity": 1,
"unit_measure": "Unid",
"detail": "Medicamento de ejemplo: cápsulas",
"unit_price": 1000,
"medicine_has_registration": true,
"medicine_registration": "REEMPLAZAR_POR_REGISTRO_REAL",
"pharmaceutical_form": "04",
"taxes": [{"code": "01", "rate_code": "03", "rate": 2}]
}
medicine_has_registration: false únicamente cuando pueda confirmar que el medicamento no tiene registro; los productos no farmacéuticos mantienen su flujo habitual.Conozca los códigos de referencia vigentes para notas de crédito, notas de débito, sustituciones y recibos de pago. Los códigos 13 al 17, la actualización del 12 y los tipos de documento 19 y 20 se aplican según la operación y el comprobante correspondiente.
| Código | Motivo de referencia | Cuándo se utiliza |
|---|---|---|
| 01 | Anula documento de referencia | Anulación ordinaria del comprobante mediante la nota que corresponda. |
| 02 | Corrige monto | Rectificación de importes mediante el documento de ajuste que corresponda. |
| 06 | Devolución de mercancía | Devolución de bienes relacionada con el comprobante original. |
| 07 | Sustituye comprobante electrónico | Nuevo comprobante que sustituye al original en el procedimiento ordinario. |
| 12 | Nota de crédito financiera por exoneración posterior | Nota de crédito financiera por exoneración concedida después de facturar, cuando proceda. |
| 13 | Anula por error material | Anulación por error material. Se identifica el período del comprobante original; si corresponde emitir un sustituto, se utiliza el código 15. |
| 14 | Corrige monto por error material | Corrección de importe por error material, vinculada al período del comprobante original. |
| 15 | Sustituye por error material | Sustitución por error material, después de la anulación correspondiente. AFECR verifica el estado del original y de la nota. |
| 16 | Sustituye comprobante rechazado | Sustitución de un comprobante rechazado por Hacienda. No requiere anular el rechazado con una nota de crédito. |
| 17 | Pago a comprobante electrónico | Referencia de pago utilizada en el Recibo Electrónico de Pago (REP). |
19: Factura Electrónica de Exportación. 20: Recibo Electrónico de Pago. Identifican el documento relacionado, no deben confundirse con el código del motivo de referencia.
En los motivos 13 y 14, AFECR distingue el mes de emisión y el mes del efecto fiscal relacionado. La aplicación consumidora debe revisar posibles declaraciones anteriores; la API no las modifica automáticamente.
Anexos y Estructuras 4.4 · Comunicado de actualización de 2026. Para cada operación, consulte también las condiciones y excepciones previstas en el anexo.
El REP documenta pagos vinculados con comprobantes electrónicos, conforme a los supuestos autorizados. El registro comercial de cobros y saldos permanece en el sistema de origen.
Para generar un REP mediante AFECR, indique una factura electrónica aceptada (document_type: "01") y el código de referencia 17. La factura debe corresponder a la empresa autorizada.
Puede incorporar las referencias complementarias permitidas por el formato (01, 04, 07, 08, 10, 20). No repita documentos ni supere las diez referencias por comprobante.
{
"document_type": "10",
"payment_reference": "COBRO-INTERNO-0001",
"references": [{
"document_type": "01",
"number": "<CLAVE_FISCAL_REAL_50_POSICIONES>",
"issued_at": "<FECHA_ORIGINAL_RFC3339>",
"code": "17",
"reason": "Abono de factura a crédito"
}]
}Importante: AFECR requiere una factura electrónica aceptada como referencia principal del REP. Las demás clases documentales pueden utilizarse como referencias complementarias cuando corresponda, pero no como documento principal del pago.
Un webhook es un aviso HTTPS que AFECR envía a un endpoint controlado por su backend cuando ocurre un evento habilitado. Sirve para sincronizar su aplicación; una consulta de estado sigue siendo el respaldo cuando la notificación no llega.
Verifique la firma HMAC-SHA256 con el secreto del webhook y el cuerpo HTTP original. Compruebe la marca de tiempo antes de procesarlo.
Registre el identificador del evento para no aplicar dos veces un mismo cambio. Responda rápidamente y procese en segundo plano cuando corresponda.
Ante una interrupción, consulte el documento desde su cuenta y reconcilie su estado. Nunca duplique una venta por no recibir el aviso.
Use credenciales, secretos y configuraciones independientes para Sandbox y Producción. Los eventos dependen de los permisos habilitados.
X-AFECR-Timestamp: 1794000000
X-AFECR-Event-Id: <EVENT_ID>
X-AFECR-Signature: v1=<HEX_HMAC>
mensaje = timestamp + "." + cuerpo_http_original
firma = HMAC_SHA256(mensaje, secreto_del_webhook)Validación de seguridad: compruebe la firma sobre el contenido original del webhook, sin modificarlo. Las cabeceras necesarias y el formato de los eventos se detallan en su documentación de integración.
Consulte los documentos relacionados con una factura, nota o sustitución. La respuesta respeta los permisos de la credencial y muestra únicamente los comprobantes a los que tiene acceso.
GET /api/v2/documents/{id}/relations
Authorization: Bearer <API_KEY_PRIVADA>
Accept: application/jsondocument, references, source_documents y related_documents. Puede incluir fiscal_period, emission_period, fiscal_effect_period y previous_period_review en el contexto del documento.Las interrupciones de red y las respuestas diferidas son normales en integraciones. El sistema debe saber si una venta ya fue registrada antes de intentar crearla nuevamente.
Utilice una Idempotency-Key estable por operación lógica. En un reintento de esa misma venta, conserve la misma clave.
Guarde la referencia propia, el identificador AFECR y el estado. Después de un timeout, consulte antes de reenviar.
Conserve el código HTTP, el código de error, el request_id y la referencia interna. Ante errores de red, consulte el estado antes de repetir una solicitud de emisión.
| HTTP | Interpretación | Acción aconsejada |
|---|---|---|
| 401 | Clave ausente, incorrecta o expirada. | Validar la credencial y su ambiente. |
| 403 | Scope, cuenta, IP o contexto sin autorización. | Revisar permisos; no cambiar IDs para eludir el control. |
| 404 | Recurso inexistente o no visible para la credencial. | Verificar identificador y ámbito de acceso. |
| 409 | Conflicto de operación o reutilización incompatible. | Consultar el documento existente y el detalle del error. |
| 422 | Datos o reglas fiscales inválidas. | Corregir campos y referencias, sin inventar valores fiscales. |
| 429 | Límite de solicitudes alcanzado. | Respetar límites y reintentar con control. |
| 5xx / timeout | Procesamiento desconocido o interrupción. | Reconciliar por ID, clave o referencia antes de reenviar. |
{
"ok": false,
"error": {
"code": "CODIGO_DEL_ERROR",
"message": "Descripción de la incidencia"
},
"meta": {"request_id": "IDENTIFICADOR_DE_SOLICITUD"}
}Utilice credenciales privadas en su servidor y conceda únicamente los permisos necesarios para cada operación.
Contextos independientes para evitar mezclar documentos, webhooks y credenciales.
La API Key no debe exponerse en JavaScript público, repositorios ni capturas.
Cada credencial opera dentro de su cuenta, emisor y scopes autorizados.
Una empresa no debe acceder a la información o los documentos de otra.
AFECR diferencia la operación de un emisor, la gestión centralizada de un integrador y la integración de infraestructura para empresas de software que utilizan marca propia.
Una empresa gestiona su facturación, sucursales y terminales desde AFECR. Está diseñado para sus documentos propios.
Un proveedor administra diversas empresas independientes desde su panel AFECR, con cupos, trazabilidad y controles según su plan.
El proveedor mantiene su propia plataforma y marca; AFECR procesa los comprobantes de las empresas habilitadas para su integración.
Una misma cédula fiscal puede utilizar AFECR directamente y conectarse a un integrador o a un SaaS autorizado, sin perder su conexión anterior.
Si la sucursal principal utiliza 001 / 00001, otra plataforma puede utilizar 001 / 00002 cuando esté libre. La sucursal 002 solo aplica a otra sucursal real.
No reinicie la numeración de una terminal que ya emitió documentos. Cada conexión conserva sus credenciales y permisos; la identidad fiscal común no da acceso a datos de otro integrador.
request_id para soporte y no vuelva a crear una empresa sin consultar primero su estado.Información general para cuentas y permisos autorizados. Los accesos de prueba o funciones anunciadas no implican habilitación contractual.
Autorización individual de AFECR con cantidad máxima de documentos. Alertas del prepago: 80/90/100 %. Alertas del crédito: 85/95/100 %. Sin capacidad una solicitud puede quedar pending_balance, no emitida ni aceptada. Política aplicable.
30 XML gratuitos al mes por sucursal (Emisor) o empresa fiscal (integradores); excedente ₡3,25 + IVA por XML elegible. Se prepara una factura a crédito al titular de la cuenta, con desglose. Alcance y facturación.
/api/v2/external-saas: GET /payments/methods, POST /payments/topups/quote, POST /payments/topups, GET /payments/orders/{orderId} y POST /payments/orders/{orderId}/pay. Los métodos de tarjeta no deben mostrarse como activos sin pasarela verificada. Las órdenes de transferencia no acreditan saldo hasta su aprobación. Consulte la documentación autenticada para esquemas y permisos definitivos.Cada modalidad de AFECR dispone de herramientas y guías adaptadas a su operación. Al ingresar, encontrará las funciones habilitadas para su cuenta y plan.
| Panel | Funciones principales | Acceso a herramientas |
|---|---|---|
| Emisor | Empresa, sucursales, terminales, emisión, recepción, estados y reportes. | Gestión operativa, sin consola técnica avanzada de integrador. |
| Integrador | Múltiples empresas, claves, webhooks, secuencias, Sandbox y diagnóstico. | Herramientas de integración según plan y scopes. |
| Integrador Externo | API como infraestructura; gestión de conexiones, clientes, claves y seguimiento. | Kits y documentación para operar con su sistema y marca, según las funciones contratadas. |
| Complementos | Conectores administrados, configuración, sincronización y errores. | Solo complementos contratados o disponibles. |
En su panel encontrará el contrato OpenAPI, los ejemplos y las herramientas disponibles para su modalidad de cuenta y sus permisos.
Las consultas auxiliares pueden incluir CAByS, contribuyentes, tipo de cambio, ubicaciones, EXONET, PYMPA y catálogos aplicables según el alcance contratado. Consulte las capacidades →
Elija Emisor, Integrador o Integrador Externo y consulte el manual público para descargar su paquete desde AFECR y realizar pruebas seguras. Abrir manual y elegir modalidad →. También puede obtener la colección introductoria de consultas.
No. Su POS, ERP o SaaS puede conservar la operación comercial y delegar a AFECR el procesamiento fiscal contemplado en su contratación.
Verifique el estado fiscal mediante los mecanismos habilitados. Una respuesta HTTP 202 confirma recepción técnica, no aceptación fiscal.
AFECR contempla modelos multiempresa. Cada emisor tiene contexto, permisos y datos fiscales independientes, según su plan.
Si el medicamento tiene registro sanitario, añada medicine_registration y pharmaceutical_form en su línea. Consulte el ejemplo y las reglas v4.4.
No. La sustitución mantiene documentos independientes y exige las validaciones correspondientes. En particular, el código 16 se utiliza ante un rechazo confirmado por Hacienda; no se emite una NC únicamente para anular un comprobante rechazado.
Consulte el endpoint GET /documents/{id}/relations, disponible conforme a los permisos de lectura y al alcance de la credencial. Vea trazabilidad documental.
Consulte el manual de Starter Kits, elija su modalidad y abra el panel. La clave debe utilizarse únicamente desde su servidor y nunca compartirse por chat o correo.
Consulte las guías de desarrollo y seleccione el tipo de cuenta que mejor se adapte a su proyecto.