Integración de SAP S/4HANA con Ágora: asientos, facturas y cobros

La integración de SAP S/4HANA con Ágora lleva a SAP las ventas que cobra el TPV: los tickets de cada local se contabilizan como un asiento por serie y las facturas con cliente se crean en SAP con su cobro ya compensado, todo a través de Connect Manager. Este manual es para el técnico (de FOS o del distribuidor) que la configura junto al consultor SAP del cliente.

[!WARNING] Esta integración se desarrolló para una instalación de SAP concreta y varios datos de organización van fijos en el código (sociedad, cuenta de ingresos, organización de ventas…). Antes de comprometer fechas con un cliente nuevo, revisa con FOS y con su consultor SAP la tabla de valores fijos del apartado Requisitos.

Qué hace la integración#

• Lee de la API de Ágora las facturas del día de cada local: tickets (facturas simplificadas), facturas con cliente y sus devoluciones.
• Agrupa los tickets por local, tipo de documento y serie, y envía cada grupo a SAP como un asiento contable: una línea de ingreso por tipo de IVA, una línea de cobro por cada cuenta de forma de pago y el detalle de impuestos. Las devoluciones de tickets van en su propio asiento.
• Crea en SAP cada factura con cliente (y cada abono) por separado. Antes busca al cliente por su NIF y, si no existe, lo da de alta como interlocutor comercial con los datos fiscales de la ficha de Ágora.
• Registra el cobro de cada factura con cliente y lo compensa contra la factura.
• Envía solo lo nuevo: si exportas otra vez el mismo día, los tickets que ya se enviaron no se repiten.
• Guarda cada envío en Contabilidad → Facturas SAP S/4HANA, con sus impuestos, sus cobros y la petición y la respuesta de SAP en cada paso, y permite reenviarlo.
• Avisa por correo y por Telegram de los locales, impuestos o formas de pago sin configurar y de los rechazos de SAP.

Qué no hace#

• No envía nada automáticamente cada noche en la versión actual del motor: la exportación se lanza desde el panel, por fecha. El campo Hora de generación fich. contable del formulario no programa ningún envío para este proveedor.
• No reintenta sola: lo que falla se reenvía a mano desde el listado de facturas.
• No envía productos ni familias: a SAP llegan importes por tipo de IVA y por forma de pago.
• No adapta los datos de organización de SAP, que van fijos en el código. Un SAP con otra sociedad, otra cuenta de ingresos u otra organización de ventas necesita un desarrollo de FOS.
• No trabaja en otra moneda ni en otro país: todo va en euros y con España como país.
• No envía los tickets de la serie T02: el código la excluye.
• La casilla Habilitado de un local no detiene su envío (ver Configuración).
• No anula documentos en SAP: una devolución de Ágora se envía como un documento más (abono o asiento de devolución).

Requisitos#

• Un sistema SAP S/4HANA accesible por HTTPS desde internet y un usuario técnico (usuario y contraseña, autenticación básica) con permiso para estos servicios:
  • Asientos contables: crear (journalentrycreaterequestconfi), modificar (journalentrybulkchangerequest_) y compensar (journalentrybulkclearingreques).
  • Solicitud de documento de facturación (billingdocumentrequest_in).
  • Consulta de documentos de facturación (OData api_billingdocument).
  • Interlocutores comerciales (OData API_BUSINESS_PARTNER).
• En SAP, el campo personalizado de referencia externa en la solicitud de facturación (YY1_ExternalReference) y su réplica en la cabecera de la factura (YY1_ExternalReference_BDH). Con él localiza Connect Manager la factura que acaba de crear.
• La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect, con su API key. Si el cliente tiene varios locales en un Ágora central, la del ACMS.
• Si SAP filtra por IP, autorizar las direcciones IP salientes de Connect Manager.
• Reparto de tareas: FOS da de alta el local y la integración; el técnico completa locales, impuestos y formas de pago con los códigos que le pasa el consultor SAP; el consultor prepara el usuario técnico y los servicios en SAP.

