0% encontró este documento útil (0 votos)

21 vistas167 páginas

Guía Del Integrador

El documento detalla las actualizaciones y cambios en las versiones del software Ágora, incluyendo mejoras en la importación y exportación de datos, correcciones de errores y nuevas propiedades. Se describen los servicios de integración con otras aplicaciones, así como el formato y las secciones del fichero de importación de datos. Además, se explican las configuraciones para la importación y exportación automática, junto con ejemplos de estructuras XML y JSON para facilitar su uso.

Cargado por

vitali

Derechos de autor

Nos tomamos en serio los derechos de los contenidos. Si sospechas que se trata de tu contenido, reclámalo aquí.

Formatos disponibles

Descarga como PDF, TXT o lee en línea desde Scribd

0% encontró este documento útil (0 votos)

21 vistas167 páginas

Guía Del Integrador

Cargado por

vitali

Derechos de autor

Nos tomamos en serio los derechos de los contenidos. Si sospechas que se trata de tu contenido, reclámalo aquí.

Formatos disponibles

Descarga como PDF, TXT o lee en línea desde Scribd

Lista de Cambios

Versión 5.0.0
▪ En esta versión se permiten importar y exportar formatos de venta. Es compatible con
versiones anteriores excepto porque ahora al exportar añadidos de un producto en el
nodo Addin se está indicando el Id del añadido en un atributo SaleFormatId en lugar
de ProductId. A la hora de importar se permite usar tanto SaleFormatId como
ProductId para mantener compatibilidad con versiones antiguas.

Versión 5.0.2
▪ Corregido error al exportar datos en formato JSON. Los valores de tipos enumerados se
enviaban en formato numérico en lugar de en formato texto, tal y como se recogía en la
documentación.

Versión 5.0.4
▪ Corregido error al intentar importar documentos con añadidos cuando el id del producto
añadido no coincidía con el id del formato de venta.

Versión 5.0.7
▪ Se permite importar y exportar mútiples grupos de añadidos para los productos. Se
mantiene la compatibilidad con el formato anterior, aunque pasa a considerarse
obsoleto y en un futuro desaparecerá.

Versión 5.0.8
▪ Corregido error al exportar productos. Se estaba exportando mal el valor de
PreparationOrder (se estaba enviando dos veces el valor del PreparationType).

Versión 5.0.9
▪ Desaparece la propiedad ShowInKitchenDisplays de PreparationType porque ya no
existe en Ágora. A partir de esta versión Ágora detecta automáticamente si se debe
enviar a un tipo de preparación o no a los monitores basándose en la existencia de
monitores que estén configurados para mostrar ese tipo de preparación asociados al
punto de venta que generó la preparación.

▪ Al importar en un servidor de centralización un documento (pedido o albarán) y

modificar su estado, se propaga el cambio a los clientes de centralización para que no
puedan actualizar más el documento.

Versión 5.1.0
▪ Aparece la propiedad Notes en las líneas de pedidos a proveedor, albaranes de entrada
y facturas de compra.

Guía del Integrador 2 Versión 5.1.0

▪ Cambiado valor OnSelectTable del importador de Centros de Venta a OnOpenDocument

Guía del Integrador 3 Versión 5.1.0

Servicios de Integración con Otras
Aplicaciones

Los servicios de integración de Ágora le permiten traspasar información entre Ágora y otras
aplicaciones, como por ejemplo un ERP o un programa de contabilidad. Para poder utilizar estos
servicios deberá activar una licencia para el "Módulo de Servicios de Integración" desde la
opción Ayuda -> Activar Licencia de Módulo en el Monitor de Ágora:

Guía del Integrador 4 Versión 5.1.0

Después, deberá activar el módulo de servicios de integración desde la opción Herramientas ->
Activar Módulos Adicionales :

Tras activar el módulo de servicios de integración, podrá usar la herramienta de integración de

Ágora Integration Services para importar y exportar datos en formato XML. Los servicios de
integración de Ágora se controla con la aplicación de línea de comandos ais.exe que encontrará
en la carpeta de instalación de Ágora. Las opciones de esta aplicación son:

▪ --import <file_name>: Realiza la importación de los datos incluidos en el fichero

indicado como parámetro

▪ --export <file_name> [fecha en formato aaaa-mm-dd]: Exporta los datos

generados por Ágora y los almacena en el fichero indicado. Si no se especifica ninguna
fecha, se exportarán todos los datos correspondientes a la fecha de negocio del día
actual. Si se indica una fecha, se exportarán los datos de la fecha indicada.

▪ --export-master <file_name> [tipos de datos a exportar]: Exporta los datos

maestros registrado en Ágora y los almacena en el fichero indicado. Si no se especifica
ningún tipo de datos a exportar, se exportarán todos los datos que pueden ser
importados en Ágora. Si desea limitar el tipo de datos a exportar, puede introducir
uno o más de los siguientes tipos separados por comas:

▪ Series: series

▪ Customers: clientes

▪ Users: usuarios

Guía del Integrador 5 Versión 5.1.0

▪ Vats: tipos de impuestos

▪ PaymentMethods: formas de pago

▪ PriceLists: tarifas

▪ SaleCenters: centros de venta

▪ Families: familias

▪ Products: productos

▪ Menus: menús

▪ Offers: promociones

▪ Warehouses: almacenes

▪ Stocks: stocks actuales

Si, por ejemplo, desea exportar únicamente usuarios y clientes, debería utilizar la línea
de comandos
ais.exe --export-master datos.xml Users,Customers.

▪ --validate <file_name>: Valida que el formato del fichero que se va a importar es

correcto, indicando los posibles errores encontrados.

El formato de los ficheros de importación y exportación se detalla en las siguientes secciones de

este manual.

Al ejecutar la aplicación se mostrará en pantalla el resultado de la operación. Además, el código

de retorno del proceso indicará el resultado de la operación:

▪ 0: Ejecución completada con éxito

▪ -1: Parámetros de línea de comandos incorrectos

▪ -2: Error al realizar exportación de ventas

▪ -3: Error al realizar importación

▪ -4: Error al realizar validación

▪ -5: Error al realizar exportación de datos maestros

Importación y Exportación Automática

Si lo desea, puede configurar el módulo de servicios de integración para que el proceso de
importación y exportación de datos se realice de forma automática. Para ello deberá activar las
opciones correspondientes al configurar el módulo de servicios de integración.

Cuando la exportación automática está habilitada, al emitir un factura, realizar un cargo en

cuenta, cancelar un cargo en cuenta, crear un movimiento de caja, cerrar una caja o efectuar
un cierre de sistema, se generará automáticamente un fichero con la información relativa al
evento en la carpeta indicada. El formato de los documentos generados es el mismo que cuando
se realiza una exportación manual utilizando ais.exe.

Guía del Integrador 6 Versión 5.1.0

Cuando se activa la importación automática, Ágora estará continuamente monitorizando el
contenido de la carpeta indicada y, tan pronto como encuentre ficheros con la extensión .xml,
intentará importarlos. Si la importación se produce con éxito, se cambiará la extensión del
fichero a .ok, y si se produce algún error, la extensión se cambiará a .error.

En caso de que se produzca algún error al importar o exportar, Ágora lo reflejará en el log del
servidor.

Formato de fichero de importación de datos

El fichero de importación de datos de Ágora permite especificar gran parte de la información
necesaria para trabajar con Ágora, incluyendo familias, productos, centros de venta, usuarios,
precios y clientes.

Al procesar el fichero de importación, Ágora procesará cada registro secuencialmente realizando

las siguientes acciones:

▪ Si no existe un registro en Ágora con el mismo Id que el registro procesado, se creará

el registro en Ágora.

▪ Si ya existe un registro en Ágora con el mismo Id que el registro procesado, se

actualizará la información de ese registro.

▪ Si el registro procesado incluye un valor para el campo fecha de borrado,

DeletionDate, el registro se considerará borrado y será marcado como tal en Ágora. Si
no incluye ese campo se considerará que el registro está activo y, en caso de que
estuviera borrado en Ágora, se volverá a activar.

Ágora no realizará ninguna acción sobre la información existente en Ágora que no aparezca en
el fichero de datos importados. Es decir, si por ejemplo se crea un producto en Ágora y luego el
producto no aparece en el fichero, el producto seguirá existiendo en Ágora.

Este sistema permite mucha flexibilidad, porque es posible realizar importaciones totales o
parciales. Cuando se realiza la puesta en marcha de la aplicación se puede enviar un fichero con
la base de datos completa y, a partir de ese momento, enviar sólo en el fichero aquellos
registros que sea necesario crear, modificar o eliminar. Ante cualquier problema, siempre se
puede volver a enviar la base de datos completa.

La información recibida en el fichero siempre sobreescribe la información existente en Ágora.

Si, por ejemplo, se modifica un precio en Ágora y luego se vuelve a importar un fichero con el
precio original, se perderá la modificación realizada en Ágora.

El tratamiento de los campos opcionales, excepto en el caso de la fecha de borrado que se ha

explicado anteriormente, será el siguiente: Si el campo no aparece en el fichero XML, se
mantendrá el valor que exista actualmente en la base de datos de Ágora. Si el campo aparece
en el fichero XML, se sobreescribirá el valor de Ágora con el valor indicado, incluso si éste es
vacío (siempre que sea posible). Por ejemplo, si el campo FamilyId de un producto no aparece
en el fichero, se mantendrá la familia asociada actualmente a ese producto. Si el campo

Guía del Integrador 7 Versión 5.1.0

FamilyId contiene un Id de familia, se asociará ese producto a la familia indicada, y si el campo
FamilyId está vacío, se quitará la familia que tuviera asociada el producto.

Hay ocasiones en que un campo es opcional pero no puede dejarse vacío. O bien aparece en el
XML con un valor válido, en cuyo caso se sobreescribirá el valor actual en Ágora, o bien no
aparece en el XML, en cuyo caso se mantiene el valor actual de Ágora. Esto ocurre, en general,
con campos que no permiten valores "nulos" o vacíos. Por ejemplo, el descuento de un cliente
puede indicarse con un valor numérico válido (incluyendo 0) para actualizarlo en Ágora, o puede
no indicarse para mantener el valor actual, pero no puede indicarse con un valor vacío porque
no es un valor válido para un número.

Recuerde que cuando haya generado el fichero de importación de datos, puede

utilizar la opción de validación de fichero de la herramienta ais.exe para
comprobar su validez.

El fichero de importación de datos consta de varias secciones como puede comprobar en el

fichero de ejemplo incluido junto a este manual. Debe respetarse el orden en que aparecen en
el fichero.

XML:

Guía del Integrador 8 Versión 5.1.0

<?xml version='1.0' encoding='utf-8'?>
<Import>
<Users>

</Users>
<Customers>

</Customers>
<Series>

</Series>
<PaymentMethods>

</PaymentMethods>
<Vats>

</Vats>
<PreparationTypes>

</PreparationTypes>
<PreparationOrders>

</PreparationOrders>
<Families>

</Families>
<PriceLists>

</PriceLists>
<SaleCenters>

</SaleCenters>
<Products>

</Products>
<Menus>

</Menus>
<SalesOrders>

</SalesOrders>
<DeliveryNotes>

</DeliveryNotes>
<Invoices>

</Invoices>
<Suppliers>

</Suppliers>

Guía del Integrador 9 Versión 5.1.0

</Import>

JSON:

{
"Users": [],
"Customers": [],
"Series": [],
"PaymentMethods": [],
"Vats": [],
"PreparationTypes": [],
"PreparationOrders": [],
"Families": [],
"PriceLists": [],
"SaleCenters": [],
"Products": [],
"Menus": [],
"SalesOrders": [],
"DeliveryNotes": [],
"Invoices": [],
"Suppliers": []
}

En cada sección del fichero habrá información que sea obligatoria e información opcional. Los
campos opcionales ni siquiera es necesario que aparezcan en el documento XML.

Utilizando la versión de demostración de Ágora es posible realizar pruebas de

importación y exportación completas. Le recomendable encarecidamente que
utilice dicha versión para poder generar datos de ejemplo con los diferentes casos
que se pueden presentar y así tener una visión más completa del proceso de
exportación y importación.

Los campos numéricos utilizan como separador de decimales el punto '.' y NO

utilizan separador de millares.

Los campos de tipo fecha utilizando como formato aaaa-mm-dd. Si además

incluye la hora, el formato es aaaa-mm-ddThh:mm:ss, por ejemplo
2012-01-29T21:00:54.

Series
Las series de documentos se indican dentro del elemento <Series> en etiquetas específicas
para cada serie:

Guía del Integrador 10 Versión 5.1.0

XML:

JSON:

{
"Series": {
"BasicInvoice": {
"Name": "T",
"LastNumber": 0
},
"StandardInvoice": {
"Name": "F",
"LastNumber": 99
},
"BasicRefund": {
"Name": "TD",
"LastNumber": 0
},
"StandardRefund": {
"Name": "FD",
"LastNumber": 0
},
"DeliveryNote": {
"Name": "ALB",
"LastNumber": 80
},
"SalesOrder": {
"Name": "PED",
"LastNumber": 91
}
}
}

Todas las series son opcionales, si no incluye una serie, no será modificada en Ágora. Las series
que puede indicar son:

▪ BasicInvoice: facturas simplicadas.

▪ StandardInvoice: facturas normales.

▪ BasicRefund: facturas simplificadas de devolución.

Guía del Integrador 11 Versión 5.1.0

▪ StandardRefund: facturas de devolución normales.

▪ DeliveryNote: albaranes/cargos en cuenta.

▪ SalesOrder: pedidos/reservas.

Para cada serie, podrá indicar:

Name [Obligatorio]
Nombre de la serie.

LastNumber
último documento generado en esa serie. El siguiente documento que se genere en esa
serie tendrá como número LastNumber+1.

Si no se indica LastNumber y la serie no existía, el primer documento que se genere tendrá

como número 1. Si la serie ya existía, se respetará el orden que tuviera. En caso de que la serie
ya exista y se indique como LastNumber un valor inferior al actual, se generará un error para
evitar crear documentos con número duplicado.

Nota: la importación de series sólo está disponible para instalaciones de tipo

independiente.

Usuarios
Los usuarios se indican dentro del elemento <Users> en sucesivos elementos <User>:

XML:

Guía del Integrador 12 Versión 5.1.0

JSON:

Guía del Integrador 13 Versión 5.1.0

