Integración de Workday con Ágora: ficheros de facturas y compras

La integración de Workday con Ágora genera cada noche, desde Connect Manager, los ficheros de carga de Workday con las ventas del día anterior (facturas y abonos), y prepara también los pedidos de compra y los albaranes de entrada, con un circuito de aprobación de pedidos por importe. El intercambio es por ficheros: se suben por SFTP o FTP y se envían por correo. Este manual es para el técnico que la configura junto al equipo de Workday del cliente.

[!WARNING] La integración se construyó para un cliente con teatros y eventos, y varias reglas de ese cliente van fijas en el código (códigos de cliente y proveedor por defecto, reglas para unos clientes concretos, calendario de subida de fin de semana). Antes de ofrecerla a otro cliente, FOS tiene que revisar esas reglas con él.

Qué hace la integración#

• Cada noche, a la hora configurada, lee de la API de Ágora las facturas del día anterior y las convierte en facturas de cliente de Workday, con numeración propia correlativa.
• Asigna a cada línea compañía, moneda, cliente, condiciones de pago, tipo de factura, categoría de ingreso, aplicabilidad e IVA, centro de coste, split, proyecto, teatro y producción, a partir de lo configurado en locales, teatros, familias e impuestos.
• Distingue las ventas hechas durante un evento (una franja horaria configurada por teatro): esas líneas usan los valores «para eventos» de la familia y llevan el nombre del evento como proyecto.
• Agrupa los tickets en facturas de Workday por teatro, tipo de sesión y serie, de hasta 1.500 € cada una (valor por defecto), y abre una factura nueva cuando cambia el cliente.
• Envía importes netos, sin IVA y con los descuentos repartidos; en el memo pone el rango de tickets, lo cobrado por forma de pago y las devoluciones con su ticket original.
• Separa los abonos en su propio fichero.
• Sube el CSV de facturas por SFTP o FTP y envía por correo el CSV y una versión en Excel.
• Lee cada noche los pedidos de compra y los albaranes de entrada del día anterior. Los pedidos pasan por aprobación por niveles de importe en Connect Manager, con aviso por correo a los aprobadores.
• Cada lunes y cada día 1 envía por correo el Excel de pedidos de compra y el de albaranes del periodo.
• Permite generar por fechas, desde Home, los ficheros de facturas, devoluciones, pedidos y entregas, y consultar exportaciones y pedidos en el menú Workday.

Qué no hace#

• No conecta con Workday por API: solo genera ficheros.
• No sube por SFTP o FTP los ficheros de pedidos ni de albaranes: solo van por correo.
• No sube el fichero de abonos: ese paso falla en el código y, cuando hay método de subida configurado, el fichero de abonos tampoco sale por correo. Los abonos se obtienen con el widget Devoluciones entre fechas (Workday).
• La aprobación de pedidos no cambia nada en Ágora ni decide qué pedidos van al fichero semanal: el Excel incluye todos los pedidos del periodo.
• No permite SFTP con clave privada desde el panel: Clave privada y Frase de contraseña aparecen en el formulario pero no se guardan. Usa usuario y contraseña.
• No vuelve a leer de Ágora un día que ya se generó bien, ni regenera un día si ya hay días posteriores generados (para no romper la numeración): eso lo hace FOS.
• No tiene pantalla para las equivalencias de clientes y proveedores de Workday: FOS las carga en el motor.

Requisitos#

• Un tenant de Workday con las cargas de facturas de cliente preparadas para leer el fichero (columnas en Cómo funciona) y los identificadores de compañía, clientes, centros de coste, categorías, proyectos, teatros, producciones y códigos de impuesto.
• Un servidor SFTP o FTP del cliente donde dejar los ficheros, con usuario y contraseña. Si filtra por IP, autoriza las direcciones IP salientes de Connect Manager.
• La API de Ágora (puerto 8984) accesible desde fuera, directamente o con Zero Connect. Si hay varios locales en un Ágora central, la URL y la API key del ACMS.
• En Ágora, todas las familias que se venden asociadas en la integración y todos los locales con ventas incluidos en algún teatro; para compras, los almacenes que reciben pedidos configurados.
• Reparto de tareas: FOS da de alta el local y la integración, carga las equivalencias de clientes y proveedores y es quien puede lanzar desde Home Generar contabilidad Workday y Generar compras Workday; el técnico completa la configuración con los códigos que da el equipo de Workday del cliente.

