Modelo de integración

Qué gestiona su software y qué procesa AFECR

Su sistema sigue gestionando ventas, clientes, inventario y pagos. AFECR procesa los comprobantes electrónicos y devuelve la información necesaria para consultar su estado y continuar la operación.

CapacidadQué aporta al desarrollo
Emisión y seguimientoProcesamiento de comprobantes y una referencia trazable para consultar o recuperar su resultado.
Recepción y mensajesFlujos para comprobantes recibidos y confirmaciones cuando correspondan.
MultiempresaAislamiento de empresas, sucursales y terminales según el modelo autorizado.
WebhooksEventos para sincronizar estados con su sistema sin depender de consultas manuales permanentes.
Idempotencia y resilienciaControles para trabajar mejor con reintentos, respuestas diferidas y recuperación de operaciones.
Toolkit fiscalCAByS, contribuyentes, tipo de cambio, ubicaciones, EXONET, PYMPA, TICA y otros catálogos desde una fuente central.
DiagnósticoTrazabilidad y herramientas para comprender validaciones y errores de integración.
ComplementosLínea de conectores administrados en desarrollo, sin disponibilidad comercial confirmada.

Recursos de integración

Encuentre lo que necesita para conectar su sistema

OpenAPI

Contrato técnico versionado para nombres de campos, estructuras, métodos y respuestas.

JSON canónicos

Ejemplos alineados con el contrato para los principales comprobantes y escenarios de integración.

Postman

Colecciones que permiten probar flujos y consultas sin construir primero toda la capa cliente.

Starter Kits

Ejemplos descargables para servidores, hojas de cálculo y aplicaciones móviles, según su modalidad.

Connection Kit

Material de apoyo para preparar, validar y revisar una integración.

Asistente técnico

Ayuda para utilizar los endpoints, interpretar errores y consultar las reglas de los comprobantes 4.4.

Medicamentos · XML 4.4: las líneas de medicamentos con registro sanitario requieren medicine_registration y pharmaceutical_form. Ver la guía y descargar el JSON de ejemplo →

La misma empresa puede trabajar con más de una plataforma.

Un emisor que ya factura mediante AFECR puede incorporar un ERP o SaaS de otro integrador sin cancelar su conexión. Cada integración autorizada opera con credenciales propias y debe respetar el ámbito fiscal de sucursal, terminal y consecutivos. Por ejemplo, la sede 001 puede utilizar 00001 para el sistema actual y 00002 para el nuevo, si este último está libre. La sucursal 002 solo corresponde a una sucursal real.

Las credenciales de Hacienda y los comprobantes no se comparten automáticamente entre cuentas. Ver coexistencia y resolución del HTTP 409 →

Seguridad y seguimiento

Controles para cada etapa del comprobante

Contratos versionados

La integración puede evolucionar de forma controlada manteniendo una referencia técnica consistente.

Ambiente Sandbox

Los recursos de prueba se mantienen separados de Producción para validar con mayor control.

Observabilidad

Las operaciones relevantes conservan trazabilidad para localizar una solicitud y comprender su estado.

Webhooks con respaldo

Los eventos reducen consultas repetitivas y pueden complementarse con recuperación cuando un callback no llega.

Secuencias protegidas

La plataforma contempla control de consecutivos y prevención de duplicidad por sucursal y terminal.

Funciones por cuenta

Las funciones se resuelven de acuerdo con la cuenta, modalidad, permisos, plan y ambiente.

Elija el nivel de control que necesita su producto.

Emisor: operación fiscal de una empresa. Integrador: administración de varias empresas desde AFECR. Integrador Externo: automatización de clientes fiscales y emisión desde un sistema propio que conserva su marca; indicado para SaaS multitenant y plataformas comerciales. Comparar modalidades →

Integrador

Administra múltiples empresas desde AFECR y dispone de herramientas orientadas a integración, webhooks, Sandbox, trazabilidad, consumo y diagnóstico.

  • Empresas independientes
  • Sucursales y terminales
  • Distribución de capacidad
  • Toolkit y herramientas de integración

Integrador externo

Mantiene su propia interfaz, operación y marca mientras utiliza AFECR como infraestructura fiscal.

  • Mayor control de experiencia
  • Modelo apto para marca propia
  • Conectividad fiscal desacoplada
  • Gestión según alcance contratado

Aprenda a utilizar el Starter Kit en su sistema

Conecte el Starter Kit a su POS, ERP, SaaS, hoja de cálculo o aplicación. Seleccione su modalidad y tecnología para ver cómo incorporar los archivos, vincular las ventas y comprobar el resultado de cada documento. El paquete se obtiene desde su panel.

Manual práctico de integración

Incorpore el Starter Kit en su sistema

Seleccione su modalidad y tecnología. La guía le muestra cómo conectar el paquete a su aplicación, realizar una prueba y comprobar el resultado.

Conecte las ventas de su empresa