{
"Users": [
{
"Id": 10,
"Name": "Wilson Fernandez",
"Password": "1111",
"SmartphonePassword": "",
"WebAdminPassword": "154!Koaxo1{",
"ButtonText": "Wilson F.",
"Color": "#34112a",
"CardNumber": "#455232",
"Profile": "Admin",
"ShowInClockings": true,
"Priority": 2
"SocialSecurityNumber": "354879894614",
"Nif": "31183150A",
"Telephone": "687459813",
"Email": "[email protected]",
"City": "Getafe",
"Region": "Madrid",
"ZipCode": "28905",
"Street": "Avd. General Perón"
},
{
"Id": 11,
"Name": "Luciano",
"Password": "2222",
"Profile": "PowerUser",
"IsTrainee": false
},
{
"Id": 12,
"Name": "Conchita",
"Password": "3333",
"Profile": "User",
"DeletionDate": "2012-12-24T15:00:00",
"Telephone": "916845793",
"Email": "[email protected]"
}
]
}

Para cada usuario podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único del usuario.

Name [Obligatorio]
Nombre del usuario.

Guía del Integrador 14 Versión 5.1.0

Password
Contraseña del usuario para acceder al TPV. Puede dejarse vacía para permitir el
acceso de este usuario sin contraseña.

SmartphonePassword
Contraseña del usuario para acceder a la comandera. Puede dejarse vacía para
permitir el acceso de este usuario sin contraseña.

WebAdminPassword
Contraseña del usuario para acceder a la administración. Puede dejarse vacía para
permitir el acceso de este usuario sin contraseña.

ButtonText
Texto mostrado en el botón asociado al usuario en el punto de venta.

Color
Color del botón asociado al usuario en el punto de venta. El formato es #RRGGBB,
como los ejemplos mostrados en el anexo I.

CardNumber
Código de la tarjeta de acceso asociada al usuario.

IsTrainee
Indica si es un usuario en formación. Por defecto no lo es.

Profile
Perfil del usuario. Los posibles valores son:

▪ Admin: perfil de "Administrador" generado por defecto en Ágora.

▪ PowerUser: perfil de "Encargado" generado por defecto en Ágora.

▪ User: perfil de "Camarero" generado por defecto en Ágora.

▪ nombre_de_perfil: perfil con el nombre nombre_de_perfil. Debe existir

previamente en Ágora.

ShowInClockings
Indica si el usuario se muestra en la pantalla de fichajes o no.

DeletionDate
Fecha de borrado del registro. Sólo se debe incluir este atributo en caso de querer
eliminar el registros. Si se incluye este atributo con un valor de fecha y hora válido, se
considerará que el registro ha sido dado de baja. El formato de fechas soportado es
aaaa-mm-ddThh:mm:ss, por ejemplo 2012-01-31T10:59:20.

SocialSecurityNumber
Número de la Seguridad Social del usuario.

Nif
NIF del usuario.

Telephone
Número de teléfono del usuario.

Guía del Integrador 15 Versión 5.1.0

Email
Email del usuario.

Street
Dirección del usuario.

City
Población del usuario.

Region
Provincia del usuario.

ZipCode
Código postal del usuario.

CompanyName
Nombre de empresa que se va a usar en los informes de fichajes.

CompanyCif
CIF de empresa que se va a usar en los informes de fichajes.

CompanyCCC
Código de cuenta contable de la empresa que se va a usar en los informes de fichajes.

AutoClockOutMaxHours
Max. horas jornada: Si está presente activa el fichaje salida automático e indica el
máximo número de horas permitidas desde la última entrada.

Clientes
Los clientes se indican dentro del elemento <Customers> en sucesivos elementos <Customer>:

XML:

Guía del Integrador 16 Versión 5.1.0

JSON:

Guía del Integrador 17 Versión 5.1.0

{
"Customers": [
{
"Id": 100,
"FiscalName": "Pedro García",
"Cif": "50748345-B",
"BusinessName": "PedroLan",
"Street": "Avd. Marcos Retuerto, S/N",
"City": "Getafe",
"Region": "Madrid",
"ZipCode": "28054",
"DiscountRate": 0.25,
"ApplySurcharge": true,
"AccountCode": "",
"CardNumber": "123",
"Telephone": "910555615",
"ContactPerson": "Pedro",
"Email": "[email protected]",
"Notes": "Preguntar por Recargo",
"ShowNotes": true,
"SendMailing": true
},
{
"Offers": [
{
"Id": 102
}
],
"Id": 101,
"FiscalName": "Lucas Grijander",
"Cif": "50748346-B",
"PriceListId": 20
},
{
"Id": 102,
"FiscalName": "María Laroca",
"Cif": "50748347-B",
"DeletionDate": "2012-12-24T15:00:00"
}
]
}

Para cada cliente podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único del cliente.

FiscalName [Obligatorio]
Nombre fiscal del cliente.

Guía del Integrador 18 Versión 5.1.0

BusinessName
Nombre comercial del cliente.

Cif
CIF/NIF del cliente. Puede dejar este campo vacío si desea crear un cliente sin CIF o
quitar el CIF de un cliente, pero recuerde que no podrá emitir facturas a clientes sin
CIF.

Street
Dirección del cliente.

City
Población del cliente.

Region
Provincia del cliente.

ZipCode
Código postal del cliente.

DiscountRate
Tanto por uno de descuento del cliente, por ejemplo, si le desea aplicar un 10% de
descuento, este valor debería ser 0.1.

ApplySurcharge
Indica si al cliente se le aplica recargo de equivalencia o no.

CardNumber
Código de la tarjeta de acceso asociada al cliente.

PriceListId
Identificador de la tarifa asociada al cliente (si la tiene).

Telephone
Teléfono del cliente.

Email
Correo electrónico del cliente.

ContactPerson
Persona de contacto.

Notes
Notas asociadas al cliente.

ShowNotes
Indica si se muestran las notas del cliente cuando se le asigna a un documento de
venta.

SendMailing
Indica si el cliente recibe o no publicidad desde el módulo de e-mailing.

AccountCode
Código de la cuenta contable asignada al cliente.

Guía del Integrador 19 Versión 5.1.0

Offers
Promociones que se aplican al ticket de asociado a un cliente. Las promociones deben
tener como "ApplicationMode" el valor "SelectedCustomerOrTickets". Cada promoción
debe indicarse en un elemento Offer con un atributo Id que contenga el Id de la
promoción asignada.

Si se va a permitir el alta de clientes tanto en Ágora como en un sistema externo, es necesario

coordinar ambas aplicaciones para evitar problemas con los códigos de cliente.

Los clientes creados en Ágora tendrán IDs inferiores a 500000 o superiores a 1000000000, por
lo que podrá configurar el otro sistema para que genere clientes en ese rango de IDs para evitar
colisiones.

Formas de Pago
Las formas de pago se indican dentro del elemento <PaymentMethods> en sucesivos elementos
<PaymentMethod>:

XML:

JSON:

Guía del Integrador 20 Versión 5.1.0

{
"PaymentMethods": [
{
"Id": 2,
"Name": "Tarjeta",
"GiveChange": false,
"IncludeInBalance": false,
"OpenCashDrawer": false,
"RegisterTip": true,
"AllowOverPaid": false,
"AllowExtraInformation": false,
"IsValidForSale": true,
"IsValidForPurchase": false,
"ExtractTipFromCashdrawer": true,
"Priority": 1
},
{
"Id": 3,
"Name": "Cheque Restaurante",
"GiveChange": false,
"IncludeInBalance": false,
"OpenCashDrawer": false,
"RegisterTip": false,
"AllowOverPaid": true,
"AllowExtraInformation": false
"IsValidForSale": false,
"IsValidForPurchase": false,
"ExtractTipFromCashdrawer": false
}
]
}

La forma de pago con Id 1 se corresponde con la forma de pago 'Efectivo' de

Ágora y no puede ser modificada, por lo que no podrá ser incluida dentro del
fichero de importación.

Para cada forma de pago podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único de la forma de pago.

Name [Obligatorio]
Nombre de la forma de pago.

GiveChange
Indica si al pagar con esta forma de pago se devolverá cambio, por ejemplo, en el caso
de pago en efectivo se devuelve cambio, pero si paga con un "vale" o con un "cheque
restaurante", puede decidir no devolver cambio.

Guía del Integrador 21 Versión 5.1.0

IncludeInBalance
Indica si el importe pagado con esta forma de pago debe tenerse en cuenta al hacer el
conteo de monedas durante el arqueo de caja. En general, sólo la forma de pago
Efectivo (recuerde que siempre existe en Ágora y no puede ser importada) debería
incluirse en el arqueo de caja.

OpenCashDrawer
Indica si se debe abrir el cajón portamonedas automáticamente cuando se realiza un
cobro con esta forma de pago.

RegisterTip
Indica si el usuario debe introducir la propina que se ha recibido mediante esta forma
de pago. Si se marca esta opción, cuando se cierra un ticket se permite al usuario
indicar el importe de la propina recibida mediante esta forma de pago.

AllowOverPaid
Indica si se puede pagar más del importe total con esta forma de pago. Por ejemplo,
con un cheque restaurante se puede pagar más del importe total del ticket, pero no
tarjeta de crédito no.

IsValidForSale
Indica si la forma de pago es válida para realizar ventas. Si no lo es no aparecerá
como forma de pago para realizar la venta.

IsValidForPurchase
Indica si la forma de pago es válida para realizar compras. Si no lo es no aparecerá
como forma de pago para realizar la compra.

AllowExtraInformation
Indica si se puede asociar a la forma de pago notas. Útil para asociar códigos de barras
de un cheque restaurante, etc.

ButtonText
Texto mostrado en el botón asociado a la forma de pago en el punto de venta.

Color
Color del botón asociado a la forma de pago en el punto de venta. El formato es
#RRGGBB, como los ejemplos mostrados en el anexo I.

Priority
Indica el orden que tomarán las formas de pago en la pantalla de cobros.

ExtractTipFromCashdrawer
Indica si, al aceptar pagos mediante esta forma de pago, las propinas se descuenten
del saldo del cajón.

Guía del Integrador 22 Versión 5.1.0

Impuestos
Los impuestos se indican dentro del elemento <Vats> en sucesivos elementos <Vat>:

XML:

JSON:

Guía del Integrador 23 Versión 5.1.0

{
"Vats": [
{
"Id": 1,
"Name": "Exento",
"VatRate": 0.00,
"SurchargeRate": 0.000
},
{
"Id": 2,
"Name": "Super reducido",
"VatRate": 0.04,
"SurchargeRate": 0.005
},
{
"Id": 3,
"Name": "Reducido",
"VatRate": 0.10,
"SurchargeRate": 0.014
},
{
"Id": 4,
"Name": "General",
"VatRate": 0.21,
"SurchargeRate": 0.052
},
{
"Id": 5,
"Name": "Especial",
"VatRate": 0.33,
"SurchargeRate": 0.15,
"Enabled": false
}
]
}

Ágora soporta hasta 10 tipos de impuestos que pueden ser indicados a través del fichero de
importación de datos. Cada tipo de impuesto debe tener un Id asociado entre 1 y 10 (inclusive).
Para cada tipo de impuesto podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único del tipo de impuesto. Deberá ser un valor entre 1 y 10.

Name [Obligatorio]
Nombre del tipo de impuesto.

VatRate [Obligatorio]
Tanto por uno de impuesto. Por ejemplo, si el impuesto es del 21%, este valor será
0.21.

Guía del Integrador 24 Versión 5.1.0

SurchargeRate [Obligatorio]
Tanto por uno de recargo de equivalencia. Por ejemplo, si el recargo es del 0.5%, este
valor será 0.005.

Enabled [Obligatorio]
Permite indicar si el impuesto está habilitado (true) o no (false).

Proveedores
Los proveedores se indican dentro del elemento <Suppliers> en sucesivos elementos
<Supplier>:

XML:

JSON:

{
"Suppliers": [
{
"Id": 1,
"FiscalName": "Casbega S.A.",
"BusinessName": "Casbega",
"Cif": "A23429423",
"Street": "Avd. Real de Pinto",
"City": "Madrid",
"Region": "Madrid",
"ZipCode": "28021",
"AccountCode": "",
"ApplySurcharge": false,
"Email": "[email protected]",
"Telephone": "912341212",
"Web": "www.casbega.com",
"ContactPerson": "Isabel Pita",
"ShowSupplierProductsInPurchaseDocumentOnly" : false,
"WarnIfPurchaseDocumentAlreadyExists": false
}
]
}

Para cada proveedor podrá indicar los siguientes atributos:

Guía del Integrador 25 Versión 5.1.0

Id [Obligatorio]
Identificador numérico único del proveedor.

FiscalName [Obligatorio]
Nombre fiscal del proveedor.

BusinessName
Nombre comercial del proveedor.

Cif [Obligatorio]
CIF/NIF del proveedor.

Street
Dirección del proveedor.

City
Población del proveedor.

Region
Provincia del proveedor.

ZipCode
Código postal del proveedor.

ApplySurcharge
Indica si al proveedor compramos con recargo de equivalencia o no.

Telephone
Teléfono del cliente.

Email
Correo electrónico del cliente.

Web
Paígina web del proveedor.

ContactPerson
Persona de contacto.

AccountCode
Código de la cuenta contable asignada al proveedor.

ShowSupplierProductsInPurchaseDocumentOnly
Indica si, al crear documentos de compra para este proveedor, solo se muestra
productos asociados al mismo.

WarnIfPurchaseDocumentAlreadyExists
Indica si, al crear documentos de compra para este proveedor con un número de
documento ya existente, Ágora debe mostrar un aviso de advertencia.

Guía del Integrador 26 Versión 5.1.0

Almacenes
Los almacenes se indican dentro del elemento <Warehouses> en sucesivos elementos
<Warehouse>:

XML:

<Warehouses>
<Warehouse Id="100" Name="General"
Street="Avd. Marcos Retuerto, S/N" City="Getafe"
Region="Madrid" ZipCode="28054"
PurchaseOrderSerie="PC"
IncomingDeliveryNoteSerie="AC"
PurchaseInvoiceSerie="FC">
<FiscalInfo Cif="" FiscalName=""
UseInDocuments="false"/>
UpdateCostPricePolicy="PurchasePrice"
</Warehouse>
<Warehouse Id="101" Name="Entradas"/>
</Warehouses>

JSON:

{
"Warehouses": [
{
"Id": 100,
"Name": "General",
"Street": "Avd. Marcos Retuerto, S/N",
"City": "Getafe",
"Region": "Madrid",
"ZipCode": "28054",
"PurchaseOrderSerie": "PC",
"IncomingDeliveryNoteSerie": "AC",
"PurchaseInvoiceSerie": "FC",
"FiscalInfo": {
"UseInDocuments": false,
"FiscalName": "",
"Cif": ""
},
"UpdateCostPricePolicy": "PurchasePrice"
}
]
}

Para cada almacén podrá indicar los siguientes atributos:

Guía del Integrador 27 Versión 5.1.0

Id [Obligatorio]
Identificador numérico único del almacén.

Name [Obligatorio]
Nombre del almacén.

Street
Dirección del almacén.

City
Población del almacén.

Region
Provincia del almacén.

ZipCode
Código postal del almacén.

PurchaseOrderSerie
Serie para los pedidos a proveedor. Si no se especifica se usara la serie por defecto.