Datos que necesitamos#

Configuración paso a paso#

En SAP (consultor del cliente)#

1. Crea el usuario técnico y habilita para él los servicios de la lista de Requisitos.
2. Comprueba que existe el campo de referencia externa en la solicitud de facturación y en la cabecera de la factura.
3. Revisa la tabla de valores fijos y confirma que la sociedad, la cuenta de ingresos, la organización de ventas y el resto existen y son los del cliente.
4. Prepara los códigos de impuesto, un material por tipo de IVA y la cuenta de cobro de cada forma de pago.

En Connect Manager: el local y la integración#

1. Entra en app.connectmanager.es y ve a Administración → Locales. Abre el local.
2. Revisa URL de API, API key y Zona horaria (con ella se calcula la fecha de los documentos) y pulsa Guardar.
3. En Integraciones de contabilidad, FOS crea la integración con el proveedor SAP HANA (BTP). Ábrela por la pestaña Configuración.
4. Rellena Usuario, Password y URL Api (la dirección base de SAP).
5. En Email de receptor de notificaciones pon uno o varios correos separados por comas, y si el cliente quiere avisos por Telegram, su Id. de chat de Telegram para recibir notificaciones.
6. Pulsa Guardar. El campo Hora de generación fich. contable no tiene efecto en este proveedor: déjalo vacío.

En Connect Manager: locales, impuestos y formas de pago#

1. Pestaña Locales: cada local de Ágora que factura necesita una fila. La primera exportación desde el widget de inicio añade solos todos los locales activos de Ágora; también puedes crearlos con Añadir, eligiendo el local en el buscador. En cada fila:
   • Código de cuenta: código del local en SAP. Sin él, el local no envía. Va en las referencias de los asientos y las facturas.
   • Cost center: centro de beneficio y de coste de las líneas. Si lo dejas vacío, se usa el código de cuenta.
   • No enviar excepciones de configuración: márcala solo en los locales que no deben enviar. Así se saltan sin generar avisos; los locales sin código de cuenta y sin esta casilla avisan en cada exportación.
   • Habilitado: no cambia nada en el envío actual.
2. Pestaña Impuestos: pulsa Añadir por cada tipo de IVA que se vende, elige el impuesto de Ágora y rellena Id. de SAP (código de impuesto), Id. material SAP (material con el que se facturan las ventas de ese IVA en las facturas con cliente) y, si quieres, Nombre SAP (texto de asignación; si falta, se usa el código). El impuesto se asocia por porcentaje.
3. Pestaña Métodos de pago: añade cada forma de pago de Ágora con su Id. de SAP (cuenta de cobro). Nombre SAP y Código de pago son opcionales: el código de pago se combina con el código de cuenta del local en la asignación del cobro (si falta, se usa la cuenta).

[!TIP] Si los buscadores de local, impuesto o forma de pago no muestran nada, Connect Manager no llega a la API de Ágora: revisa la URL y la API key del local.

En Ágora#

• No hay que instalar informes ni acciones personalizadas: la integración solo lee por la API.
• Para las facturas con cliente, la ficha del cliente necesita NIF, nombre fiscal y dirección completa: con esos datos se busca o se crea en SAP.
• Los tickets de la serie T02 no se envían. Si el cliente factura con esa serie, avisa a FOS.

Lanzar la exportación#

1. Todos los locales a la vez: en Home, widget Exportación SAP S/4HANA. Elige el Local de Connect Manager y la Fecha y pulsa Click para exportar. Verás «La petición de exportación de facturas se ha enviado.»
2. Un solo local de Ágora: en la pestaña Locales de la integración, botón Exportar de su fila. Elige la fecha y confirma; verás «Se ha enviado la solicitud de exportación de facturas».

Cómo funciona#