Datos que necesitamos#

Configuración paso a paso#

En Workday (equipo del cliente)#

1. Prepara la carga de facturas de cliente que leerá los ficheros …-CI-workday_invoices.csv (facturas) y …-CN-workday_invoices.csv (abonos) desde la carpeta del servidor de ficheros.
2. Pasa al técnico los identificadores de la tabla anterior, con los mismos códigos que existen en Workday.

En Connect Manager: la integración#

1. En app.connectmanager.es, ve a Administración → Locales, abre el local y revisa URL de API y API key.
2. En Integraciones de contabilidad, FOS crea la integración con el proveedor Workday. Ábrela por la pestaña Configuración.
3. Rellena Compañía, Código de moneda, Payment terms, Deferred revenue, Customer invoice type y Line item description. Cliente para tickets es obligatorio en el formulario, pero no se usa: el cliente de cada factura sale de los códigos de los locales y de las equivalencias.
4. Email de receptor de notificaciones (varios separados por comas) e Id. de chat de Telegram para recibir notificaciones: ahí llegan los ficheros y los avisos de error. Si los dejas vacíos, solo llegan a FOS.
5. Hora de generación fich. contable: hora de la pasada nocturna, entre 1:00 y 7:00 en tramos de 10 minutos. Recomendado: entre las 3:00 y las 7:00.
6. En Configuración de subida de ficheros: Método de subida de ficheros (FTP o SFTP; con «-» no se sube nada y solo se envía por correo), Usuario y Password, URL (S)FTP (solo el nombre del servidor, sin sftp://), Root (carpeta de destino), Puerto y Timeout en segundos; para FTP, Pasivo y SSL según el servidor.
7. Pulsa Guardar.

En Connect Manager: locales, teatros y eventos#

1. Pestaña Teatros: crea un teatro por cada unidad que Workday contabiliza aparte. Pon Nombre, elige en Locales los locales de Ágora que le pertenecen y rellena Split, Project, Theater y Production. Las ventas se agrupan por el valor de Theater. Todo local con ventas debe estar en algún teatro.
2. Pestaña Locales: añade cada local de Ágora con sus tres códigos de cliente: Cód. de cliente, Código de cliente pago en Efectivo y Código de cliente pago en Tarjeta. El formulario pide también Split, Project y Theater; para las facturas mandan los del teatro.
3. Pestaña Eventos (opcional): para cada evento, Nombre, el teatro en Theater y Fecha de inicio, Hora de inicio, Fecha de fin y Hora de fin. Los tickets de ese teatro hechos dentro de la franja se tratan como venta de evento.

En Connect Manager: familias e impuestos#

1. Pestaña Familias: añade cada familia de Ágora que se vende con Split, Cost center, Revenue category y Tax applicability. Si las ventas de evento van a otros códigos, rellena Split para eventos, Cost center para eventos, Revenue category para eventos y Tax applicability para eventos (vacíos = se usan los normales). Marca No es aplicable a eventos si esa familia nunca debe llevar el evento como proyecto. Spend category y Cost object se usan en los pedidos de compra.
2. Pestaña Impuestos: añade cada tipo de IVA de Ágora con su Tax code de Workday.

En Connect Manager: compras#

1. Pestaña Almacenes: añade cada almacén de Ágora que recibe pedidos con Buyer id., Bill to contact, Ship to contact, Production purpose, Código de moneda, Project, Theater y Production. Configura todos: un pedido de un almacén sin configurar puede salir con datos de otro o hacer fallar la lectura.
2. Pestaña Intervalos de aprobación (opcional): crea los niveles de menor a mayor importe, porque se numeran por orden de creación. En cada uno, Importe mínimo, Importe máximo, los usuarios aprobadores y, si hace falta, Tiene que ser aprobado por todos. Sin niveles, todos los pedidos quedan aprobados.

En Ágora#

• Revisa que todas las familias con ventas estén en la pestaña Familias: una familia sin asociar detiene la generación del día.
• Para que una factura con cliente lleve su código de Workday, el cliente de Ágora debe tener el código contable correcto o estar en las equivalencias que carga FOS.
• En compras, los proveedores necesitan su código contable y las líneas, su unidad de compra.

Cómo funciona#

De madrugada, cada diez minutos, Connect Manager busca las integraciones de Workday cuya hora de generación coincide con la hora actual (hora de Madrid) y procesa el día anterior. Pide a Ágora las facturas de ese día, las agrupa y guarda las líneas de Workday en su base de datos. Según el día de la semana de las ventas, genera y sube el fichero y lo envía por correo. En paralelo, lee los pedidos de compra y los albaranes de entrada del mismo día.

sequenceDiagram
    participant CM as Connect Manager
    participant AG as API de Ágora
    participant FTP as SFTP del cliente
    participant M as Correo y Telegram
    CM->>AG: Facturas del día anterior
    AG-->>CM: Tickets, facturas y abonos
    CM->>CM: Agrupa por teatro, sesión y serie
    CM->>CM: Guarda las líneas con su numeración
    CM->>FTP: Sube el CSV de facturas
    CM->>M: Envía el CSV y el Excel
    CM->>AG: Pedidos de compra y albaranes del día
    AG-->>CM: Pedidos y albaranes
    CM->>M: Avisa a los aprobadores si hace falta

Calendario de subida#

Si un día no hay ventas, el fichero se genera vacío y se sube igualmente.

El fichero de facturas#

Es un CSV en UTF-8 con BOM y campos separados por barra vertical (|), llamado AAAAMMDD-HHMMSS-CI-workday_invoices.csv (abonos: …-CN-…). Cada fila es una línea de factura con estas columnas: Invoice ID, Company, Currency, Customer, Date, Payment Terms, Customer Invoice Type, Memo, Row ID, Revenue Category, Line Item Description, Tax Applicability, Tax Code, Extended Amount, Deferred Revenue, Cost Center, Project, Theater, Split, Production y Movement. El Excel que va por correo lleva los mismos datos sobre la plantilla de carga de Workday.

• Agrupación: por teatro, por tipo de sesión (evento o normal) y por serie. Dentro, los tickets se acumulan hasta 1.500 € o hasta que cambia el cliente; entonces empieza otra factura con el siguiente número.
• Líneas: una por combinación de tipo de IVA, categoría de ingreso, centro de coste, split, proyecto y aplicabilidad. El importe es neto: total de la línea con los descuentos repartidos, dividido por (1 + IVA), en valor absoluto.
• Cliente: en las facturas con cliente, su equivalencia de Workday si existe, si no su código contable de Ágora y, si tampoco lo tiene, el del local; en los tickets, el código del local según la forma de pago (efectivo con la forma de pago 1 de Ágora, tarjeta con la 2, si no el general) y, si el local no tiene códigos, uno fijo del código.
• Eventos: en las ventas de evento, el proyecto es el nombre del evento y la producción va vacía, salvo en las familias marcadas como no aplicables.

Pedidos de compra y albaranes#

Cada pedido de compra del día se guarda con su compañía, proveedor, moneda, comprador y contactos (del almacén), y sus líneas con artículo, cantidad, unidad (un, kilo, litro y caja se convierten en EA, KGM, LTR y BX), coste unitario, centro de coste, split, spend category y cost object (de la familia). Si el total del pedido llega al importe mínimo del primer nivel, el pedido queda pendiente y los aprobadores reciben el correo «Pedido pendiente de aprobación» con el botón Revisar.

flowchart TD
    A[Pedido leído de Ágora] --> B{Hay niveles de aprobación}
    B -- No --> C[Aprobado]
    B -- Sí --> D{Total igual o mayor que el mínimo del nivel 1}
    D -- No --> C
    D -- Sí --> E[Pendiente en el nivel y correo a sus aprobadores]
    E -- Rechaza --> R[Rechazado]
    E -- Aprueba --> F{Total igual o mayor que el máximo del nivel}
    F -- Sí --> G[Pasa al siguiente nivel]
    G --> E
    F -- No --> C

Se aprueba o rechaza en Workday → Pedidos pendientes de aprobación, con los botones Aprobar y Rechazar; la ficha muestra la Cadena de aprobación. Si el nivel exige que aprueben todos, el pedido no avanza hasta que lo hayan hecho todos sus usuarios.

Cada lunes y cada día 1, la pasada nocturna envía por correo el Excel de pedidos de compra y el de albaranes del periodo: los siete días anteriores, sin cruzar de mes (el día 1 sale lo que queda del mes que se cierra). Los errores de esta lectura no generan aviso: revisa Workday → Pedidos de compra.

Generar o reenviar un periodo#

• Desde Home, los widgets Facturas entre fechas (Workday), Devoluciones entre fechas (Workday), Pedidos entre fechas (Workday) y Entregas entre fechas (Workday) generan el fichero de un rango con lo ya guardado y te lo envían por correo. No suben nada al servidor.
• FOS dispone de Generar contabilidad Workday y Generar compras Workday para lanzar una fecha concreta. Si ese día ya se generó bien, no se vuelve a leer de Ágora: solo se repite la subida según el calendario.
• Un día que falló por configuración (una familia o un local sin asociar) se regenera completo al relanzarlo después de corregir, siempre que no haya días posteriores ya generados. Si los hay, llega el aviso «Existen facturas posteriores al día solicitado. Contacte con soporte@fos.systems.»

Las exportaciones generadas se consultan en Workday → Exportaciones, con su fecha, local, tipo y base imponible.

Comprobar que funciona#

1. Configura la hora de generación y espera a la pasada de esa noche (o pide a FOS que lance Generar contabilidad Workday para ayer).
2. En Workday → Exportaciones deben aparecer las exportaciones del día, de facturas y de abonos, con su base imponible.
3. Comprueba que ha llegado el correo «Archivo facturas Workday» con el CSV y el Excel, y que el CSV está en la carpeta del servidor (si las ventas son de lunes a jueves).
4. Revisa unas cuantas líneas: teatro, centro de coste, categoría e importe neto deben cuadrar con las ventas de Ágora de ese día.
5. Pide al equipo de Workday que cargue el fichero de prueba y confirme que no hay rechazos.
6. Para compras: confirma en Ágora un pedido de prueba por encima del primer nivel, comprueba al día siguiente el correo «Pedido pendiente de aprobación» y apruébalo en Pedidos pendientes de aprobación.

Errores frecuentes y solución#

Preguntas frecuentes#

¿Cómo conecto Workday con Ágora?#

Con Connect Manager: FOS crea en el local la integración de contabilidad Workday y tú configuras compañía, teatros, familias, impuestos y el servidor de ficheros. Cada noche se generan los ficheros de carga y Workday los importa desde el servidor.

¿Se envían las ventas a Workday por API?#

No. La integración genera ficheros CSV (y su versión Excel) que se suben por SFTP o FTP y se envían por correo; la carga en Workday la hace el propio Workday.

¿Por qué no se subió el fichero del viernes?#

Porque las ventas de viernes y sábado se suben el lunes, junto con las del domingo, en un único fichero.

¿Puedo regenerar un día que salió mal?#

Si falló por configuración, sí: corrige y relanza la fecha. Si el día ya se generó bien o hay días posteriores generados, tiene que hacerlo FOS para no romper la numeración de facturas.

¿La aprobación de pedidos bloquea el pedido en Ágora?#

No. La aprobación queda registrada en Connect Manager y avisa por correo, pero no cambia nada en Ágora ni filtra el Excel semanal de pedidos.

¿Sirve para un cliente que no sea un teatro?#

Los teatros son la forma de agrupar locales y pueden representar cualquier unidad de negocio, pero varias reglas del cliente original están fijas en el código. FOS tiene que revisarlas antes de usarla con otro cliente.

Referencias#

• Ficha de la integración en el catálogo: Workday.
• Direcciones IP salientes de Connect Manager, para autorizar el acceso al servidor de ficheros.
• Glosario de Connect Manager.