IncomingDeliveryNoteSerie
Serie para los albaranes de entrada. Si no se especifica se usara la serie por defecto.

PurchaseInvoiceSerie
Serie para las facturas de proveedor. Si no se especifica se usara la serie por defecto.

FiscalInfo
Información fiscal que se usa para la generación de documentos en pdf de los
documentos de compra, incluyendo:

FiscalName
Nombre Fiscal.

Cif
Cif.

UseInDocuments
Sí se usa en los documentos de compra o no. Si no se usa se usarán los datos de
empresa.

Delivered
El pedido ha sido servido totalmente desde algún albarán.

UpdateCostPricePolicy
Política de actualización de los precios de coste del Almacén a la hora de crear un
Albarán de Entrada asociado al mismo.

Guía del Integrador 28 Versión 5.1.0

Tipos de Preparación
Los tipos de preparación se indican dentro del elemento <PreparationTypes> en sucesivos
elementos <PreparationType>:

XML:

JSON:

{
"PreparationTypes": [
{
"Id": 1,
"Name": "Barra"
},
{
"Id": 2,
"Name": "Plancha"
},
{
"Id": 3,
"Name": "Freidora"
}
]
}

Para cada tipo de preparación podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único del tipo de preparación.

Name [Obligatorio]
Nombre del tipo de preparación.

Guía del Integrador 29 Versión 5.1.0

Órdenes de Preparación
Los órdenes de preparación se indican dentro del elemento <PreparationOrders> en sucesivos
elementos <PreparationOrder>:

XML:

JSON:

{
"PreparationOrders": [
{
"Id": 1,
"Name": "Bebidas",
"Priority": 0,
"CanBeRequested": false
},
{
"Id": 2,
"Name": "Primeros",
"Priority": 1,
"CanBeRequested": false
},
{
"Id": 3,
"Name": "Segundos",
"Priority": 2,
"CanBeRequested": true
}
]
}

Para cada orden de preparación podrá indicar los siguientes atributos

Id [Obligatorio]
Identificador numérico único del orden de preparación.

Name [Obligatorio]
Nombre del orden de preparación.

Guía del Integrador 30 Versión 5.1.0

Priority [Obligatorio]
Prioridad del orden de preparación. Al mostrarse en pantalla, en las comandas
impresas, y en los monitores de cocina, los órdenes de preparación aparecerán
ordenados por prioridad.

CanBeRequested [Obligatorio]
Indica si es posible marchar este órden de preparación (true) o no (false).

Familias
Las familias se indican dentro del elemento <Families> en sucesivos elementos <Family>:

XML:

JSON:

Guía del Integrador 31 Versión 5.1.0

{
"Families": [
{
"Id": 100,
"Name": "Refrescos",
"Color": "#00FF00",
"Order": 2
},
{
"Id": 101,
"Name": "Bocadillos",
"Color": "#FF0000",
"ButtonText": "BOCATAS",
"Order": 1
},
{
"Id": 102,
"Name": "Helados",
"DeletionDate": "2012-11-30T15:00:50"
},
{
"Id": 103,
"Name": "Sin Gas",
"Color": "#00FF00",
"ParentFamilyId": 100,
"ShowInPos": "false"
},
{
"Id": 104,
"Name": "Menús",
"Color": "#00FF00"
}
]
}

Para cada familia podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único de la familia.

Name [Obligatorio]
Nombre de la familia.

ButtonText
Texto mostrado en el botón asociado a la familia en el punto de venta.

Color
Color del botón asociado a la familia en el punto de venta. El formato es #RRGGBB,
como los ejemplos mostrados en el anexo I.

Guía del Integrador 32 Versión 5.1.0

ParentFamilyId
Identificador único de la familia padre de esta familia. La familia padre debe existir en
Ágora o aparecer en el documento XML de importación. Este valor sólo debe indicarse
para subfamilias. Si una familia deja de ser subfamilia de otra, deberá indicarse
dejando este atributo vacío.

ShowInPos
Permite indicar si la familia se visualiza o no en el punto de venta.

Order
Posición de la familia en el punto de venta. A la hora de mostrar las familias, se
ordenarán por el valor introducido en este campo. Las familias para las que no se haya
indicado el orden aparecerán al final de la lista de familias.

Tarifas
Las tarifas de venta se indican dentro del elemento <PriceLists> en sucesivos elementos
<PriceList>:

XML:

JSON:

{
"PriceLists": [
{
"Id": 20,
"Name": "Hora Feliz",
"VatIncluded": true
},
{
"Id": 21,
"Name": "Clientes VIP",
"VatIncluded": true
}
]
}

Para cada tarifa podrá indicar los siguientes atributos:

Guía del Integrador 33 Versión 5.1.0
Id [Obligatorio]
Identificador numérico único de la tarifa.

Name [Obligatorio]
Nombre de la tarifa.

VatIncluded [Obligatorio]
Indica si los precios en esta tarifa son con impuestos incluidos (true) o no (false).

Centros de Venta
Los centros de venta se indican dentro del elemento <SaleCenters> en sucesivos elementos
<SaleCenter>:

XML:

JSON:

Guía del Integrador 34 Versión 5.1.0

{
"SaleCenters": [
{
"SaleLocations": [
{ "Name": "S1" },
{ "Name": "S2" },
{ "Name": "S3" },
{ "Name": "S4" },
{ "Name": "S5" }
],
"Id": 10,
"Name": "Salón",
"PriceListId": 1,
"CurrentPriceListId": 1,
"ButtonText": "SALÓN",
"Color": "#341122",
"VatIncluded": true,
"AskForGuests": true,
"GuestProductId": 2,
"WhenAskForGuests": "OnCloseDocument"
"Priority": 2,
},
{
"SaleLocations": [
{ "Name": "T1" },
{ "Name": "T2" },
{ "Name": "T3" },
{ "Name": "T4" }
],
"Id": 11,
"Name": "Terraza",
"PriceListId": 2,
"CurrentPriceListId": 2,
"Color": "#00FF00",
"VatIncluded": false,
"DeletionDate": "2012-12-24T15:00:00"
}
]
}

Para cada centro de venta podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único del centro de venta.

Name [Obligatorio]
Nombre del centro de venta.

Guía del Integrador 35 Versión 5.1.0

PriceListId [Obligatorio]
Identificador de la tarifa por defecto del centro de venta. Está tarifa debe existir
previamente.

CurrentPriceListId
Identificador de la tarifa actual del centro de venta. Esta tarifa debe existir
previamente.

VatIncluded [Obligatorio]
Indica si los precios en esta tarifa son con impuestos incluidos (true) o no (false).

ButtonText
Texto mostrado en el botón asociado al centro de venta en el punto de venta.

Color
Color del botón asociado al centro de venta en el punto de venta. El formato es
#RRGGBB, como los ejemplos mostrados en el anexo I.

AskForGuests [Obsoleto]
Indica si al seleccionar una ubicación del centro de venta debe solicitarse (true) o no
(false) la introducción del número de comensales. Obsoleto, ver WhenAskForGuests

GuestProductId
Id del producto que se venderá automáticamente por cada comensal introducido al
seleccionar una ubicación del centro de venta. Si no desea que se realice la venta
automática de ningún producto, deberá incluir este atributo vacío. El producto deberá
existir en la base de datos. Tenga en cuenta que, durante el proceso de importación,
se realiza primero la importación de centros de venta y luego la de productos, por lo
que no es posible asignar como producto de servicio un producto que esté siendo
creado en la misma importación.

WhenAskForGuests
Indica cuando se debe solicitar la introducción del número de comensales. Los posibles
valores son (Never) Nunca, (OnOpenDocument) Al abrir documento y
(OnCloseDocument) Al cerrar documento

SaleLocations [Obligatorio]
Lista de ubicaciones/mesas existentes en el centro de venta, cada una de ellas debe
indicarse en un elemento SaleLocation con un único atributo Name que contenga el
nombre único de la ubicación dentro del centro de venta. En cada centro de venta debe
existir al menos ubicación.

Productos
Los productos se indican dentro del elemento <Products> en sucesivos elementos <Product>:

Guía del Integrador 36 Versión 5.1.0

XML:

Guía del Integrador 37 Versión 5.1.0

Guía del Integrador 38 Versión 5.1.0

</Addins>
<AddinRoles>
<AddinRole Name="Añadidos" ButtonText="Añadidos" Color="#BACDE2"
<Addin SaleFormatId="1"/>
<Addin SaleFormatId="4"/>
</AddinRole>
</AddinRoles>
<AdditionalSaleFormats>
<SaleFormat Id="401" Name="Chupito de DYC" Ratio="0.3"
ButtonText="Chupito de DYC" Color="#000000"
SaleableAsMain="true" SaleableAsAddin="true" AskForAddins="false">
<Prices>
<Price PriceListId="1" MainPrice="1.0" AddinPrice="1.0"/>
<Price PriceListId="2" MainPrice="1.5" AddinPrice="1.0"/>
</Prices>
</SaleFormat>
<SaleFormat Id="402" Name="Copa de DYC" Ratio="1.0"
ButtonText="Copa de DYC" Color="#000000"
SaleableAsMain="true" SaleableAsAddin="true" AskForAddins="false">
<Prices>
<Price PriceListId="1" MainPrice="5.0" AddinPrice="3.0"/>
<Price PriceListId="2" MainPrice="6.0" AddinPrice="4.0"/>
</Prices>
<Addins>
<Addin SaleFormatId="1" />
</Addins>
<AddinRoles>
<AddinRole Name="Añadidos" ButtonText="Añadidos"
<Addin SaleFormatId="1"/>
<Addin SaleFormatId="4"/>
</AddinRole>
</AddinRoles>
</SaleFormat>
</AdditionalSaleFormats>
</Product>
</Products>

JSON:

Guía del Integrador 39 Versión 5.1.0

{
"Products": [
{
"Barcodes": [
{
"BarcodeValue": "91000122"
},
{
"BarcodeValue": "81000122"
}
],
"StorageOptions": [
{
"WarehouseId": 1,
"Location": "S1.A90",
"MinStock": 5,
"MaxStock": 25
},
{
"WarehouseId": 1,
"Location": "S1.A90",
"MinStock": 10,
"MaxStock": 30
}
],
"Prices": [
{
"PriceListId": 10,
"Price": 2.50,
"AddinPrice": 0.00,
"MenuItemPrice": 0.00
},
{
"PriceListId": 11,
"Price": 3.00,
"AddinPrice": 0.00,
"MenuItemPrice": 0.00
}
],
"Id": 100,
"Name": "Coca Cola",
"FamilyId": 100,
"VatId": 3,
"ButtonText": "COCA-COLA",
"Color": "#341122",
"Barcode": "255223",
"Order": 1,
"UseAsDirectSale": true,
"AskForPreparationNotes": true,
"AskForAddins": true,
"PreparationTypeId": 1,

Guía del Integrador 40 Versión 5.1.0

"PreparationOrderId": 1,
"PLU": "0001"
},
{
"Id": 103,
"Name": "Pitiusa",
"FamilyId": 100,
"VatId": 3,
"PrintWhenPriceIsZero": false,
"DeletionDate": "1982-10-01T12:00:00"
},
{
"Prices": [
{
"PriceListId": 10,
"MainPrice": 2.50,
"AddinPrice": 0.00,
"MenuItemPrice": 0.00
},
{
"PriceListId": 11,
"MainPrice": 3.00,
"AddinPrice": 0.00,
"MenuItemPrice": 0.00
}
],
"Addins": [
{
"SaleFormatId": 100
}
],
"Id": 200,
"Name": "Ron Brugal",
"FamilyId": 101,
"Order": 1,
"VatId": 3,
"MinAddins": 0,
"MaxAddins": 1,
"SaleableAsMain": true,
"SaleableAsAddin": false
},
{
"Id": 301,
"Name": "Bocadillo de Jamón",
"FamilyId": 101,
"VatId": 3
},
{
"Id": 302,
"Name": "Bocadillo de Lomo",
"FamilyId": 101,

Guía del Integrador 41 Versión 5.1.0

"VatId": 3
},
{
"Prices": [
{
"PriceListId": 1,
"MainPrice": 3.0,
"AddinPrice": null
},
{
"PriceListId": 2,
"MainPrice": 4.0,
"AddinPrice": null
}
],
"Addins": [
{
"SaleFormatId": 1
},
{
"SaleFormatId": 4
}
],
"AddinRoles": [
{
"Name": "Añadidos",
"ButtonText": "Añadidos",
"Color": "#BACDE2",
"MinAddins": 0,
"MaxAddins": 1,
"UsePreparationType": 0,
"Addins": [
{
"AddinSaleFormatId": 4
},
{
"AddinSaleFormatId": 1
}
]
}
],
"AdditionalSaleFormats": [
{
"Id": 401,
"Name": "Chupito de DYC",
"Ratio": 0.3,
"ButtonText": "Chupito de DYC",
"Color": "#000000",
"SaleableAsMain": true,
"SaleableAsAddin": true,
"AskForAddins": false,

Guía del Integrador 42 Versión 5.1.0

"Prices": [
{
"PriceListId": 1,
"MainPrice": 1.0,
"AddinPrice": 1.0
},
{
"PriceListId": 2,
"MainPrice": 1.5,
"AddinPrice": 1.0
}
]
},
{
"Id": 402,
"Name": "Copa",
"Ratio": 1.0,
"ButtonText": "Copa",
"Color": "#000000",
"SaleableAsMain": true,
"SaleableAsAddin": true,
"AskForAddins": false,
"Prices": [
{
"PriceListId": 1,
"MainPrice": 5.0,
"AddinPrice": 3.0
},
{
"PriceListId": 2,
"MainPrice": 6.0,
"AddinPrice": 4.0
}
],
"Addins": [
{
"SaleFormatId": 1
}
],
"AddinRoles": [
{
"Name": "Añadidos",
"ButtonText": "Añadidos",
"Color": "#BACDE2",
"MinAddins": 0,
"MaxAddins": 1,
"UsePreparationType": 0,
"Addins": [
{
"AddinSaleFormat
}

Guía del Integrador 43 Versión 5.1.0

]
}
],
}
],
"Id": 400,
"Name": "Whisky DYC",
"BaseSaleFormatId": 400,
"FamilyId": 4,
"Color": "#341122",
"VatId": 2,
"MinAddins": 1,
"MaxAddins": 2,
"Order": 2,
"SaleableAsMain": true,
"SaleableAsAddin": false,
"AskForPreparationNotes": true
}
]
}

Para cada producto podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único del producto. Este ID se utilizará también para crear el
formato base del producto.

Name [Obligatorio]
Nombre del producto.

VatId [Obligatorio]
Id del impuesto de venta asociado al producto.

BaseSaleFormatId
Id de formato de venta base del producto. Si no se indica, se asumirá que el Id del
formato base coincide con el Id del producto y que no se van a utilizar formatos de
venta en Ágora.