Cuando lanzas una fecha, Connect Manager pide a la API de Ágora las facturas de ese día, local a local. Los tickets se agrupan por local, tipo (venta o devolución) y serie, y cada grupo se convierte en un asiento contable que se envía a SAP. Si SAP devuelve un número de asiento, el grupo queda Enviado; si no, queda en Error de factura con el motivo, y llega un aviso. Las facturas con cliente siguen otro camino, más largo, descrito después.

sequenceDiagram
    participant T as Técnico
    participant CM as Connect Manager
    participant AG as API de Ágora
    participant SAP as SAP S/4HANA
    T->>CM: Exportar una fecha
    CM->>AG: Facturas del día de cada local
    AG-->>CM: Tickets, facturas y devoluciones
    CM->>CM: Agrupa los tickets por local, tipo y serie
    CM->>SAP: Asiento contable de cada grupo
    SAP-->>CM: Número de asiento o error
    CM->>CM: Estado Enviado o Error de factura

Qué se envía en el asiento de tickets#

• Cabecera: fecha del día exportado, referencia FRS_ seguida del código de cuenta del local, y texto con el primer y el último ticket del grupo (serie y número con seis cifras, por ejemplo T1000123-T1000187).
• Ingresos: una línea por tipo de IVA en la cuenta de ingresos fija, con la base imponible, el código de impuesto, el nombre SAP del IVA como asignación y el centro de coste del local. La base se calcula a partir del total con IVA de cada tipo.
• Cobros: una línea por cuenta de cobro (las formas de pago con la misma cuenta se suman), con el código de cuenta del local y el código de pago como asignación. El importe de la forma de pago con Id. 16 de Ágora («resto sin devolución») se suma a la otra forma de pago del mismo ticket.
• Impuestos: una línea por tipo de IVA con la cuota y la base.

Facturas con cliente#

Cada factura con cliente y cada abono se envían uno a uno y en varios pasos. Primero se busca al cliente en SAP por su NIF y, si no existe, se crea. Después se pide a SAP el documento de facturación, con una posición por tipo de IVA (el material SAP de ese IVA y el importe con IVA) y la referencia externa FRA- + código de cuenta + año + serie + número. A los cinco segundos se consulta en SAP la factura por esa referencia para obtener su asiento, se escribe la referencia en el asiento, se crea el asiento de cobro con las cuentas de las formas de pago y, por último, se compensan factura y cobro.

sequenceDiagram
    participant CM as Connect Manager
    participant SAP as SAP S/4HANA
    CM->>SAP: Busca el cliente por NIF
    alt No existe
        CM->>SAP: Crea el interlocutor comercial
    end
    CM->>SAP: Solicitud de factura con una posición por IVA
    CM->>SAP: Consulta la factura por su referencia externa
    SAP-->>CM: Número de factura y de asiento
    CM->>SAP: Escribe la referencia en el asiento
    CM->>SAP: Asiento de cobro por forma de pago
    CM->>SAP: Compensa la factura con el cobro

Cada paso deja su estado: Facturado, Asiento contable encontrado, Factura asignada, Factura pagada y, al final, Enviado. Si un paso falla, la factura se queda en ese punto (Error de factura, Asiento contable no encontrado, Error de asignación de factura, Error de pago…) y al reenviarla continúa desde ahí, sin repetir lo que ya está hecho.

El listado de envíos#

En Contabilidad → Facturas SAP S/4HANA ves cada grupo de tickets y cada factura con su local, tipo de documento (Ticket, Devolución, Factura, Devolución de fact.), serie, números inicial y final y estado. Puedes filtrar por Código de local, Estado, serie y fechas. Al abrir uno, la ficha muestra los identificadores de SAP (cliente, factura, asiento y asiento de cobro), los pasos 1 a 5 con la petición, la respuesta y el error de cada uno, y las pestañas de impuestos y de pagos.

Reenviar un día o un documento#