Su POS, ERP o sistema comercial sigue gestionando ventas y clientes. El Starter Kit conecta la operación fiscal de su empresa y utiliza las sucursales y terminales autorizadas en AFECR.

  1. Prepare su sistema. Identifique dónde su programa confirma una venta y obtiene cliente, productos, cantidades, impuestos, pagos y referencia interna.
  2. Integre el cliente del kit en su servidor. Abra README.md, incorpore el adaptador indicado en client/ y configure la credencial en almacenamiento privado. No la copie al navegador.
  3. Relacione los datos. Conecte los campos de su venta con los ejemplos de payloads/. Compruebe empresa, sucursal, terminal, CAByS y tratamiento tributario.
  4. Pruebe una operación en Sandbox. Envíe una venta de demostración y conserve su referencia e identificador de operación. Evite reenviar una venta ante un tiempo de espera sin consultar primero.
  5. Recupere el resultado. Consulte el estado o procese el webhook y actualice su factura solo cuando exista el resultado fiscal correspondiente.
  6. Active Producción. Tras validar el circuito completo, configure las credenciales y el ambiente productivo por separado.

Cómo incorporar el paquete a su tecnología

Seleccione su tecnología para ver la instalación y el punto de conexión.

Ejemplo: una venta hecha desde su sistema

Venta confirmada en su sistemaAdaptador o gateway protegidoAFECR procesa el comprobanteSu sistema recibe el estado fiscal

Conserve una referencia estable para cada operación. Si la solicitud queda pendiente, consulte su estado antes de reintentar. Un código HTTP 202 no confirma la aceptación de Hacienda.

Antes de utilizarlo en Producción

¿El Starter Kit instala automáticamente la facturación en mi sistema?

No. El paquete aporta el cliente de integración, documentación y ejemplos. Usted o su equipo deben conectar esos archivos al flujo de ventas, permisos y datos de su aplicación.

¿Puedo guardar la clave dentro de Excel o una aplicación móvil?

No. Para hojas de cálculo y apps móviles utilice un servidor propio autenticado. Las claves fiscales y administrativas permanecen exclusivamente en el backend.

¿Qué hago si AFECR recibe la solicitud pero no tengo respuesta final?

Conserve el identificador y la referencia de la venta. Consulte el estado o espere el webhook autenticado antes de generar otro intento. Así evita duplicar comprobantes.

¿Cómo sé si mi integración está lista?

Pruebe una emisión válida, una solicitud inválida, el seguimiento hasta estado final, un tiempo de espera, un evento repetido y los permisos de su empresa. Solo entonces habilite Producción con sus credenciales separadas.

El paquete descargado desde su panel incluye la documentación técnica correspondiente a su modalidad, tecnología, ambiente y permisos. Esta guía explica el proceso de integración sin exponer credenciales ni operaciones privadas.

Abrir mi Kit de conexión Consultar la documentación de integración
Aplicaciones móviles y hojas de cálculo: la comunicación con AFECR debe pasar por un servidor autorizado que almacene las claves privadas. En Excel y Google Sheets se usan conexiones limitadas, sin distribuir credenciales fiscales.

Recursos públicos y herramientas de su cuenta

Puede descargar una colección introductoria de consultas de Postman, sin credenciales ni ejemplos de administración de cuentas. Para obtener los archivos de integración correspondientes a su empresa, ingrese al panel con su usuario.

API V2 y referencias fiscales 4.4

La referencia de la API V2 reúne las principales operaciones de emisión, recepción, consulta y webhooks. Consulte los códigos de referencia 4.4 y las condiciones de emisión del REP antes de integrar esos documentos.

Recargas y continuidad de integración

Una cuenta Integrador o Integrador Externo habilitada puede consultar los medios de pago y solicitar recargas desde el backend de su sistema con una Key administradora autorizada. Las tarjetas requieren integración comercial específica; un pago reportado no acredita saldo hasta su aprobación. Ver alcance técnico, rutas y estados.

El crédito documental es opcional y limitado. Las solicitudes sin saldo pueden quedar pendientes sin haberse emitido fiscalmente. El servicio mensual de recepción se factura por separado y únicamente después de su aceptación.

Seguridad de su integración

Los ambientes de prueba y producción funcionan de forma independiente. Cada cuenta dispone de permisos y credenciales propias para proteger los documentos y operaciones de sus empresas.

Llaves criptográficas de Hacienda: el PIN de nuevas llaves utiliza 14 caracteres (mayúscula, minúscula, número y símbolo). Los certificados antiguos vigentes con PIN de 4 dígitos siguen siendo válidos hasta su vencimiento o revocación. AFECR no genera el PIN ni debe recibirlo por canales de soporte. Comunicado de Hacienda →

Revise su integración con asistencia técnica

Si necesita ayuda con un error, comparta únicamente el código de respuesta y un ejemplo sin datos personales ni credenciales. Consulte primero las guías de su panel para obtener la referencia correspondiente a su integración.

Toda la información para avanzar con su integración

Comience por las guías públicas y continúe en su panel con OpenAPI, ejemplos, Starter Kits y las herramientas habilitadas para su cuenta.

Integración fiscal: su aplicación conserva las ventas y la atención a clientes. AFECR recibe la información fiscal y devuelve el resultado correspondiente.

Abrir documentación pública v2 →