FamilyId
Id de la familia a la que pertenece el producto. Si el producto no pertenece a ninguna
familia, deberá incluirse este atributo vacío.

ButtonText
Texto mostrado en el botón asociado al producto en el punto de venta.

PLU
Código PLU del menú. Debe ser una cadena numérica. Ejemplos: 0001, 33232, etc.

Guía del Integrador 44 Versión 5.1.0

Color
Color del botón asociado al producto el punto de venta. El formato es #RRGGBB, como
los ejemplos mostrados en el anexo I.

Barcodes
Lista de códigos de barras del producto. Cada uno de ellos debe indicarse en un
elemento Barcode con un único atributo Value que contenga el código de barras. En el
caso de esté asociado a una talla y color llevará ademñas los atributos ColorId y
SizeId.

StorageOptions
Opciones de almacenamiento del producto en cada almacén. Cada una debe indicarse
dentro de un elemento StorageOption con los siguientes atributos:

WarehouseId [Obligatorio]
Id del almacén.

Location [Obligatorio]
Ubicación del producto dentro del almacén. Si no desea asignar ninguna
ubicación, puede dejar el atributo vacío. Nota para productos con tallas y
colores: la ubicación dentro del almacén es única para todas las tallas y
colores de un mismo producto, por lo que debería replicar el mismo valor en
todos los registros de tallas y colores asociados a un mismo almacén y
producto.

MinStock [Obligatorio]
Stock mínimo del producto en unidades de venta.

MaxStock [Obligatorio]
Stock máximo del producto en unidades de venta.

Order
Posición del producto dentro de su familia en el punto de venta. A la hora de mostrar
los productos de una determinada familia, se ordenarán por el valor introducido en
este campo. Los productos para los que no se haya indicado el orden, aparecerán al
final de la lista de los productos.

UseAsDirectSale
Indica si el producto debe tratarse como un producto de venta directa (true) o no
(false). Si es así, el producto se mostrará junto a los grupos de productos en la
pantalla de venta, y la posición indicada en el atributo Order será relativa a la posición
de las familias y otros productos de venta directa, no a la posición de los productos de
esta familia.

MinAddins [Obsoleto: Usar AddinRoles]

Número mínimo de añadidos que se deberán seleccionar al vender el producto.

MaxAddins [Obsoleto: Usar AddinRoles]

Número máximo de añadidos que se podrán seleccionar al vender el producto.

SaleableAsMain
Indica si el producto puede venderse como producto principal (true) o no (false).

Guía del Integrador 45 Versión 5.1.0

SaleableAsAddin
Indica si el producto puede venderse como producto añadido (true) o no (false).

AskForAddins
Indica si al vender el producto deben solicitarse automáticamente añadidos (true) o
no (false).

AskForPreparationNotes
Indica si al vender el producto deben solicitarse automáticamente notas de preparación
(true) o no (false).

PrintWhenPriceIsZero
Indica si al imprimir un ticket en el cual este producto tiene precio cero, debe
mostrarse el producto (true) o no (false).

PreparationTypeId
Id del tipo de preparación asociado al producto. Si el producto no tiene tipo de
preparación, deberá incluirse el atributo vacío. Si un producto tiene tipo de
preparación, deberá establecer también su orden de preparación.

PreparationOrderId
Id del order de preparación asociado al producto. Si el producto no tiene order de
preparación, deberá incluirse el atributo vacío. Si un producto tiene orden de
preparación, deberá establecer también su tipo de preparación.

IsSoldByWeight
Indica si el producto es vendible al peso (true) o no (false).

Prices
Precios del producto en cada centro de venta y tarifa especial. Cada precio debe
indicarse en un elemento Price con los siguientes atributos:

PriceListId [Obligatorio]
Id de la tarifa cuyos precios se quieren establecer.

MainPrice [Obligatorio]
Precio de venta como producto principal. El precio será con impuestos
incluidos o no dependiendo de la configuración de la tarifa. Si deja el atributo
vacío, Ágora solicitará el precio en el momento de la venta.

AddinPrice [Obligatorio]
Precio de venta como añadido de otro producto. El precio será con impuestos
incluidos o no dependiendo de la configuración de la tarifa. Si deja el atributo
vacío, Ágora solicitará el precio en el momento de la venta.

MenuItemPrice [Obligatorio]
Suplemento al incluir el producto en un menú. El precio será con impuestos
incluidos o no dependiendo de la configuración de la tarifa. Si deja el atributo
vacío, Ágora solicitará el precio en el momento de la venta.

Addins [Obsoleto: Usar AddinRoles]

Añadidos disponibles para el producto. Cada añadido debe indicarse en un elemento
Addin con los siguientes atributos:

Guía del Integrador 46 Versión 5.1.0

SaleFormatId [Obligatorio]
Id del formato de venta que se usará como añadido. Por razones de
compatibilidad, este atributo se puede sustituir por ProductId.

AddinRoles
Grupos de añadidos disponibles para el producto. Prevalece sobre el node Addins. Cada
grupo debe indicarse en un elemento AddinRole con los siguientes atributos:

Name [Obligatorio]
Nombre del grupo de añadidos.

ButtonText
Texto del botón del grupo de añadidos.

Color
Color del botón del grupo de añadidos.

MinAddins
Número mínimo de añadidos que se deberán seleccionar al vender el producto
con un añadido de este grupo.

MaxAddins
Número máximo de añadidos que se podrán seleccionar al vender el producto
con un añadido de este grupo.

UsePreparationType
Tipo de preparación para los añadidos del grupo. Puede tener dos valores
"FromMain" para usar el tipo de preparción del producto del que es añadido o
"FromAddin" para usar el del añadido.

AdditionalSaleFormats
Formatos de venta adicionales del producto. Los formatos que aparezca en este
elemento serán creados o actualizado en la base de datos conforme sea necesario.
Para eliminar un formato, será necesario indicarlo en este nodo con su DeletionDate
correspondiente. Cada formato de venta debe indicarse en un elemento SaleFormat
con los siguientes atributos:

Id [Obligatorio]
Identificador único del formato de venta. Este identificador debe ser único en
todos los formatos de venta de Ágora, no sólo los de este producto,
incluyendo los Ids de los formatos base de los productos indicados en el
atributo BaseSaleFormatId de los elementos Product.

Name [Obligatorio]
Nombre del formato de venta.

Ratio [Obligatorio]
Relación de la cantidad consumida por este formato con respecto al formato
base.

ButtonText
Texto mostrado en el botón asociado al formato de venta en el punto de
venta.

Guía del Integrador 47 Versión 5.1.0

Color
Color del botón asociado al formato de venta el punto de venta. El formato es
#RRGGBB, como los ejemplos mostrados en el anexo I.

SaleableAsMain
Indica si el formato puede venderse como formato principal (true) o no
(false).

SaleableAsAddin
Indica si el formato puede venderse como formato añadido (true) o no
(false).

AskForAddins
Indica si al vender el formato deben solicitarse automáticamente añadidos
(true) o no (false).

MinAddins [Obsoleto: Usar AddinRoles]

Número mínimo de añadidos que se deberán seleccionar al vender el formato.

MaxAddins [Obsoleto: Usar AddinRoles]

Número máximo de añadidos que se podrán seleccionar al vender el formato.

DeletionDate
Fecha de borrado del registro. Sólo se debe incluir este atributo en caso de
querer eliminar el registro. Si se incluye este atributo con un valor de fecha y
hora válido, se considerará que el registro ha sido dado de baja. El formato de
fechas soportado es aaaa-mm-ddThh:mm:ss, por ejemplo
2012-01-31T10:59:20.

Prices
Precios del formato en cada centro de venta y tarifa especial. Cada precio
debe indicarse en un elemento Price con los siguientes atributos:

PriceListId [Obligatorio]
Id de la tarifa cuyos precios se quieren establecer.

MainPrice [Obligatorio]
Precio de venta como formato principal. El precio será con impuestos
incluidos o no dependiendo de la configuración de la tarifa. Si deja el
atributo vacío, Ágora solicitará el precio en el momento de la venta.

AddinPrice [Obligatorio]
Precio de venta como añadido de otro producto o formato. El precio
será con impuestos incluidos o no dependiendo de la configuración
de la tarifa. Si deja el atributo vacío, Ágora solicitará el precio en el
momento de la venta.

MenuItemPrice [Obligatorio]
Suplemento al incluir el formato en un menú. El precio será con
impuestos incluidos o no dependiendo de la configuración de la
tarifa. Si deja el atributo vacío, Ágora solicitará el precio en el
momento de la venta.

Guía del Integrador 48 Versión 5.1.0

Addins [Obsoleto: Usar AddinRoles]
Añadidos disponibles para el formato. Cada añadido debe indicarse en un
elemento Addin con los siguientes atributos:

SaleFormatId [Obligatorio]
Id del formato de venta que se usará como añadido. Por razones
de compatibilidad, este atributo se puede sustituir por
ProductId.

AddinRoles
Grupos de añadidos disponibles para el formato. Prevalece sobre el node
Addins. Cada grupo debe indicarse en un elemento AddinRole con los
siguientes atributos:

Name [Obligatorio]
Nombre del grupo de añadidos.

ButtonText
Texto del botón del grupo de añadidos.

Color
Color del botón del grupo de añadidos.

MinAddins
Número mínimo de añadidos que se deberán seleccionar al vender el
producto con un añadido de este grupo.

MaxAddins
Número máximo de añadidos que se podrán seleccionar al vender el
producto con un añadido de este grupo.

UsePreparationType
Tipo de preparación para los añadidos del grupo. Puede tener dos
valores "FromMain" para usar el tipo de preparción del producto del
que es añadido o "FromAddin" para usar el del añadido.

CostPrice
Precio de coste del producto.

DeletionDate
Fecha de borrado del registro. Sólo se debe incluir este atributo en caso de querer
eliminar el registro. Si se incluye este atributo con un valor de fecha y hora válido, se
considerará que el registro ha sido dado de baja. Si se indica este atributo, todos los
formatos relacionados con el producto también serán eliminados. El formato de fechas
soportado es aaaa-mm-ddThh:mm:ss, por ejemplo 2012-01-31T10:59:20.

Internamente Ágora creará el formato de venta base del producto usando el mismo Id que el
producto si no se especifica el atributo BaseSaleFormatId. Si ya existiese un formato de venta
con ese Id en la base de datos asociado a otro producto, por ejemplo porque ha sido creado
manualmente desde la administración de Ágora, se generará un error.

Guía del Integrador 49 Versión 5.1.0

Menús
Los menús se indican dentro del elemento <Menus> en sucesivos elementos <Menu>:

XML:

JSON:

Guía del Integrador 50 Versión 5.1.0

{
"Menus": [
{
"Barcodes": [
{
"BarcodeValue": "15998763"
}
],
"Prices": [
{
"SaleCenterId": 10,
"MainPrice": 9.00
},
{
"SaleCenterId": 11,
"MainPrice": 10.00
}
],
"MenuGroups": [
{
"Products": [
{
"Id": 100
},
{
"Id": 101
}
],
"Name": "Bebida",
"MaxItems": 1,
"PreparationOrderId": 1
},
{
"Products": [
{
"Id": 301
},
{
"Id": 302
}
],
"Name": "Bocadillo",
"MaxItems": 1,
"PreparationOrderId": 2
}
],
"Id": 401,
"Name": "Menú Merienda",
"VatId": 3,
"FamilyId": 104,
"ButtonText": "M.Merienda",

Guía del Integrador 51 Versión 5.1.0

"Color": "#341122",
"Order": 1,
"UseAsDirectSale": true,
"Tag": "MM",
"PLU": "0001"
}
]
}

Para cada menú podrá indicar información similar a la del producto, pero además deberá indicar
los grupos que forman parte del menú:

Id [Obligatorio]
Identificador numérico único del menú. Este Id se utilizará también para crear el
formato base del menú. Deberá asegurarse además de que este Id no coincide con
ningún Id de producto.

Name [Obligatorio]
Nombre del menú.

VatId [Obligatorio]
Id del impuesto de venta asociado al menú.

FamilyId
Id de la familia a la que pertenece el menú. Si el menú no pertenece a ninguna familia,
deberá incluirse este atributo vacío.

ButtonText
Texto mostrado en el botón asociado al menú en el punto de venta.

Color
Color del botón asociado al menú el punto de venta. El formato es #RRGGBB, como los
ejemplos mostrados en el anexo I.

Barcodes
Lista de códigos de barras del menú. Cada uno de ellos debe indicarse en un elemento
Barcode con un único atributo Value que contenga el código de barras.

Order
Posición del menú dentro de su familia en el punto de venta. A la hora de mostrar los
productos y menús de una determinada familia, se ordenarán por el valor introducido
en este campo. Los productos y menús para los que no se haya indicado el orden,
aparecerán al final de la lista de los productos.

UseAsDirectSale
Indica si el menú debe tratarse como un producto de venta directa (true) o no
(false). Si es así, el menú se mostrará junto a los grupos de productos en la pantalla
de venta, y la posición indicada en el atributo Order será relativa a la posición de las
familias y otros productos de venta directa, no a la posición de los productos de esta
familia.

Guía del Integrador 52 Versión 5.1.0

SaleableAsMain
Indica si el menú puede venderse (true) o no (false).

Tag [Obligatorio]
Texto usado en la comanda impresa y en los monitores de cocina para distinguir los
platos de este menú. Si no se desea utilizar ningún indicador, este campo debe dejarse
vacio.

PLU
Código PLU del menú. Debe ser una cadena numérica. Ejemplos: 0001, 33232, etc.

Prices
Precios del menú en cada centro de venta y tarifa especial. Cada precio debe indicarse
en un elemento Price con los siguientes atributos:

SaleCenterId o SpecialPriceListId
Id del centro de venta o tarifa especial cuyos precios se quieren establecer.

MainPrice
Precio de venta del menú. El precio será con impuestos incluidos o no
dependiendo de la configuración del centro de venta o tarifa. Si deja el
atributo vacío, Ágora solicitará el precio en el momento de la venta.

MenuGroups [Obligatorio]
Grupos de platos que forman el menú. Deberá indicar al menos un grupo de platos.
Cada uno de ellos deberá especificarse en un element MenuGroup con los siguientes
atributos:

Name [Obligatorio]
Nombre del grupo de platos.

MaxItems [Obligatorio]
Número máximo de platos de este grupo que puede pedirse.

PreparationOrderId [Obligatorio]
Id del orden de preparación que se usará al pedir los platos de este grupo.

Products
Lista de productos que se pueden elegir para este grupo de platos. Cada uno
de ellos debe indicarse en un elemento Product con un único atributo Id que
contenga el Id del producto.

