Integración de ARCA (AFIP) con Ágora: factura electrónica

La integración de ARCA (antes AFIP) con Ágora autoriza en ARCA cada factura y cada nota de crédito que emite el TPV: Connect Manager pide el CAE al web service de factura electrónica, devuelve a Ágora lo que hay que imprimir (CUIT, número de comprobante, CAE con su vencimiento y código QR) y guarda cada comprobante para consultarlo después. Si ARCA no responde, el local sigue facturando con un CAEA de contingencia.

Este manual es para el técnico de FOS o del distribuidor que deja la integración funcionando en un local de Argentina. En las pantallas de Connect Manager la integración sigue apareciendo con el nombre antiguo, AFIP.

Qué hace la integración#

• Recibe cada factura de Ágora al emitirla, por la integración de documentos de Ágora, y Ágora no la cierra hasta que ARCA la autoriza o la rechaza.
• Elige el tipo de comprobante (Factura, Nota de crédito o Nota de débito, A o B) y el punto de venta de ARCA según la serie de Ágora.
• Numera cada comprobante con el siguiente al último autorizado en ARCA para ese punto de venta y tipo.
• Identifica al receptor por su CUIT: el de la ficha del cliente de Ágora o el que se asigna al ticket con el botón CUIT del TPV. Sin CUIT, sale a consumidor final sin identificar.
• Asocia cada nota de crédito a su factura original, si esa factura se autorizó con esta integración.
• Devuelve a Ágora el bloque que se imprime al final del ticket: CUIT del cliente (en los comprobantes A, también nombre, domicilio, código postal y provincia), número de comprobante, CAE o CAEA, vencimiento del CAE, la leyenda del régimen de transparencia fiscal (Ley 27.743) con el IVA contenido en los comprobantes que no son A, y el código QR de ARCA.
• Si no consigue hablar con ARCA, emite el comprobante con el CAEA vigente de la quincena para que la caja no se pare. Los CAEA se piden solos dos veces al día.
• Rechaza las facturas sin CUIT que superan el importe máximo general o el de la forma de pago con la que se cobran.
• Avisa por correo y por Telegram si encuentra saltos en la numeración de los comprobantes.
• Guarda todos los comprobantes con lo enviado y lo respondido por ARCA, para consultarlos, verificarlos contra ARCA y exportarlos a Excel desde Listados fiscales.
• Si Ágora reenvía una factura que ya tiene CAE (misma serie y número), no pide otro: devuelve el que ya tenía.

Qué no hace#

• No factura en otra moneda que el peso argentino.
• No emite comprobantes de servicios: todos salen con el concepto «Productos».
• No emite Factura C, M, recibos ni Factura de Crédito Electrónica MiPyMEs: solo comprobantes A y B.
• No envía tributos, importes exentos ni no gravados: van siempre a cero.
• No informa por sí sola a ARCA los comprobantes emitidos con CAEA durante una caída: esa tarea está desactivada en la versión actual y la lanza FOS. Avísalo en cuanto veas comprobantes «Sin enviar».
• No anula comprobantes: en ARCA lo autorizado se corrige con una nota de crédito.

Requisitos#

