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.
| Capacidad | Qué aporta al desarrollo |
|---|---|
| Emisión y seguimiento | Procesamiento de comprobantes y una referencia trazable para consultar o recuperar su resultado. |
| Recepción y mensajes | Flujos para comprobantes recibidos y confirmaciones cuando correspondan. |
| Multiempresa | Aislamiento de empresas, sucursales y terminales según el modelo autorizado. |
| Webhooks | Eventos para sincronizar estados con su sistema sin depender de consultas manuales permanentes. |
| Idempotencia y resiliencia | Controles para trabajar mejor con reintentos, respuestas diferidas y recuperación de operaciones. |
| Toolkit fiscal | CAByS, contribuyentes, tipo de cambio, ubicaciones, EXONET, PYMPA, TICA y otros catálogos desde una fuente central. |
| Diagnóstico | Trazabilidad y herramientas para comprender validaciones y errores de integración. |
| Complementos | Lí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.
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.
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.
- Prepare su sistema. Identifique dónde su programa confirma una venta y obtiene cliente, productos, cantidades, impuestos, pagos y referencia interna.
- Integre el cliente del kit en su servidor. Abra
README.md, incorpore el adaptador indicado enclient/y configure la credencial en almacenamiento privado. No la copie al navegador. - Relacione los datos. Conecte los campos de su venta con los ejemplos de
payloads/. Compruebe empresa, sucursal, terminal, CAByS y tratamiento tributario. - 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.
- Recupere el resultado. Consulte el estado o procese el webhook y actualice su factura solo cuando exista el resultado fiscal correspondiente.
- Active Producción. Tras validar el circuito completo, configure las credenciales y el ambiente productivo por separado.
Integre las empresas que administra
Conecte su sistema con cada empresa autorizada sin mezclar documentos, credenciales ni consecutivos de clientes diferentes.
- Organice sus empresas. Relacione cada empresa de su sistema con su empresa, sucursal y terminal correspondientes en AFECR.
- Incorpore el cliente en su servidor. Revise
README.mdy los ejemplos declient/ypayloads/. Configure una credencial autorizada por empresa y ambiente. - Valide a quién pertenece la operación. Antes de emitir, compruebe que el usuario o proceso tiene permiso para trabajar con esa empresa y terminal.
- Pruebe cada empresa en Sandbox. Envíe una venta de ejemplo, registre la referencia y utilice una clave de idempotencia estable por operación.
- Sincronice los estados. Verifique webhooks, evite procesar eventos repetidos y utilice la consulta de estado como recuperación.
- Publique por empresa. Active Producción únicamente cuando la empresa tenga configuración fiscal, credenciales y consecutivos correctos.
Conecte su SaaS, ERP o plataforma comercial
Su plataforma mantiene usuarios, clientes, ventas, pantallas y marca. AFECR aporta los procesos fiscales autorizados; las funciones administrativas solo se utilizan desde su servidor protegido.
- Prepare su backend. Abra
README.mdydocs/INSTALACION_STACK.md. Incorpore el adaptador debackend/correspondiente a su tecnología. - Proteja el acceso. Implemente autenticación, autorización por cliente y un almacén cifrado de credenciales antes de conectar con AFECR.
- Vincule los clientes autorizados. Siga
docs/CONEXION_Y_KEYS.mddentro del paquete autenticado para configurar los permisos y credenciales que correspondan a su plan. Nunca incorpore claves administrativas en el frontend. - Conecte la venta con la emisión. Adapte los ejemplos de
payloads/a los datos de su aplicación y utilice una credencial de alcance específico para cada cliente. - Pruebe el ciclo completo. Emita en Sandbox, consulte el estado, valide las notificaciones y compruebe que un cliente no puede consultar documentos de otro.
- Habilite Producción. Mantenga ambientes, claves, clientes y eventos separados. Active solo los flujos habilitados en su contrato.
Cómo incorporar el paquete a su tecnología
Seleccione su tecnología para ver la instalación y el punto de conexión.
Su hoja de cálculo o aplicación se comunica con un backend propio autenticado. Ese backend comprueba los permisos y consume AFECR; el cliente nunca almacena ni envía claves fiscales o administrativas. Las rutas de ejemplo de su gateway son definidas por usted, no son endpoints AFECR.
Ejemplo: una venta hecha desde su sistema
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ónRecursos 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.