Internamente Ágora creará el formato de venta base del menú usando el mismo Id que el
menú. Si ya existiese un formato de venta con ese Id en la base de datos asociado a otro menú,
por ejemplo porque ha sido creado manualmente desde la administración de Ágora, se generará
un error. Además, deberá asegurarse de que no existe ningún producto o menú en la base de
datos con el Id asignado.

Guía del Integrador 53 Versión 5.1.0

Para cada grupo de platos de los menús, Ágora creará automáticamente una categoría llamada
"Grupo de Menú", por ejemplo, "Bebidas de Menú del Día". La gestión de estas categorías es
realizada automáticamente por Ágora y no deberán ser modificadas desde la administración de
Ágora.

Promociones
Las promociones se indican dentro del elemento <Offers> en sucesivos elementos <Offer>:

XML:

<!-- Contiene sólo uno de los siguientes tres elementos dependiendo

del tipo de promoción -->

</Offer>
</Offers>

JSON:

Guía del Integrador 54 Versión 5.1.0

{
"Offers": [
{
"Discount": {},
"Custom": {},
"FixedPrice": {},
"Id": 2,
"Name": "50%",
"Code": "50%",
"ApplicationMode": "AllTickets",
"FromDate": "2016-02-17",
"ToDate": "2016-03-17",
"StartTime": "00:00",
"EndTime": "23:59",
"ApplyOnMonday": true,
"ApplyOnTuesday": true,
"ApplyOnWednesday": true,
"ApplyOnThursday": true,
"ApplyOnFriday": true,
"ApplyOnSaturday": true,
"ApplyOnSunday": true
}
]
}

Para cada promoción podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único de la promoción.

Name [Obligatorio]
El nombre de la promoción. Este campo no puede ser vacío

Code [Obligatorio]
Código de la promoción. Este campo no puede ser vacío

ApplicationMode [Obligatorio]
Si el valor es "AllTickets" indica que la promoción se aplica automáticamente a todos
los tickets o por el contrario es una promoción que puede asociarse a clientes o tickets
manualmente cuando el valor es "SelectedCustomerOrTickets".

FromDate [Obligatorio]
Fecha de inicio de la promoción. El fomato soportado es de la forma aaaa-mm-dd

ToDate [Obligatorio]
Fecha de fin de la promoción. El fomato soportado es de la forma aaaa-mm-dd

Guía del Integrador 55 Versión 5.1.0

StartTime [Obligatorio]
Hora de inicio de la promoción. El formato soportado es de la forma HH:mm. Para
indicar que la promoción está activa durante todo el día, deberá marcar como
StartTime las 00:00 y como EndTime las 23:59.

EndTime [Obligatorio]
Hora de fin de la promoción. El formato soportado es de la forma HH:mm

ApplyOnMonday [Obligatorio]
Indica si la promoción está vigente los lunes.

ApplyOnTuesday [Obligatorio]
Indica si la promoción está vigente los martes.

ApplyOnWednesday [Obligatorio]
Indica si la promoción está vigente los miércoles.

ApplyOnThursday [Obligatorio]
Indica si la promoción está vigente los jueves.

ApplyOnFriday [Obligatorio]
Indica si la promoción está vigente los viernes.

ApplyOnSaturday [Obligatorio]
Indica si la promoción está vigente los sábados.

ApplyOnSunday [Obligatorio]
Indica si la promoción está vigente los domingos.

Cada promoción además de la configuración básica llevará la configuración de los descuentos y

productos a los que se aplica dependiendo del tipo de promoción.

▪ Descuento Directo: su configuración se indica dentro del elemento <Discount>.

▪ Pack de Productos a Precio Fijo: su configuración se indica dentro del elemento

<FixedPrice>.

▪ Personalizada: su configuración se indica dentro del elemento <Custom>.

Descuento Directo
Se corresponde con la promoción de "Descuento Directo" que aparece en el manual de Ágora.

Esta promoción se encuentra dentro del elemento <Discount> que contiene el elemento
<Products> con los productos a los que se aplica la promoción:

Guía del Integrador 56 Versión 5.1.0

XML:

<Discount DiscountRate="0.5000" RequiredQuantity="1.000" ApplyBy="Groups">

JSON:

{
"Discount": {
"Products": [
{
"Id": 12
},
{
"Id": 13
},
{
"Id": 14
},
{
"Id": 91
},
{
"Id": 92
},
{
"Id": 93
}
],
"DiscountRate": 0.5000,
"RequiredQuantity": 1.000,
"ApplyBy": "Groups"
}
}

Los atributos disponibles son los siguientes:

DiscountRate [Obligatorio si no asignamos CashDiscount]

Tanto por uno de descuento que aplica la promoción.

CashDiscount [Obligatorio si no asignamos DiscountRate]

Descuento en moneda que se aplica la promoción.

Guía del Integrador 57 Versión 5.1.0

RequiredQuantity [Obligatorio]
Cantidad necesaria que se debe comprar de los productos indicados para aplicar la
promoción.

ApplyBy
Modo de aplicación de la promoción. Los posibles valores para este atributo son
"Groups" y "Units". Este atributo, si está presente, modifica el comportamiento de
Ágora a la hora de aplicar la promoción. Con el valor "Units", una vez que se alcancen
la cantidad requerida de unidades, se aplicará la promoción a todas ellas. Con el valor
"Groups" la promoción se aplicará a cada tantas unidades como se hayan establecido.

Nota: Sólo es necesario asignar CashDiscount o DiscountRate, no ambos.

Para producto, debería indicarse:

Id [Obligatorio]
Identificador del producto.

Pack de Productos a Precio Fijo

Se corresponde con la promoción "Pack de Productos a Precio Fijo" que aparece en el manual de
Ágora.

Esta promoción se encuentra dentro del elemento <FixedPrice> que contiene el elemento
<Products> con los productos a los que se aplica la promoción y por otro lado el elemento
<Prices> con los precios por tarifa o centro de venta del pack de productos:

XML:

JSON:

Guía del Integrador 58 Versión 5.1.0

{
"FixedPrice": {
"Products": [
{
"Id": 1
},
{
"Id": 2
},
{
"Id": 3
},
{
"Id": 4
}
],
"Prices": [
{
"PriceListId": 11,
"Value": 1.6
},
{
"PriceListId": 12,
"Value": 1.6
}
],
"RequiredQuantity": 2
}
}

Los atributos disponibles en el elemento <FixedPrice> son los siguientes:

RequiredQuantity [Obligatorio]
Cantidad necesaria que se debe comprar de los productos para aplicar la promoción.

Para cada producto será necesario indicar:

Id [Obligatorio]
Identificador del producto.

Cada precio se indicará de la siguiente manera:

PriceListId [Obligatorio]
Id de la tarifa cuyos precios se quieren establecer.

Value [Obligatorio]
Precio de venta del pack de productos. El precio será con impuestos incluidos o no
dependiendo de la configuración del centro de venta o tarifa.

Guía del Integrador 59 Versión 5.1.0

Personalizada
Se corresponde con la promoción "Personalizada" y permite relizar el resto de promociones
disponibles en Ágora así como promociones más complejas.

Esta promoción se encuentra dentro del elemento <Custom> que contiene el elemento
<SourceProducts> con los productos que es necesario comprar para que se aplique la
promoción y el elemento <TargetProducts> con los productos sobre los que se aplica el
descuento de la promoción:

XML:

JSON:

Guía del Integrador 60 Versión 5.1.0

{
"Custom": {
"SourceProducts": [
{
"ProductId": 19
},
{
"ProductId": 20
},
{
"ProductId": 21
},
{
"ProductId": 22
},
{
"ProductId": 23
}
],
"TargetProducts": [
{
"ProductId": 19
},
{
"ProductId": 20
},
{
"ProductId": 21
},
{
"ProductId": 22
},
{
"ProductId": 23
}
],
"RequiredSourceQuantity": 1.000,
"MaxTargetQuantity": 1.000,
"DiscountRate": "1.0000"
}
}

Los atributos disponibles son los siguientes:

RequiredSourceQuantity [Obligatorio]
Cantidad necesaria que se debe comprar de los productos indicados para aplicar la
promoción.

Guía del Integrador 61 Versión 5.1.0

MaxTargetQuantity [Obligatorio]
Cantidad de productos sobre los que se aplicará el descuento de la promoción.

DiscountRate [Obligatorio si no asignamos CashDiscount]

Tanto por uno de descuento que aplica sobre los productos a los que se aplica la
promoción.

CashDiscount [Obligatorio si no asignamos DiscountRate]

Descuento en moneda que aplica sobre los productos a los que se aplica la promoción.

Nota: Sólo es necesario asignar CashDiscount o DiscountRate, no ambos.

Los productos que se deben comprar para promoción se establecen en el elemento

SourceProducts indicando para cada uno:

Id [Obligatorio]
Identificador del producto.

Los productos que a los que se aplicará el descuento se establecen en el elemento

SourceProducts indicando para cada uno:

Id [Obligatorio]
Identificador del producto.

Notas Predefinidas
Las notas predefinidas se indican dentro del elemento <PredefinedNotes> en sucesivos
elementos <PredefinedNote>:

XML:

Guía del Integrador 62 Versión 5.1.0

JSON:

Guía del Integrador 63 Versión 5.1.0

{
"PredefinedNotes": [
{
"ValidGroups": [],
"Id": 100,
"Text": "Sin Sal",
"ValidForAllGroups": true,
"Priority": 5
},
{
"ValidGroups": [
{
"FamilyId": 3
},
{
"FamilyId": 24
}
],
"Id": 101,
"Text": "Muy Hecho",
"ValidForAllGroups": false,
"Priority": 5
},
{
"ValidGroups": [],
"Id": 102,
"Text": "Muy Hecho",
"DeletionDate": "2012-01-31T10:00:00"
}
]
}

Para cada nota predefinida podrá indicar los siguientes atributos:

Id [Obligatorio]
Identificador numérico único de la nota predefinida.

Text [Obligatorio]
Texto de la nota predefinida.

Priority [Obligatorio]
Prioridad usada para ordenar las notas predefinidas a la hora de mostrarlas en la
pantalla de selección de notas. Las notas con un valor de Priority más bajo serán
mostradas antes.

ValidForAllGroups [Obligatorio]
Indica si la nota predefinida se puede aplicar a todas las familias y categorías de
productos (true) o sólo a algunas familias (false).

Guía del Integrador 64 Versión 5.1.0

ValidGroups [Obligatorio]
Lista de familias a las que se puede aplicar la nota predefinida. Cada familia debe
indicarse en un elemento Family con un único atributo Id que contenga el identificador
único de la familia. Si la nota predefinida está marcada como
ValidForAllGroups='false', sólo se podrá aplicar a las familias incluidas en este
elemento. Tenga en cuenta que las familias deben existir en las base de datos o estar
definidas en el fichero xml antes de las notas predefinidas para poder importarlas
correctamente.

ButtonText
Texto mostrado en el botón asociado a la nota predefinida en el punto de venta.

Color
Color del botón asociado a la nota en el punto de venta. El formato es #RRGGBB,
como los ejemplos mostrados en el anexo I.

Pedidos
El formato de importación de los pedidos es igual que el formato usado para la exportación,
con la salvedad de que no es obligatorio añadir el elemento <Totals> porque será recalculado
en base a los descuentos y líneas introducidas.

En caso de que el albarán no incluya una dirección de entrega se le pondrá la dirección de

entrega por defecto del cliente asociado.

Importante: antes de importar cualquier pedido en Ágora debe de darse de alta

la serie con la que se va a importar. No se dejará importar un pedido con la serie
que esté activada en Ágora en ese momento.

A la hora de importar un pedido en Ágora se tratará de distinta manera según su estado.

Cuando el pedido a importar tiene un estado "Pendiente" (Pending) o "Facturado" (Invoiced) se
tratará de la siguiente manera:

▪ Si el pedido no existía en Ágora, se guardará un pedido que puede ser editado desde
Ágora, independientemente de que su estado en el documento XML sea "Pendiente" o
"Facturado". Para que un pedido quede como facturado, será necesario importar la
factura correspondiente, y será en ese momento cuando el pedido dejará de ser
editable.

▪ Si existía en Ágora y no había sido facturado o cancelado previamente, se sobreescribirá

el pedido anterior con los nuevos datos importados. De esta manerá el pedido quedará
actualizado con las últimas modificaciones.

Guía del Integrador 65 Versión 5.1.0

▪ Si existía en Ágora y ya había sido facturado o cancelado, se ignorará el documento
importado y se respetará la información existente en Ágora.

En cambio, si el pedido que se está importando tiene un estado "Cancelado" (Cancelled):

▪ Si el pedido no existía en Ágora, se guardará el pedido y se emitirá y guardará su

cancelación, por lo que el pedido pasará a estar en estado "Cancelado" y no podrá ser
editado.

▪ Si ya existía en Ágora y no aun no estaba cancelado o facturado, se sobreescribirá el

pedido anterior y se guardará y emitirá su cancelación.

▪ Si ya existía en Ágora y ya se encontraba facturado o cancelado, se ignorará el pedido

importado y se respetará el estado existente en Ágora.

Importante: siempre que se importa un pedido con estado "Cancelado" en una

central de Ágora, el pedido de origen que se encuentre en el local quedará
invalidado y no podrá modificarse.

Albaranes
El formato de importación de los albaranes es igual que el formato usado para la exportación.
Con la salvedad de que no es obligatorio añadir el elemento <Totals> porque será recalculado
en base a los descuentos y líneas introducidas.

En caso de que el albarán no incluya una dirección de entrega se le pondrá la dirección de

entrega por defecto del cliente asociado.

Importante: antes de importar cualquier albarán en Ágora debe de darse de alta

la serie con la que se va a importar. No se permitirá importar un albarán con la
serie que esté usando Ágora, a menos que sea para realizar su cancelación.

A la hora de importar un albarán en Ágora se tratará de distinta manera según su estado.

Cuando el albarán importado tiene un estado "Pendiente" (Pending) o "Facturado" (Invoiced) se
tratará de la siguiente manera:

▪ Si el albarán existía en Ágora pero todavía no había sido facturado o cancelado, se

sobrescribirá el albarán anterior con los datos importados. De esta manerá el albarán
quedará actualizado con las últimas modificaciones.

▪ Si el albarán existía en Ágora y ya estaba facturado o cancelado, se ignorará el albarán

importado y se respetará la información existente en Ágora.

Guía del Integrador 66 Versión 5.1.0

En cambio, si el albarán que se está importando tiene un estado "Cancelado" (Cancelled):

▪ Si el albarán no existía en Ágora, se guardará un albarán que no puede ser editado

desde Ágora (por ejemplo, no puede reabrirse ni facturarse).

▪ Si el albarán ya existía en Ágora pero todavía no estaba cancelado o facturado, se

sobreescribirá el albarán anterior y se marcará como que no puede ser editado. De esta
forma, quedará registrado un albarán con las últimas modificaciones, pero no se
permitirá su edición.