• Local en Connect Manager (https://app.connectmanager.es) con la URL de la API y la API key de Ágora. El alta del local y de la integración la hace FOS; el distribuidor revisa y completa el resto.
• API de Ágora accesible desde Internet (puerto abierto o Zero Connect), solo para configurar: el buscador de formas de pago de Límites de pago la consulta. Las facturas las envía Ágora a Connect Manager.
• Ágora con el módulo Servicios de integración (integración de documentos con sistemas externos), Acciones personalizadas y una plantilla de factura ESC/POS: el bloque con el CAE y el QR llega como datos de impresión y Ágora solo lo imprime en plantillas ESC/POS.
• En ARCA (contador o cliente, con su clave fiscal): certificado digital del CUIT emisor autorizado para el web service de factura electrónica (wsfe) y los puntos de venta de web service para CAE y para CAEA.
• TPV con Internet: la ventana del botón CUIT se carga desde Connect Manager.

Datos que necesitamos#

Configuración paso a paso#

En ARCA (contador o cliente)#

1. Genera el certificado digital del CUIT emisor, autorízalo para el servicio de factura electrónica (wsfe) y guarda la clave privada sin contraseña: la integración no admite claves protegidas.
2. Da de alta los puntos de venta de web service para CAE y para CAEA y apunta sus números.
3. Para las pruebas, pide también un certificado de homologación (ver Comprobar que funciona).

En Connect Manager#

1. En https://app.connectmanager.es, ve a Administración → Locales, abre el local, revisa la URL de API y la API key de Ágora y pulsa Guardar. Se habilitan los módulos de la derecha.
2. Entra en Integraciones fiscales, pulsa Añadir y en Proveedor elige AFIP (no se puede cambiar después de guardar).
3. Rellena la pestaña Configuración:
   • URL Api: la del web service de factura. Ponla siempre: vacía se usa la dirección por defecto del servidor, que no tiene por qué ser la de producción.
   • URL Auth: la de autenticación de ARCA, sin ?WSDL al final.
   • Certificado y Clave privada: sube los dos ficheros; verás «Certificado subido» y «Private key subida».
   • CUIT: el del emisor, sin guiones.
   • Límite de pago sin CUIT: importe máximo de una factura sin CUIT. Vacío o 0, sin límite.
   • Email de receptor de notificaciones (varias direcciones separadas por comas) e Id. de chat de Telegram para recibir notificaciones: reciben el aviso de saltos de numeración (ver Telegram).
   • Simular caída del servicio AFIP: desmarcada. Marcada, todas las llamadas a ARCA fallan; solo sirve para probar la contingencia.
4. Pulsa Guardar. Al pie aparecen, con su botón de copiar, la URL para enviar facturas desde Ágora (termina en /fiscals/afip/generate-receipt) y la URL de botón de asignación de CUIT. Cópialas tal cual, sin tocar los marcadores entre llaves.
5. En la pestaña Puntos de venta AFIP, pulsa + Añadir y crea una fila por cada serie con la que emite Ágora (simplificadas, nominales y sus devoluciones) con: Serie de fact. en Agora (nombre exacto), Tipo de factura por defecto, Código del punto de venta (CAE), Código del punto de venta (CAEA), Condición ante el IVA del receptor (Consumidor Final en las series B, IVA Responsable Inscripto en las A) y Último nº de documento CAEA.
6. Si hay límites por forma de pago, en la pestaña Límites de pago pulsa + Añadir, elige el Método de pago de Ágora y escribe la Cantidad.

[!WARNING] El tipo de comprobante se decide por la serie, no por el tipo de documento. Si las devoluciones salen con la misma serie que las facturas, irían a ARCA como facturas: comprueba en Ágora que cada tipo de documento tiene su propia serie.

En Ágora#

1. En Herramientas → Activar módulos adicionales → Servicios de integración, pega la URL para enviar facturas desde Ágora en la integración de documentos con sistemas externos y actívala para las facturas.
2. Crea el botón en Herramientas → Acciones personalizadas → Nuevo: Texto CUIT, Tipo Url/Aplicación y, en Acción, la URL de botón de asignación de CUIT. Deja marcada Mostrar Urls en un diálogo de Ágora y pulsa Aceptar.
3. Colócalo en Herramientas → Configuración de botones, en el perfil que use el local, y da el permiso de la acción a los perfiles de usuario que vayan a usarla.
4. En las fichas de cliente pon el CUIT en el campo del CIF, con 11 dígitos y sin guiones. A los clientes que reciben Factura A márcales el recargo de equivalencia: la integración lo usa como señal de factura nominal.

Cómo funciona#

Cuando se emite una factura, Ágora la manda a Connect Manager y espera. Connect Manager comprueba la serie, el CUIT y los límites; obtiene de ARCA un ticket de acceso firmado con el certificado del cliente (lo reutiliza mientras no caduca); pregunta el último número autorizado de ese punto de venta y tipo, y pide el CAE con el siguiente. Si ARCA lo aprueba, guarda el CAE y su vencimiento y contesta a Ágora con el bloque que se imprime. Si lo rechaza, contesta con el código y el texto de ARCA y Ágora no cierra la factura.

sequenceDiagram
    participant TPV as TPV Ágora
    participant CM as Connect Manager
    participant AUTH as ARCA WSAA
    participant FE as ARCA WSFE
    TPV->>CM: Factura emitida
    CM->>CM: Valida serie, CUIT y límites
    CM->>AUTH: Ticket de acceso firmado con el certificado
    AUTH-->>CM: Token y firma
    CM->>FE: Último comprobante autorizado
    FE-->>CM: Último número del punto de venta
    CM->>FE: Solicitud de CAE con el número siguiente
    FE-->>CM: CAE y fecha de vencimiento
    CM-->>TPV: Aceptada con datos de impresión y QR
    TPV->>TPV: Cierra e imprime la factura

Qué se envía: el punto de venta CAE y el tipo de la serie; el CUIT emisor; el receptor con CUIT (tipo de documento 80) si la ficha del cliente lo tiene y es válido o si se asignó con el botón, o con tipo 99 si no; la condición ante el IVA de la serie; la fecha de negocio de Ágora; total, neto gravado e IVA con su desglose por alícuota (cada tipo de IVA de Ágora se traduce al código de ARCA con una tabla interna, y uno que no esté en ella se manda como 21 %), y en las notas de crédito los datos de la factura original. El número del comprobante en ARCA no es el de Ágora: Ágora conserva su serie y número, y los dos quedan guardados juntos.

Contingencia con CAEA#

Si la factura no supera las validaciones o ARCA la rechaza, Ágora recibe el motivo. Si lo que falla es la comunicación (ARCA no responde, error de red o de autenticación), Connect Manager usa el CAEA de la quincena de la fecha de negocio: numera el comprobante en el punto de venta CAEA (siguiente al último emitido con CAEA o al Último nº de documento CAEA configurado), lo deja «Sin enviar» y Ágora imprime el CAEA. Sin CAEA para ese periodo, la factura se rechaza.

flowchart TD
    A[Factura de Ágora] --> B{Pasa las validaciones}
    B -- No --> R1[Rechazada con el motivo]
    B -- Sí --> C{Respuesta de ARCA}
    C -- Aprobada --> OK[CAE impreso en el ticket]
    C -- Rechazada --> R2[Rechazada con el código de ARCA]
    C -- Sin conexión o error de autenticación --> D{Hay CAEA de la quincena}
    D -- Sí --> E[Sin enviar con el CAEA impreso]
    D -- No --> R3[Rechazada sin CAEA]

[!WARNING] Un certificado mal subido o caducado no da un error de certificado en el TPV: la integración lo trata como una caída y factura con CAEA. Si aparecen comprobantes «Sin enviar» sin que ARCA esté caída, revisa certificado, clave y URL Auth, y pide a FOS que informe a ARCA los comprobantes emitidos con CAEA.

Tareas programadas y botón CUIT#

• CAEA: dos veces al día se pide el de la quincena en curso (días 1 a 15 y 16 a fin de mes) y, del 11 al 15 y en los últimos cinco días del mes, también el de la siguiente. Se ven en Listados fiscales → CAEAs.
• Saltos de numeración: cada hora se revisan los comprobantes de las dos últimas horas de cada punto de venta CAE y tipo; si un número no sigue al anterior, se avisa a FOS y a los correos y al chat de la integración («Error documentos AFIP»).
• Botón CUIT: abre en Ágora la ventana «CUIT para la factura», con teclado en pantalla y el CUIT ya asignado si lo había. Al pulsar Asignar, el CUIT se valida (11 dígitos y dígito de control) y queda ligado al ticket abierto: hay que asignarlo antes de emitir la factura.

Comprobar que funciona#

1. Empieza con las URL y un certificado de homologación.
2. Emite una factura simplificada pequeña: debe imprimirse con número de comprobante, CAE, vencimiento y QR.
3. En Listados fiscales → AFIP documentos debe aparecer Aceptado con tipo, punto de venta, número y código.
4. Asigna un CUIT con el botón a un ticket abierto y factúralo: el CUIT debe salir impreso.
5. Emite una factura nominal a un cliente con CUIT y recargo de equivalencia: debe salir como Factura A con sus datos.
6. Devuelve la primera factura y comprueba que sale como nota de crédito.
7. Si hay límite sin CUIT, intenta superarlo sin CUIT: Ágora debe mostrar el rechazo.
8. Para la contingencia (solo en homologación y con un CAEA ya visible en CAEAs), marca Simular caída del servicio AFIP, factura, comprueba que sale con CAEA y queda «Sin enviar», y desmarca la casilla.
9. Pasa a las URL, el certificado y la clave de producción y repite la primera prueba.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto ARCA (AFIP) con Ágora?#

Con Connect Manager: se da de alta la integración fiscal AFIP del local con certificado, clave y CUIT, se mapea cada serie de Ágora a un tipo de comprobante y punto de venta, y en Ágora se pega la URL de facturas en la integración de documentos.

¿Qué pasa si ARCA se cae mientras el local está facturando?#

Si hay CAEA de la quincena, las facturas salen con CAEA y quedan «Sin enviar»; después hay que informarlas a ARCA, y eso lo lanza FOS. Sin CAEA, la factura se rechaza.

¿Cómo emito una Factura A desde Ágora?#

Con una factura nominal a un cliente con el CUIT en el CIF y el recargo de equivalencia marcado, emitida con una serie mapeada a Factura A.

¿Puedo poner el CUIT de un cliente sin darlo de alta en Ágora?#

Sí: con el botón CUIT se asigna al ticket abierto antes de facturar.

¿Dónde veo el CAE de una factura?#

Impreso en el ticket y en Listados fiscales → AFIP documentos, columna Código, con el detalle de lo enviado y lo recibido.

¿Sirve para monotributistas?#

No: emite comprobantes A y B; la Factura C no está disponible.

Referencias#

• Ficha de la integración: ARCA en el catálogo de Connect Manager.
• Avisos de las integraciones por Telegram.
• Zero Connect: publicar la API de Ágora sin abrir puertos.
• Global Blue, otra integración fiscal que se configura en la misma pantalla.
• Web services de ARCA: https://www.afip.gob.ar/ws/.
• Especificación del código QR de los comprobantes: https://www.afip.gob.ar/fe/qr/.