• Volver a exportar la fecha (widget o botón del local): solo envía los tickets posteriores al último ya enviado de cada serie, y retoma las facturas con cliente que no llegaron a Enviado. Puedes exportar el día en curso y repetir más tarde para mandar el resto.
• Exportar en el listado: selecciona uno o varios envíos y pulsa Exportar. Se vuelven a leer de Ágora con la configuración actual (útil después de corregir un impuesto o una forma de pago) y se reenvían si SAP no los tenía.
• Resetear: borra los identificadores y estados de SAP de los envíos seleccionados y los manda desde cero. Úsalo solo si has comprobado en SAP que el documento no existe.

[!WARNING] Resetear un documento que ya está en SAP, o reintentar uno que dio tiempo agotado sin comprobarlo, crea un duplicado en SAP. Revisa siempre antes en SAP la referencia FRS_… o FRA-….

Avisos#

Cualquier error de una exportación (local, impuesto o forma de pago sin configurar, Ágora sin respuesta, rechazo de SAP) genera un correo «Error en aplicación» con el local, la fecha y el mensaje, que llega a FOS y a los correos configurados, y el mismo aviso por Telegram si hay chat configurado.

Una asociación que falta (un local, un tipo de IVA o una forma de pago) detiene la exportación de ese local para ese día: lo que quedaba por preparar no se envía hasta que la completes y vuelvas a exportar la fecha.

Comprobar que funciona#

1. En un local configurado, haz un ticket de prueba y una factura a un cliente de prueba con NIF y dirección.
2. Lanza la exportación de ese día con el botón Exportar del local.
3. Abre Contabilidad → Facturas SAP S/4HANA y filtra por la fecha. El grupo de tickets debe estar en Enviado con su ID de asiento contable SAP; la factura, en Enviado con ID de cliente SAP, ID de factura SAP y los dos asientos.
4. En SAP, busca el asiento con la referencia FRS_ del local y la factura con la referencia FRA-; comprueba el interlocutor creado y que el cobro está compensado.
5. Vuelve a exportar la misma fecha: no debe aparecer nada nuevo ni duplicarse nada en SAP.
6. Repite con el widget Exportación SAP S/4HANA para un día completo y revisa que los demás locales salen en Enviado y que los que no deben enviar no generan avisos.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto SAP S/4HANA con Ágora?#

Con Connect Manager: FOS crea en el local la integración de contabilidad SAP HANA (BTP); tú pones la dirección y el usuario técnico de SAP y asocias locales, tipos de IVA y formas de pago a sus códigos de SAP. Después lanzas la exportación por fecha desde el panel.

¿La contabilidad se envía sola a SAP cada noche?#

No en la versión actual del motor. La exportación se lanza desde el widget Exportación SAP S/4HANA de Home o desde el botón Exportar de cada local, eligiendo la fecha.

¿Qué pasa si el cliente de una factura no existe en SAP?#

Connect Manager lo busca por NIF y, si no lo encuentra, lo crea como interlocutor comercial con el nombre fiscal, la dirección y el NIF de la ficha de Ágora. Si SAP rechaza el alta, la factura se queda en error con el mensaje de SAP.

¿Puedo volver a enviar un día sin duplicar?#

Sí: volver a exportar la misma fecha solo envía lo que falta, y el botón Exportar del listado reenvía únicamente lo que SAP no tiene. Lo único que puede duplicar es Resetear algo que ya estaba en SAP.

¿Sirve para cualquier SAP S/4HANA?#

No tal cual: la sociedad, la cuenta de ingresos, la organización de ventas y otros datos van fijos en el código. Si el SAP del cliente usa otros valores, FOS tiene que adaptar la integración antes de ponerla en marcha.

Referencias#

• Ficha de la integración en el catálogo: SAP S/4HANA.
• Direcciones IP salientes de Connect Manager, para autorizar el acceso a SAP.
• Glosario de Connect Manager.
• Documentación oficial de las API de SAP: SAP Business Accelerator Hub.