▪ Si el albarán ya existía en Ágora y ya estaba facturado o cancelado, se ignorará el

albarán importado y se respetará el estado existente en Ágora.

Importante: siempre que se importa un albarán, se generan los movimientos de

stock correspondientes. Si se importa un albarán ya existente en Ágora, al
sobreescribirlo se actualizarán también sus movimientos de stock. En el caso de
albaranes cancelados, los movimientos de stock se mantienen. Un albarán
cancelado sólo implica que ya no puede ser modificado desde el TPV (reabierto,
facturado, etc.), pero sus movimientos de stock siguen siendo válidos. En el caso
de querer hacer una devolución de un albarán, será necesario enviar la
cancelación del albarán original, y enviar un nuevo albarán en negativo para
recuperar el stock; este albarán en negativo deberá tener estado cancelado para
evitar que sea facturado.

Importante: siempre que se importa un albarán con estado "Cancelado" en una

central de Ágora, el albarán de origen que se encuentre en el local quedará
invalidado y no podrá modificarse.

Facturas
El formato de importación de las facturas es igual que el formato usado para la exportación.
Con la salvedad de que no es obligatorio añadir cualquier elemento <Totals> porque será
recalculado en base a los descuentos y líneas introducidas.

Importante: antes de importar cualquier factura en Ágora debe de darse de alta

la serie con la que se va a importar. No se dejará importar una factura con la
serie que esté activada en Ágora.

Si se importa una factura que ya existe en Ágora, sea cual sea su contenido se ignorará porque
ninguna factura puede ser modificada y por tanto es seguro descartar la nueva factura.
Asimismo, si se importa una factura que referencia a otra, la factura referenciada deberá existir
previamente en Ágora.

Guía del Integrador 67 Versión 5.1.0

A la hora de importar una factura que no esté dada de alta se tratará de distinta manera según
su contenido:

▪ Si el contenido de la factura son albaranes, se crearán los albaranes correspondientes y

se emitirá la factura. Si los albaranes ya existían en la base de datos, su contenido será
sobreescrito con la información procedente del documento XML, siguiendo las reglas
descritas en la importación de albaranes.

▪ Si el contenido es un ticket que referencia a un pedido, se creará el pedido

correspondiente y se realizará la facturación de dicho pedido. Si el pedido ya existía en
la base de datos, su contenido será sobreescrito con la información procedente del
documento XML, siguiendo las reglas descritas en la importación de pedidos.

▪ Si el contenido es simplemente un ticket, se creará la factura.

Notas especiales sobre redondeo de facturas

En ocasiones pueden existir desajustes entre los totales de la factura calculados por Ágora y por
el sistema que la generó, generalmente basados por diferencias de redondeo. Para permitir que
el importe total de la factura coincida en ambos sistemas, es posible forzar a que Ágora haga
coincidir el total de la factura con los pagos realizados. Para ello, Ágora añadirá una línea con un
artículo para compensar las diferencias de redondeo al cuerpo de la factura y, si fuera
necesario, ajustará los descuentos a pie de ticket. Este comportamiento sólo está disponible
para facturas generadas a partir de un único ticket (no funcionará con las facturas de varios
albaranes). Para habilitarlo, es necesario indicar en el nodo Invoice el valor
FixTotalToPayments a true:

XML:

<Invoice Serie="F" Number="1" BusinessDay="2014-09-29"

...
FixTotalToPayments="true"
...>

JSON:

{
"Serie": "F",
"Number": 1,
"BusinessDay": "2014-09-29",
...
"FixTotalToPayments": true
...
}

Pedidos a Proveedor
El formato de importación de los pedidos a proveedor es igual que el formato usado para la
exportación, con la salvedad de que no es obligatorio añadir el elemento <Totals> y

Guía del Integrador 68 Versión 5.1.0

<TotalAmount> para cada línea del pedido porque los totales serán recalculados en base a los
descuentos y líneas introducidas.

Importante: Al contrario que en los Pedidos de venta, no es necesario crear una

serie específica para importar Pedidos a Proveedor, aunque la serie indicada debe
existir en Ágora. Sin embargo es importante resaltar que, si se importa un Pedido
a Proveedor con un número de serie inferior al último número de dicha serie, se
actualizará el documento que tuviera asociado dicho número, y la serie
mantendrá su contador inalterado. Si se importa un Pedido con un número de
serie superior al último de dicha serie, el contador de la misma actualizará su
contador para que su último número coincida con el número de serie del Pedido
que se importa.

A la hora de importar un pedido a proveedor en Ágora se tratará de distinta manera según su

estado y si se encontraba registrado previamente en Ágora:

▪ Si el pedido no existía en Ágora, se guardará un pedido que puede ser editado desde
Ágora ignorando la cantidad servida si se ha indicado. Cuando el pedido a importar
tiene un estado "Borrador" (Draft) se mantendrá como tal. Si por el contrario tiene un
estado distinto como "Confirmado" (Confirmed), "Servido Parcialmente"
(PartialDelivery) o "Servido" (Delivered), el pedido se importará como "Confirmado"
(Confirmed).

▪ Si el pedido existía en Ágora y no está servido (estado "Borrador" o "Confirmado"), se

sobreescribirá el pedido anterior con los nuevos datos importados. De esta manerá el
pedido quedará actualizado con las últimas modificaciones.

▪ Si el pedido existía en Ágora y está servido, total o parcialmente, se ignorará el

documento importado y se respetará la información existente en Ágora.

Albaranes de Proveedor
El formato de importación de los albaranes es igual que el formato usado para la exportación.
Con la salvedad de que no es obligatorio añadir el elemento <Totals> y <TotalAmount> de las
líneas del albarán porque serán recalculados en base a los descuentos y líneas introducidas.

Importante: Al contrario que en los Albaranes, no es necesario crear una serie

específica para importar Albaranes de Proveedor, aunque la serie indicada debe
existir en Ágora. Sin embargo es importante resaltar que, si se importa un
Albarán de Proveedor con un número de serie inferior al último número de dicha
serie, se actualizará el documento que tuviera asociado dicho número, y la serie
mantendrá su contador inalterado. Si se importa un Albarán con un número de
serie superior al último de dicha serie, el contador de la misma actualizará su
contador para que su último número coincida con el número de serie del Albarán
que se importa.

Guía del Integrador 69 Versión 5.1.0

A la hora de importar un albarán de proveedor en Ágora se tratará de distinta manera según su
estado y si existía o no en Ágora:

▪ Si el albarán no existía en Ágora, se guardará un albarán que puede ser editado desde
Ágora independientemente de que su estado en el documento XML sea "Pendiente" o
"Facturado". Para que un albarán quede como facturado, será necesario importar la
factura de proveedor correspondiente, y será en ese momento cuando el albarán dejará
de ser editable. Si el albarán está sirviendo líneas de pedidos que no existen en Ágora
se producirá un error de importación. Los pedidos que se estén sirviendo en el albarán
quedarán marcados como "Servidos" o "Servidos Parcialmente".

▪ Si el albarán existía en Ágora pero todavía no había sido facturado o cancelado, se

sobrescribirá el albarán anterior con los datos importados. De esta manerá el albarán
quedará actualizado con las últimas modificaciones y los pedidos servidos quedarán
marcados como "Servidos" o "Servidos Parcialmente".

▪ Si el albarán existía en Ágora y ya estaba facturado, se ignorará el albarán importado y

se respetará la información existente en Ágora.

Importante: siempre que se importa un albarán de proveedor, se generan los

movimientos de stock correspondientes. Si se importa un albarán ya existente en
Ágora, al sobreescribirlo se actualizarán también sus movimientos de stock.

Facturas a Proveedor
El formato de importación de las facturas es igual que el formato usado para la exportación.
Con la salvedad de que no es obligatorio añadir cualquier elemento <Totals> porque será
recalculado en base a los descuentos y líneas introducidas.

Importante: Al contrario que en las Facturas, no es necesario crear una serie

específica para importar Facturas de Proveedor, aunque la serie indicada debe
existir en Ágora. Sin embargo es importante resaltar que, si se importa una
Factura de Proveedor con un número de serie inferior al último número de dicha
serie, se actualizará el documento que tuviera asociado dicho número, y la serie
mantendrá su contador inalterado. Si se importa una Factura con un número de
serie superior al último de dicha serie, el contador de la misma se actualizará
para que su último número coincida con el número de serie de la Factura que se
importa.

A la hora de importar una factura de proveedor en Ágora se tratará de distinta manera según su
estado y si existía o no en Ágora:

▪ Si la factura no existía en Ágora, esta se importará con el estado indicado, y

reimportará los albaranes que se estén importando en la factura. Esto marcará dichos
albaranes como "Facturados".

▪ Si la factura existía en Ágora, será reimportada marcando como facturados todos los
albaranes que se incluyan con la factura. Si la factura incluye pagos que la pagan

Guía del Integrador 70 Versión 5.1.0

completamente, la factura se importará con el estado "Pagada", si no, será importada
con el estado "Pendiente de Pago".

Importante: Para marcar una factura como "Contabilizada" ha de importarse con

la propiedad Accounted con el valor true. Además, para que esta importación sea
válida la factura ha de estar pagada completamente y, por tanto, estar en estado
"Pagado".

Formato de fichero de exportación de datos de ventas y

compras
El fichero de exportación de datos de Ágora permite obtener la información generada en el
punto de venta, incluyendo Facturas, Cargos a Cuenta, Movimientos de Caja, Cierres de Caja y
Cierres de Sistema. Así mismo también permite obtener los documentos de compra realizados
incluyendo Pedidos a Proveedor, Albaranes de Entrada y Facturas de Proveedor.

Se trata de un fichero xml con las siguientes secciones:

Guía del Integrador 71 Versión 5.1.0

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Export>
<CashTransactions>

</CashTransactions>
<SalesOrders>

</SalesOrders>
<DeliveryNotes>

</DeliveryNotes>
<Invoices>

</Invoices>
<PosCloseOuts>

</PosCloseOuts>
<SystemCloseOuts>

</SystemCloseOuts>
<PurchaseOrders>

</PurchaseOrders>
<IncomingDeliveryNotes>

</IncomingDeliveryNotes>
<PurchaseInvoices>

</PurchaseInvoices>
</Export>

También puede tratarse de un fichero JSON con las siguientes secciones:

Guía del Integrador 72 Versión 5.1.0

{
"CashTransactions": [
/* Movimientos de Caja */
],
"SalesOrders": [
/* Pedidos */
],
"DeliveryNotes": [
/* Albaranes */
],
"Invoices": [
/* Facturas */
],
"PosCloseOuts": [
/* Cierres de Caja */
],
"SystemCloseOuts": [
/* Cierres de Caja */
],
"PurchaseOrders": [
/* Pedidos a Proveedor */
],
"IncomingDeliveryNotes": [
/* Albaranes de Entrada */
],
"PurchaseInvoices": [
/* Facturas de Proveedor */
]
}

Los ejemplos que se incluyen en este documento son orientativos y puede que
no cubran todos los casos existentes. Le recomendamos encarecidamente que,
además de seguir los textos incluidos en este documento, utilice la versión de
demostración de Ágora para verificar el formato de ficheros.

La información del fichero se generará para la fecha de negocio indicada como parámetro al
ejecutar la aplicación ais.exe. Si no se indica una fecha de negocio, se usará el día actual como
fecha de negocio.

Sólo se incluirán en el documento aquellas secciones que tengan datos. Por ejemplo, si no se ha
generado ninguna factura o no hay ningún cierre de caja, estas secciones no aparecerán en el
documento.

Los campos numéricos utilizan como separador de decimales el punto '.' y NO

utilizan separador de millares.

Guía del Integrador 73 Versión 5.1.0

Los campos de tipo fecha utilizando como formato aaaa-mm-dd. Si además
incluye la hora, el formato es aaaa-mm-ddThh:mm:ss, por ejemplo
2012-01-29T21:00:54.

Movimientos de Caja
Los movimientos de caja se indican dentro del elemento CashTransactions en sucesivos
elementos CashTransaction:

XML:

JSON:

{
"CashTransactions": [
{
"Id": 1,
"PosId": 1,
"UserId": 3,
"BusinessDay": "2014-09-29",
"Date": "2014-09-29T12:06:46",
"Amount": 500.00,
"Supplier": "Casbega",
"Description": "Devolución de Mercancía"
},
{
"Id": 2,
"PosId": 1,
"UserId": 3,
"BusinessDay": "2014-09-29",
"Date": "2014-09-29T12:07:20",
"Amount": -100.00,
"Supplier": "Fontanero",
"Description": "Grifo WC Caballeros"
}
]
}

Guía del Integrador 74 Versión 5.1.0

La información indicada para cada movimiento de caja es:

Id
Identificador del movimiento de caja.

PosId
Identificador del punto de venta donde se ha realizado el movimiento de caja.

UserId
Identificador del usuario que ha realizado el movimiento de caja.

BusinessDay
Fecha de negocio en que se ha realizado el movimiento de caja con formato aaaa-mm-
dd.

Date
Fecha y hora en que se ha realizado el movimento de caja con formato aaaa-mm-
ddThh:mm:ss.

Amount
Importe del movimiento de caja. Si es un movimiento de entrada, el importe será
positivo, y si es de salida, el importe será negativo.

Supplier
Proveedor para el que se ha realizado el movimiento de caja.

Description
Motivo o concepto del movimiento de caja.

Pedidos
Los pedidos se indican dentro del elemento SalesOrders en sucesivos elementos SalesOrder:

XML:

Guía del Integrador 75 Versión 5.1.0

<Customer Id="2" FiscalName="Sol y Sombra, S.L." Cif="B0018912"

Street="C/ García de Paredes, 10"
City="Madrid" Region="Madrid" ZipCode="28010"
ApplySurcharge="false"
AccountCode="43100001"/>

<DeliveryAddress Street="C/ García de Paredes, 10"

City="Madrid" Region="Madrid" ZipCode="28010" />

<Pos Id="1" Name="TPV" />

<SaleCenter Id="1" Name="Barra" Location="B1"/>

<Lines>
<Line
Index="0" Type="Standard"
CreationDate="2014-09-29T12:08:00"
ParentIndex="" MenuGroup=""
ProductId="16" ProductName="Hamburguesa doble"
SaleFormatId="16"
SaleFormatName="Hamburguesa doble"
SaleFormatRatio="1.000"
MainBarcode=""
ProductPrice="3.25"
Quantity="1.000"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
UnitPrice="4.25"
DiscountRate="0.0000" CashDiscount="0.0000"
TotalAmount="4.25"
UnitCostPrice="0.00"
TotalCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU="598"
FamilyId="1"
FamilyName="Hamburguesas"
PreparationOrderId=""
PreparationOrderName="">
<Addins>
<Addin ProductId="18" ProductName="Bacon"
SaleFormatId="18"

Guía del Integrador 76 Versión 5.1.0

SaleFormatName="Bacon"
SaleFormatRatio="1.000"
MainBarcode=""
ProductPrice="0.50"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
ProductCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU=""
FamilyId="2"
FamilyName="Complementos Hamburguesas" />
<Addin ProductId="17"
ProductName="Queso"
SaleFormatId="17"
SaleFormatName="Queso"
MainBarcode=""
SaleFormatRatio="1.000"
ProductPrice="0.50"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
ProductCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU=""
FamilyId="2"
FamilyName="Complementos Hamburguesas" />
</Addins>
<Notes><![CDATA[Muy Hecha]]>
</Line>
<Line
Index="1" Type="Standard"
CreationDate="2014-09-29T12:08:00"
ParentIndex="" MenuGroup=""
ProductId="5" ProductName="Fanta Limón"
SaleFormatId="5"
SaleFormatName="Fanta Limón"
SaleFormatRatio="1.000"
MainBarcode=""
ProductPrice="2.50"
Quantity="1.000"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
UnitPrice="2.50"
DiscountRate="0.0000" CashDiscount="0.0000"
TotalAmount="2.50"
UnitCostPrice="0.00"
TotalCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU=""

Guía del Integrador 77 Versión 5.1.0

FamilyId="3"
FamilyName="Refrescos"
PreparationOrderId=""
PreparationOrderName="" />
</Lines>

<Discounts DiscountRate="0.0050" CashDiscount="0.00" />

<Totals GrossAmount="6.22" NetAmount="5.65"

VatAmount="0.57" SurchargeAmount="0.00">
<Taxes>
<Tax VatRate="0.1000" SurchargeRate="0.0140"
GrossAmount="6.22" NetAmount="5.65"
VatAmount="0.57" SurchargeAmount="0.00" />
</Taxes>
</Totals>

</SalesOrder>
</SalesOrders>

JSON:

Guía del Integrador 78 Versión 5.1.0

{
"SalesOrders": [
{
"Customer": {
"Id": 2,
"FiscalName": "Sol y Sombra, S.L.",
"Cif": "B0018912",
"AccountCode": "43100001"
"Street": "C/ García de Paredes, 10",
"City": "Madrid",
"Region": "Madrid",
"ZipCode": "28010",
"ApplySurcharge": false
},
"DeliveryAddress": {
"Street": "",
"City": "",
"Region": "",
"ZipCode": ""
},
"Pos": {
"Id": 1,
"Name": "TPV"
},
"Workplace": {
"Id": 1,
"Name": "Local"
},
"User": {
"Id": "3",
"Name": "Pedro"
},
"SaleCenter": {
"Id": 1,
"Name": "Barra",
"Location": "B1"
},
"Notes": "",
"Lines": [
{
"Addins": [
{
"ProductId": 18,
"ProductName": "Bacon",
"SaleFormatId": 18,
"SaleFormatName": "Bacon",
"SaleFormatRatio": 1.000,
"MainBarcode": "",
"ProductPrice": 0.50,
"VatId": 3,
"VatRate": 0.1000,

Guía del Integrador 79 Versión 5.1.0

"SurchargeRate": 0.0140,
"ProductCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PLU": "",
"FamilyId": 2,
"FamilyName": "Complementos Hamburguesas"
},
{
"ProductId": 17,
"ProductName": "Queso",
"SaleFormatId": 17,
"SaleFormatName": "Queso",
"MainBarcode": "",
"SaleFormatRatio": 1.000,
"ProductPrice": 0.50,
"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"ProductCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PLU": "",
"FamilyId": 2,
"FamilyName": "Complementos Hamburguesas"
}
],
"Index": 0,
"Type": "Standard",
"CreationDate": "2014-09-29T12:08:00",
"ParentIndex": null,
"MenuGroup": "",
"ProductId": 16,
"ProductName": "Hamburguesa doble",
"SaleFormatId": 16,
"SaleFormatName": "Hamburguesa doble",
"SaleFormatRatio": 1.000,
"MainBarcode": "",
"ProductPrice": 3.25,
"Quantity": 1.000,
"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"UnitPrice": 4.25,
"DiscountRate": 0.0000,
"CashDiscount": 0.0000,
"TotalAmount": 4.25,
"UnitCostPrice": 0.00,
"TotalCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",

Guía del Integrador 80 Versión 5.1.0

"PLU": "",
"FamilyId": 1,
"FamilyName": "Hamburguesas",
"PreparationOrderId": null,
"PreparationOrderName": "",
"Notes": "Muy hecha"
},
{
"Index": 1,
"Type": "Standard",
"CreationDate": "2014-09-29T12:08:00",
"ParentIndex": null,
"MenuGroup": "",
"ProductId": 5,
"ProductName": "Fanta Limón",
"SaleFormatId": 5,
"SaleFormatName": "Fanta Limón",
"SaleFormatRatio": 1.000,
"MainBarcode": "",
"ProductPrice": 2.50,
"Quantity": 1.000,
"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"UnitPrice": 2.50,
"DiscountRate": 0.0000,
"CashDiscount": 0.0000,
"TotalAmount": 2.50,
"UnitCostPrice": 0.00,
"TotalCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PLU": "",
"FamilyId": 3,
"FamilyName": "Refrescos",
"PreparationOrderId": null,
"PreparationOrderName": ""
}
],
"Discounts": {
"DiscountRate": 0.0050,
"CashDiscount": 0.00
},
"LoyaltyProgram": {
"MemberId": "3hRXhZ01Kictq",
"Rewards": [
{
"Id": "7cnZDFPw",
"Name": "Descuento de 3€",
"Type": "CashDiscount",
"Value": 3.000000

Guía del Integrador 81 Versión 5.1.0

},
{
"Id": "8xmssMkq",
"Name": "Descuento Cumpleaños",
"Type": "NamedDiscount",
"Code": "EMPT"
}
]
},
"Payments": [
{
"ExtraInformation": "Tipo de Tarjeta: MASTERVISA",
"MethodId": 2,
"MethodName": "Tarjeta",
"Amount": -6.85,
"PaidAmount": -6.85,
"ChangeAmount": 0.00,
"PosId": 1,
"IsPrepayment": true
}
],
"Offers": [
{
"Id": 1
}
],
"Totals": {
"Taxes": [
{
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"GrossAmount": 6.22,
"NetAmount": 5.65,
"VatAmount": 0.57,
"SurchargeAmount": 0.00
}
],
"GrossAmount": 6.22,
"NetAmount": 5.65,
"VatAmount": 0.57,
"SurchargeAmount": 0.00
},
"Serie": "P",
"Number": 1,
"VatIncluded": true,
"BusinessDay": "2014-09-29",
"Date": "2014-09-29T12:08:00",
"Guests": null,
"Status": "Pending",
"AutoPrepare": "Always"
}

Guía del Integrador 82 Versión 5.1.0

]
}

La información indicada para cada pedido es:

Serie
Serie de pedido.

Number
Número de pedido.

BusinessDay
Fecha de negocio en formato aaaa-mm-dd.

Guests
Número de comensales. Vacío si no los tiene asociados.

VatIncluded
Indica si lleva impuestos incluidos (true) o no (false).

Date
Fecha y hora de creación del pedido en formato aaaa-mm-ddThh:mm:ss.

Pos
Identificador único y nombre del TPV en que se creó el pedido.

Workplace
Identificador único y nombre del Local en que se creó el pedido.

User
Identificador único y nombre del usuario que creó el pedido.

Status
Estado del pedido. Puede ser:

Pending
El pedido está pendiente de facturar.

Cancelled
El pedido no ha sido facturado y ya no podrá facturarse nunca más (por
ejempo, porque ha sido cancelado).

Invoiced
El pedido ha sido facturado.

AutoPrepare [Opcional: sólo válido a importar documentos]

Indica si se deben enviar las comandas a los puntos de preparación al importar el
documento. Los posibles valores de este campo son:

▪ Never: No enviar comandas nunca.

▪ Always: Enviar comandas siempre que se importa el documento.

Guía del Integrador 83 Versión 5.1.0

▪ OnlyIfNew: Enviar comandas sólo la primera vez que se importe el documento
(si el documento ya existía y se vuelve a importar, no se volverán a realizar los
envíos).

Customer
Datos del cliente al que se emite la factura, incluyendo:

Id
Identificador único del cliente.

FiscalName
Nombre fiscal del cliente.

Cif
CIF/NIF del cliente.

AccountCode
Código de la cuenta contable del cliente.

Street
Calle del cliente.

City
Población del cliente.

Region
Provincia del cliente.

ZipCode
Código postal del cliente.

ApplySurcharge
Indica si al cliente se le aplica recargo de equivalencia.

DeliveryAddress
Dirección de Entrega del pedido. Es opcional si no se indica se usará la dirección de
facturación del cliente.

Street
Calle del cliente.

City
Ciudad del cliente.

Region
Población del cliente.

ZipCode
Código Postal del cliente.

SaleCenter
Información del centro de venta donde se ha realizado el pedido, incluyendo Id,
Nombre y Ubicación.

Guía del Integrador 84 Versión 5.1.0

Notes
Notas asociadas al pedido.

Lines
Líneas del documento, cada una de ellas en un elemento Line con el siguiente
formato:

Index
Índice de la línea dentro del documento. Las líneas se empiezan a numerar en
0.

Type
Tipo de línea. Puede ser Standard si es una línea normal, MenuHeader si es la
un menú, o MenuItem si es un plato perteneciente a un menú.

CreationDate
Fecha en que se añadió la línea al documento.

ParentIndex
Índice de la línea a la que está asociada ésta. Sólo se utiliza en el caso de
platos de menú, es decir, cuando Type="MenuItem". En ese caso,
ParentIndex es el índice de la línea que contiene el menú al que pertenece
este plato. Si la línea es de otro tipo, este atributo estará vacío.

MenuGroup
Nombre del grupo de platos del menú al que pertenece esta línea. Sólo se
utiliza en el caso de platos de menú, es decir, cuando Type="MenuItem". En
ese caso, MenuGroup es nombre del group de platos al que pertenece este
plato. Si la línea es de otro tipo, este atributo estará vacío.

UserId
Identificador del usuario que añadió la línea.

ProductId
Identificador del producto principal de la línea.

ProductName
Nombre del producto principal de la línea.

SaleFormatId
Identificador del formamto de venta principal de la línea.

SaleFormatName
Nombre del formato de venta principal de la línea.

SaleFormatRatio
Ratio del formato de venta principal de la línea con respecto a su formato
base.

MainBarcode
Código de barras principal del artículo.

Guía del Integrador 85 Versión 5.1.0

ProductPrice
Precio unitario del producto principal de la línea. Este precio incluirá
impuestos o no dependiendo del valor del atributo VatIncluded del ticket.

Quantity
Cantidad.

VatId
Identificador único del impuesto asociado al producto principal de la línea.

VatRate
Tanto por uno de impuesto asociado al producto principal de la línea. Por
ejemplo, si el porcentaje de impuesto es 21%, este valor será 0.21.

SurchargeRate
Tanto por uno de recargo de equivalencia asociado al producto principal de la
línea. Por ejemplo, si el porcentaje de recargo es 4%, este valor será 0.04.

UnitPrice
Precio unitario de la línea incluyendo tanto el producto principal como los
añadidos. Es decir, si el producto principal tiene un precio de 6€ y lleva un
añadido de 2€, el valor de este atributo será 8€. Este precio incluirá
impuestos o no dependiendo del valor del atributo VatIncluded del ticket.

DiscountRate
Tanto por uno de descuento aplicado a la línea. Por ejemplo, si el porcentaje
de descuento es 10%, este valor será 0.1.

CashDiscount
Descuento en moneda aplicado a la línea.

TotalAmount
Importe total de la línea tras aplicar descuentos. Este valor incluirá impuestos
o no dependiendo del valor del atributo VatIncluded del ticket.

ProductCostPrice
Precio de coste del producto principal.

UnitCostPrice
Precio de coste unitario de la línea, incluyendo tanto el producto principal
como los añadidos.

TotalCostPrice:
Precio de coste total de la línea. Es decir la cantidad por el precio de coste de
la línea.

OfferId
En caso de que la línea pertenezca a una promoción se incluye este elemento
con el identificador de la oferta.

OfferCode
En caso de que la línea pertenezca a una promoción se incluye este elemento
con el código de la oferta.

Guía del Integrador 86 Versión 5.1.0

PreparationTypeId
Identificador del tipo de preparación del producto principal. Si no lleva tipo de
preparación el campo se dejará vacío.

PreparationTypeName [Opcional]
Nombre del tipo de preparación del producto principal.

PLU
PLU del artículo. Puede ser vacía si el artículo no tiene asignada ninguna PLU.

FamilyId
Identificador de la familia a la que pertenece el producto. Puede ser vacío si el
producto no está asociado a ninguna familia.

FamilyName
Nombre de la familia a la que pertenece el producto. Puede ser vacío si el
producto no está asociado a ninguna familia

PreparationOrderId
Identificador del orden de preparación del producto principal. Si no lleva tipo
de preparación el campo se dejará vacío.

PreparationOrderName [Opcional]
Nombre del orden del preparación del producto principal.

Addins
En caso de que haya añadidos al producto principal se incluyen en este
elemento. Para cada uno de ellos se indica información análoga a la del
producto principal salvo que no llevan ordenes de preparación, usan el orden
de preparación del producto principal.

Notes
Notas de preparación asociadas a la línea. Si la línea no lleva notas de
preparación, no se incluirá este elemento.

Discounts
Descuentos del documento

DiscountRate
Tanto por uno de descuento aplicado al documento. Por ejemplo, si el
porcentaje de descuento es 10%, este valor será 0.1.

CashDiscount
Descuento en moneda aplicado al documento.

Offers
Lista con las promociones asignadas:

Id
Identificador de la promoción.

Totals
Contiene el detalle de los descuentos en pie del documento y de los totales,
desglosándolos por base imponible. La información incluida para cada uno es:

Guía del Integrador 87 Versión 5.1.0

GrossAmount
Importe incluyendo los impuestos.

NetAmount
Importe tras descontar los impuestos.

VatAmount
Cuota correspondiente al impuesto.

SurchageAmount
Cuota correspondiente al recargo de equivalencia.

LoyaltyProgram [Opcional]
Información sobre los datos del participante del sistema de fidelización asociados al
documento en caso de que el documento tenga asociado un participante del programa
de fidelización. Puede consultar los detalles sobre la información suministrada en la
sección sobre integración con sistemas de fidelización de este manual.

Payments
Lista con los pagos asociados al pedido. Cada pago incluirá la siguiente información:

MethodId
Identificador de la forma de pago.

MethodName
Nombre de la forma de pago.

Amount
Cantidad total. La diferencia entra la cantidad pagada y el cambio

PaidAmount
Cantidad pagada.

ChangeAmount
Cambio entregado.

Date
Fecha en la que se ha realizado el pago.

PosId
Identificador del punto de venta donde se registró el pago

IsPrepayment
Indica si el pago se realizó antes de emitir al factura (true) o en el momento
de emitirla (false). En este caso de pedidos, todos los pagos tendrán el valor
true.

ExtraInformation
Información adicional sobre el pago que se haya introducido en el punto de
venta.

Los documentos aparecen ordenados primero por Fecha de Creación y luego por
Id.

Guía del Integrador 88 Versión 5.1.0

Albaranes (Cargos en Cuenta)
Los albaranes (cargos a cuenta) se indican dentro del elemento DeliveryNotes en sucesivos
elementos DeliveryNote:

XML:

Guía del Integrador 89 Versión 5.1.0

<Customer Id="2" FiscalName="Sol Sombra, S.L." Cif="B0018912"

Street="C/ García de Paredes, 10"
City="Madrid" Region="Madrid" ZipCode="28010"
ApplySurcharge="false"
AccountCode="43100001"/>

<DeliveryAddress Street="" City="" Region="" ZipCode="" />

<Pos Id="1" Name="TPV" />

<Workplace Id="1" Name="Local" />
<User Id="3" Name="Pedro" />
<SaleCenter Id="1" Name="Barra" Location="B1"/>
<Notes><![CDATA[]]> </Notes>
<SuggestedTip Percentage="0.00" VatId="0" VatRate="0.00"
SurchargeRate="0.00" ApplyToVatIncluded="true"
IgnoreTicketDiscounts="false" />
<ServiceCharge Rate="0.00" VatId="0" VatRate="0.00"
SurchargeRate="0.00" ApplyToVatIncluded="true"
IgnoreTicketDiscounts="false" GrossAmount="0.00"
NetAmount="0.00" VatAmount="0.00" SurchargeAmount="0.00" />
<Lines>
<Line
Index="0" Type="Standard"
CreationDate="2014-09-29T12:08:00"
ParentIndex="" MenuGroup=""
ProductId="16" ProductName="Hamburguesa doble"
SaleFormatId="16"
SaleFormatName="Hamburguesa doble"
SaleFormatRatio="1.000"
MainBarcode=""
ProductPrice="3.25"
Quantity="1.000"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
UnitPrice="4.25"
DiscountRate="0.0000" CashDiscount="0.0000"
TotalAmount="4.25"
UnitCostPrice="0.00"
TotalCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU="598"
FamilyId="1"
FamilyName="Hamburguesas"
PreparationOrderId=""

Guía del Integrador 90 Versión 5.1.0

PreparationOrderName="">
<Addins>
<Addin ProductId="18" ProductName="Bacon"
SaleFormatId="18"
SaleFormatName="Bacon"
SaleFormatRatio="1.000"
MainBarcode=""
ProductPrice="0.50"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
ProductCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU=""
FamilyId="2"
FamilyName="Complementos Hamburguesas" />
<Addin ProductId="17"
ProductName="Queso"
SaleFormatId="17"
SaleFormatName="Queso"
MainBarcode=""
SaleFormatRatio="1.000"
ProductPrice="0.50"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
ProductCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU=""
FamilyId="2"
FamilyName="Complementos Hamburguesas" />
</Addins>
<Notes><![CDATA[Muy Hecha]]>
</Line>
<Line
Index="1" Type="Standard"
CreationDate="2014-09-29T12:05:00"
ParentIndex="" MenuGroup=""
ProductId="5" ProductName="Fanta Limón"
SaleFormatId="5"
SaleFormatName="Fanta Limón"
SaleFormatRatio="1.000"
MainBarcode=""
ProductPrice="2.50"
Quantity="1.000"
VatId="3" VatRate="0.1000"
SurchargeRate="0.0140"
UnitPrice="2.50"
DiscountRate="0.0000" CashDiscount="0.0000"
TotalAmount="2.50"
UnitCostPrice="0.00"

Guía del Integrador 91 Versión 5.1.0

TotalCostPrice="0.00"
PreparationTypeId=""
PreparationTypeName=""
PLU=""
FamilyId="3"
FamilyName="Refrescos"
PreparationOrderId=""
PreparationOrderName="" />
<Notes><![CDATA[Sin hielo]]>
</Lines>

<Discounts DiscountRate="0.0050" CashDiscount="0.00" />

<Totals GrossAmount="6.22" NetAmount="5.65"

VatAmount="0.57" SurchargeAmount="0.00">
<Taxes>
<Tax VatRate="0.1000" SurchargeRate="0.0140"
GrossAmount="6.22" NetAmount="5.65"
VatAmount="0.57" SurchargeAmount="0.00" />
</Taxes>
</Totals>

</DeliveryNote>
</DeliveryNotes>

JSON:

Guía del Integrador 92 Versión 5.1.0

{
"DeliveryNotes": [
{
"Serie": "A",
"Number": 1,
"VatIncluded": true,
"BusinessDay": "2014-09-29",
"Date": "2014-09-29T12:08:00",
"Guests": null,
"Status": "Pending",
"AutoPrepare": "Always",
"Customer": {
"Id": 2,
"FiscalName": "Sol Sombra, S.L.",
"Cif": "B0018912",
"AccountCode": "43100001",
"Street": "C/ García de Paredes, 10",
"City": "Madrid",
"Region": "Madrid",
"ZipCode": "28010",
"ApplySurcharge": false
},
"DeliveryAddress": {
"Street": "",
"City": "",
"Region": "",
"ZipCode": ""
},
"Pos": {
"Id": 1,
"Name": "TPV"
},
"Workplace": {
"Id": 1,
"Name": "Local"
},
"User": {
"Id": 3,
"Name": "Pedro"
},
"SaleCenter": {
"Id": 1,
"Name": "Barra",
"Location": "B1"
},
"Notes": "",
"SuggestedTip": {
"Percentage": 0,
"VatId": 0,
"VatRate": 0,
"SurchargeRate": 0,

Guía del Integrador 93 Versión 5.1.0

"ApplyToVatIncluded": true,
"IgnoreTicketDiscounts": true
},
"ServiceCharge": {
"Rate": 0,
"VatId": 0,
"VatRate": 0,
"SurchargeRate": 0,
"ApplyToVatIncluded": true,
"IgnoreTicketDiscounts": true
},
"Lines": [
{
"Index": 0,
"Type": "Standard",
"CreationDate": "2014-09-29T12:08:00",
"ParentIndex": null,
"MenuGroup": "",
"ProductId": 16,
"ProductName": "Hamburguesa doble",
"SaleFormatId": 16,
"SaleFormatName": "Hamburguesa doble",
"SaleFormatRatio": 1.000,
"MainBarcode": "",
"ProductPrice": 3.25,
"Quantity": 1.000,
"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"UnitPrice": 4.25,
"DiscountRate": 0.0000,
"CashDiscount": 0.0000,
"TotalAmount": 4.25,
"UnitCostPrice": 0.00,
"TotalCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PLU": "598",
"FamilyId": 1,
"FamilyName": "Hamburguesas",
"PreparationOrderId": null,
"PreparationOrderName": "",
"Addins": [
{
"ProductId": 18,
"ProductName": "Bacon",
"SaleFormatId": 18,
"SaleFormatName": "Bacon",
"SaleFormatRatio": 1.000,
"MainBarcode": "",
"ProductPrice": 0.50,

Guía del Integrador 94 Versión 5.1.0

"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"ProductCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PLU": "",
"FamilyId": 2
"FamilyName": "Complementos Hamburguesas"
},
{
"ProductId": 17,
"ProductName": "Queso",
"SaleFormatId": 17,
"SaleFormatName": "Queso",
"MainBarcode": "",
"SaleFormatRatio": 1.000,
"ProductPrice": 0.50,
"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"ProductCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PLU": "",
"FamilyId": 2
"FamilyName": "Complementos Hamburguesas"
}
],
"Notes": "Muy hecha"
},
{
"Index": 1,
"Type": "Standard",
"CreationDate": "2014-09-29T12:05:00",
"ParentIndex": null,
"MenuGroup": "",
"ProductId": 5,
"ProductName": "Fanta Limón",
"SaleFormatId": 5,
"SaleFormatName": "Fanta Limón",
"SaleFormatRatio": 1.000,
"MainBarcode": "",
"ProductPrice": 2.50,
"Quantity": 1.000,
"VatId": 3,
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"UnitPrice": 2.50,
"DiscountRate": 0.0000,
"CashDiscount": 0.0000,

Guía del Integrador 95 Versión 5.1.0

"TotalAmount": 2.50,
"UnitCostPrice": 0.00,
"TotalCostPrice": 0.00,
"PreparationTypeId": null,
"PreparationTypeName": "",
"PreparationOrderId": null,
"PreparationOrderName": "",
"PLU": "",
"FamilyId": 3
"FamilyName": "Refrescos",
"Notes": "Sin hielo"
}
],
"Discounts": {
"DiscountRate": 0.0050,
"CashDiscount": 0.00
},
"LoyaltyProgram": {
"MemberId": "3hRXhZ01Kictq",
"Rewards": [
{
"Id": "7cnZDFPw",
"Name": "Descuento de 3€",
"Type": "CashDiscount",
"Value": 3.000000
},
{
"Id": "8xmssMkq",
"Name": "Descuento Cumpleaños",
"Type": "NamedDiscount",
"Code": "EMPT"
}
]
},
"Payments": [
{
"ExtraInformation": "Tipo de Tarjeta: MASTERVISA",
"MethodId": 2,
"MethodName": "Tarjeta",
"Amount": -6.85,
"PaidAmount": -6.85,
"ChangeAmount": 0.00,
"PosId": 1,
"IsPrepayment": true
}
],
"Offers": [
{
"Id": 1
}
],

Guía del Integrador 96 Versión 5.1.0

"Totals": {
"Taxes": [
{
"VatRate": 0.1000,
"SurchargeRate": 0.0140,
"GrossAmount": 6.22,
"NetAmount": 5.65,
"VatAmount": 0.57,
"SurchargeAmount": 0.00
}
],
"GrossAmount": 6.22,
"NetAmount": 5.65,
"VatAmount": 0.57,
"SurchargeAmount": 0.00
}
}
]
}

La información indicada para cada albarán es:

Serie
Serie de albarán.

Number
Número de albarán.

BusinessDay
Fecha de negocio en formato aaaa-mm-dd.

VatIncluded
Indica si lleva impuestos incluidos (true) o no (false).

Date
Fecha y hora de creación del albarán en formato aaaa-mm-ddThh:mm:ss.

Guests
Número de comensales. Si no se han indicado comensales, este campo aparecerá
vacío.

Pos
Identificador único y nombre del TPV en que se creó el albarán.

Workplace
Identificador único y nombre del Local en que se creó el albarán.

User
Identificador único y nombre del usuario que creó el albarán.

Guía del Integrador 97 Versión 5.1.0

SaleCenter
Información del centro de venta donde se ha realizado el albarán, incluyendo Id,
Nombre y Ubicación.

Notes
Notas asociadas al albarán.

Status
Estado del albarán. Puede ser:

Pending
El albarán está pendiente de facturar.

Cancelled
El albarán no ha sido facturado y ya no podrá facturarse nunca más (por
ejempo, porque ha sido cancelado).

Invoiced
El albarán ha sido facturado.

AutoPrepare [Opcional: sólo válido a importar documentos]

Indica si se deben enviar las comandas a los puntos de preparación al importar el
documento. Los posibles valores de este campo son:

▪ Never: No enviar comandas nunca.

▪ Always: Enviar comandas siempre que se importa el documento.

▪ OnlyIfNew: Enviar comandas sólo la primera vez que se importe el documento

(si el documento ya existía y se vuelve a importar, no se volverán a realizar los
envíos).

Customer
Datos del cliente al que se emite la factura, incluyendo:

Id
Identificador único del cliente.

FiscalName
Nombre fiscal del cliente.

Cif
CIF/NIF del cliente.

AccountCode
Código de la cuenta contable del cliente.

Street
Calle del cliente.

City
Población del cliente.

Region
Provincia del cliente.

Guía del Integrador 98 Versión 5.1.0

ZipCode
Código postal del cliente.

ApplySurcharge
Indica si al cliente se le aplica recargo de equivalencia.

DeliveryAddress
Dirección de Entrega del albarán. Es opcional si no se indica se usará la dirección de
facturación del cliente.

Street
Calle del cliente.

City
Ciudad del cliente.

Region
Población del cliente.

ZipCode
Código Postal del cliente.

SuggestedTip
Propina sugerida para la factura, incluyendo impuesto aplicado a la propina y modo de
aplicación (si es sobre el total con o sin impuestos y con o sin descuentos al pie del
ticket).

ServiceCharge
Recargo por servicio para la factura, incluyendo impuesto aplicado al servicio por
recargo y modo de aplicación (si es sobre el total con o sin impuestos y con o sin
descuentos al pie del ticket).

RelatedSalesOrder
Serie y número del pedido relaccionado con éste documento. Este campo sólo se indica
cuando el documento ha sido emitido a partir de un pedido.

Lines
Líneas del documento, cada una de ellas en un elemento Line con el siguiente
formato:

Index
Índice de la línea dentro del documento. Las líneas se empiezan a numerar en
0.

Type
Tipo de línea. Puede ser Standard si es una línea normal, MenuHeader si es la
un menú, o MenuItem si es un plato perteneciente a un menú.

CreationDate
Fecha en que se añadió la línea al documento.

ParentIndex
Índice de la línea a la que está asociada ésta. Sólo se utiliza en el caso de
platos de menú, es decir, cuando Type="MenuItem". En ese caso,

Guía del Integrador 99 Versión 5.1.0

ParentIndex es el índice de la línea que contiene el menú al que pertenece
este plato. Si la línea es de otro tipo, este atributo estará vacío.

UserId
Identificador del usuario que añadió la línea.

ProductId
Identificador del producto principal de la línea.

ProductName
Nombre del producto principal de la línea.

SaleFormatId
Identificador del formamto de venta principal de la línea.

SaleFormatName
Nombre del formato de venta principal de la línea.

SaleFormatRatio
Ratio del formato de venta principal de la línea con respecto a su formato
base.

MainBarcode
Código de barras principal del artículo.

ProductPrice
Precio unitario del producto principal de la línea. Este precio incluirá
impuestos o no dependiendo del valor del atributo VatIncluded del ticket.

Quantity
Cantidad.

VatId
Identificador único del impuesto asociado al producto principal de la línea.

VatRate
Tanto por uno de impuesto asociado al producto principal de la línea. Por
ejemplo, si el porcentaje de impuesto es 21%, este valor será 0.21.

SurchargeRate
Tanto por uno de recargo de equivalencia asociado al producto principal de la
línea. Por ejemplo, si el porcentaje de recargo es 4%, este valor será 0.04.

Guía del Integrador 100 Versión 5.1.0