Jordi Vidal – Página 6

Requisitos:

La licencia con el módulo Mesas API y la integración necesaria. Configurar la integración en el propio Glop.
En caso de querer realizar pagos directos a las mesas, será necesario disponer de una licencia con el módulo de PagosQR

Configuración desde Glop:

La configuración en Glop se llevará a cabo en la sección de terminales, dentro de la pestaña «Módulos/API/PEDIDOS MESAS» en su apartado correspondiente.

Simplemente, será necesario marcar la casilla de verificación para activar la integración y activar los parámetros de aparcar automáticamente los pedidos recibidos y añadir artículos recibidos de nuevos pedidos a las mesas ya abiertas según conveniencia. Enlace al manual de configuraciones necesarias: Link

En caso de querer realizar pagos deberemos acceder a la pestaña de PAGOS QR y activar el envío de tickets en tiempo real.

Además tendremos que crear la forma de pago de tipo QR asociada.

También para gestionar pagos parciales por importe en los tickets deberemos habilitar su respectivo parámetro en la sección de parámetros del terminal.

Configuración desde App.glop.es (Sólo soporte)

Para activar una integración de pedidos mesa a un cliente se deberá seleccionar tanto la integración como la localización en la plataforma app.glop.es.

En el caso de que la integración cuente con la posibilidad de realizar Pagos QR, se deberá también activar dicho parámetro en el apartado de Cobros apps QR.

Localizaciones: Deliveries | Glop API Rest

Obtención de localizacionesPara poder obtener las reservas y redirigirlas a nuestros terminales, necesitamos que la plataforma integradora de Reservas nos envíe localizaciones/restaurantes a las que van dirigidos las reservas.
Nosotros hacemos un mapeo entre localizaciones y terminal de Glop de envío de las reservas.

La plataforma integradora deberá desarrollar un endpoint al cual llamaremos para que nos devuelva las localizaciones. La respuesta debe tener estas características:[ { "id":"96f8adc9-c1dd-42a8-94a1-6b6d669bcce6", "nombre":"Nombre Localización 1" }, { "id":"96f0d827-8b28-4f65-a874-89f67e76a9b4", "nombre":"Nombre Localización 2" } ]El campo id debe ser único para todos las localizaciones existentes. El id de localización lo obtenemos de la llamada explicada aquí.El campo nombre es el nombre de cada localización (restaurante o establecimiento)
Este endpoint debe ser remitido por la plataforma integradora a joaquin@glop.es.
Nuestro sistema siempre utiliza el id de localización de un JSON de reserva para «llevarlo» hasta el terminal (una vez mapeado).
La plataforma integradora necesita obtener de Glop los identificadores de las mesas para hacer un match entre el salón de Glop y el de la plataforma Obtener mesas por id grupo | Glop API Rest “La solicitud requiere que el Servicio Glop esté activo para responder a esta petición. Esto es necesario para la correcta recuperación de tablas a través de los grupos de terminales.” El ID de grupo se refiere a un establecimiento (Localización) que agrupa al menos un terminal. Un grupo puede contener uno o más terminales. Por ejemplo, si un propietario tiene dos establecimientos, esto implicaría tener dos ID de grupos diferentes: uno con uno o más terminales y el otro con sus propios terminales. Aquí un enlace al endpoint de obtener la lista de grupos de terminales: Obtener lista grupos terminales | Glop API Rest

Mesas: Obtener mesas por id grupo | Glop API Rest

Obtención de mesas
Para poder asignar las reservas a las mesas equivalentes en los salones de glop, las plataformas integradoras deberán usar este endpoint para recibir los identificadores únicos de cada mesa.
Nosotros hacemos un mapeo entre el número de mesa en los salones Glop y los identificadores que devolvemos en el endpoint. Para poder realizar esta llamada, el software Glop deberá estar en marcha.

Estructura endpoint a sistema externo de reservas

curl --request GET \ --url https://api.glop.es/api/v1/cloud/tables?id_grupo={id_grupo} \ --header 'Accept: application/json' \ --header 'Authorization: Bearer 123'
- Id_grupo: ID del grupo de terminales sobre el cual queremos obtener las mesas.
- Authorization: Token de acceso que se obtendrá mediante el endpoint de obtener token.
  
  Nuestro endpoint devolverá una respuesta con estos parámetros:
[ { "id_mesa": "12", "numero_mesa": "9", "id_salon": "1", "nombre_salon": "Salon Glop" } ]
- id_mesa: Identificador único de la mesa.
- numero_mesa: Número de la mesa en el salón de glop.
- id_salon: Identificador único del salón al cual pertenece la mesa.
- nombre_salon: Nombre del salón al cual pertenece la mesa en glop.

Revisión de los salones corresponden al grupo de terminales correcto

Revisar que los salones en la tabla TB_SALONES apunten al grupo de terminales correcto, sino al realizar la llamadas de obtener mesas no devolverá nada.

Obtener token de acceso: Autorización | Glop API Rest

Obtención del token
Para poder realizar llamadas a la API de Glop se necesitará obtener el Bearer Token de autorización mediante este endpoint. Para poder obtenerlo necesitaremos tener un sitio configurado con API Rest en App.glop.es.

Estructura endpoint a sistema externo de reservas

curl --request POST \ --url https://api.glop.es/api/v1/auth/oauth/token \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "grant_type": "client_credentials", "client_id": "{{client_id_client_user}}", "client_secret": "{{client_secret_client_user}}", "scope": "*" }'
- client_id: Id de las credenciales de API Rest del sitio.
- client_secret: Secret de las credenciales de API Rest del sitio.
  Estos valores deberán ser suministrados por el soporte de Glop.
  
  Nuestro endpoint devolverá una respuesta con estos parámetros:
  
  { "token_type": "string", "expires_in": 0, "access_token": "string" }El token a usar será el devuelto en el parámetro access_token.

Obtener Pedidos: Recibir pedidos | Glop API Rest

Glop siempre añadirá al ticket de la mesa los productos que se envíen. No se aceptarán anulaciones de líneas ya enviadas ni actualizaciones de las mismas.

Cada vez que se llame con el mismo id_mesa, se añadirán los nuevos productos a las líneas del ticket ya existente en esa mesa. Precaución: no enviar líneas de tickets que ya se enviaron anteriormente ya que se entenderán como líneas nuevas. Si no existiera ticket en esa mesa, se abriría la mesa y se crearía uno nuevo con las líneas. Si se recibe el id_mesa, el pedido se aparcará en dicha mesa en Glop, sin embargo si no se recibe el pedido se aparcará como un pedido delivery.

Estructura endpoint a sistema externo de reservas

curl --request POST \
  --url https://api.glop.es/api/v1/delivery/orders \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data '{
  "orderId": "6205109ce29381c7615f187c",
  "id_mesa": "1",
  "deliveryTime": "2022-02-10T14:05:00.000000Z",
  "_created": "2022-02-10T13:18:19.000000Z",
  "_updated": "2022-02-10T13:18:20.000000Z",
  "location": "6143250ca254e1a8323bec47",
  "orderIsAlreadyPaid": true,
  "discountTotal": 0,
  "channel": {
    "slug": "uber"
  },
  "payment": {
    "amount": 3200
  },
  "customer": {
    "name": "Hector",
    "phoneNumber": "912123123",
    "phoneAccessCode": "612123123",
    "email": "900f97630cd5@deliverect.com"
  },
  "deliveryAddress": {
    "street": "Avinguda asdasd Palmer, 3",
    "streetNumber": "4, 6º",
    "postalCode": "08840",
    "city": "Viladecans"
  },
  "clientComments": "Entrega sin contacto.",
  "orderType": 2,
  "deliveryCost": 0,
  "serviceCharge": 0,
  "deliveryTip": 0,
  "items": [
    {
      "plu": "9-rusa",
      "name": "RUSA",
      "price": 700,
      "quantity": 1,
      "discount": 0,
      "productType": 1
    },
    {
      "plu": "M-241-packfamiliarpollo",
      "name": "PACK FAMILIAR POLLO",
      "price": 2500,
      "quantity": 1,
      "discount": 0,
      "productType": 1,
      "subItems": [
        {
          "plu": "1-241-1-polloentero",
          "name": "POLLO ENTERO",
          "quantity": 1,
          "productType": 1
        },
        {
          "plu": "23-241-2-patatasasadasakompana",
          "name": "PATATAS ASADAS AKOMPAÑA",
          "quantity": 1,
          "productType": 1
        },
        {
          "plu": "6-241-3-croquetasdepollo",
          "name": "CROQUETAS DE POLLO",
          "quantity": 1,
          "productType": 1
        },
        {
          "plu": "61-241-4-alioli",
          "name": "ALIOLI",
          "quantity": 1,
          "productType": 1
        }
      ]
    }
  ]
}'

Obtener Grupos de terminales: Obtener grupos de terminales | Glop API Rest

Obtener lista grupos terminales. El ID de grupo se refiere a un establecimiento (Localización) que agrupa al menos un terminal. Un grupo puede contener uno o más terminales. Por ejemplo, si un propietario tiene dos establecimientos, esto implicaría tener dos ID de grupos diferentes: uno con uno o más terminales y el otro con sus propios terminales.

curl --request GET \
  --url https://api.glop.es/api/v1/cloud/terminal-groups \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123'

Obtener lista productos: Obtener lista productos | Glop API Rest

Endpoint para obtener productos.

Esta llamada puede ser parametrizada para obtener productos según:

Este endpoint está paginado: para más información lea aquí

curl --request GET \
  --url https://api.glop.es/api/v1/cloud/products \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: '

Obtener listado de terminales: Obtener listado de terminales | Glop API Rest

Obtener lista terminales.

curl --request GET \
  --url https://api.glop.es/api/v1/cloud/terminals \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123'

Módulo de Pagos QR

Obtener pre ticket por mesa: Obtener pre ticket por mesa | Glop API Rest

Esta llamada es una obtención ad-hoc contra los terminales GLOP para pedir tickets. Un ticket deberá estar aparcado en mesa para poder ser devuelto, si la mesa está abierta con ese ticket, el ticket en cuestión NO SE DEVOLVERÁ.

Es una llamada no instantánea que puede dar timeout a los 20 segundos de iniciarse
Si el parámetro mode=1 -> el ticket se bloqueará en GLOP y no podrá ser cobrado por el terminal, solamente por el método de pago externo que haya solicitado este ticket
Si el parámetro mode=0 -> el ticket será devuelto pero no se bloqueará: SOLAMENTE USAR para consultar si hay ticket en esa mesa.
El parámetro mode es OBLIGATORIO enviarlo.

El Servicio Glop debe estar activo para poder responder a esta petición.

curl --request GET \
  --url 'https://api.glop.es/api/v1/cloud/pretickets?mode=0' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123'
  --data '{ 
	"id_grupo": 1,
	"id_mesa": 1,
	"mode": 0
  }'

Detalle de las líneas.

El campo detail_type_product de los detalles de las líneas indicará si ese detalle es un producto COMBINADO, es una LÍNEA DE ARTÍCULO de menú o ARTÍCULO EXTRA. Es necesario saber esta información para cada detalle ya que si es ARTÍCULO EXTRA, el total de la línea con ARTÍCULOS EXTRAS será el resultado de la suma de total_amount más el precio de sus detalles con detail_type_product=3

Datos de prueba

Para las pruebas utilizar (no es necesario Servicio Glop activo) id_mesa=99999 id_grupo=1

Posibles errores

1.- Cuando el ticket se encuentra abierto en el TPV. Para poder obtener un ticket, este debe estar aparcado en mesa.

{
    "error": "La mesa está abierta: aparque el ticket.",
    "code": 500
}

2.- Cuando la mesa de la que se solicita el ticket no tiene ninguno.

{
    "error": "La mesa no tiene ticket aparcado.",
    "code": 500
}

Liberar un pre ticket / Cancelación de pago: Liberar un pre ticket / Cancelación de pago | Glop API Rest

Para cancelar el pago y que el ticket se pueda modificar en el terminal o utilizar otro método de pago.

Si se vuelve a querer pagar este ticket por un método de pago, volver a llamar al endpoint Obtener preticket por mesa.

curl --request PUT \
  --url https://api.glop.es/api/v1/cloud/pretickets \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data '{
  "id_ticket": "string",
  "id_terminal": "string",
  "payments": {
    "payment_channel": "string"
  }
}'

Pagar un pre ticket / Cerrar ticket: Pagar un pre ticket / Cerrar ticket | Glop API Rest

Marcar un ticket como pagado.

Pago completo del ticket

El campo payments.payment_1_amount debe ser igual al total del ticket entregado en Obtener preticket por mesa.
El campo payment_type debe ser igual a 0.
No es necesario enviar las líneas del ticket a partir de la versión 8.0, no enviar ticket_lines: ver el ejemplo Ejemplo pago total. En versiones anteriores será necesario enviar un array vacío.

curl --location --request PATCH 'https://api.glop.es/api/v1/cloud/pretickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 123' \
--data '{
    "id_ticket": "string",
    "id_terminal": "string",
    "num_ticket": "string",
    "sell_channel": "string",
    "pending_amount": "string",
    "date_new": "string",
    "id_mesa": "string",
    "payment_type": "0",
    "payment_channel": "string",
    "payments": {
        "payment_channel": "string",
        "payment_1_amount": "string",
        "payment_2_amount": "string",
        "payment_3_amount": "string"
    }
}'

Pagos parciales por importe del ticket

El campo payment_type debe ser igual a 2.
No es necesario enviar las líneas del ticket a partir de la versión 8.0, no enviar ticket_lines: ver el ejemplo Ejemplo pago parcial por importe. En versiones anteriores será necesario enviar un array vacío.
El campo payments.payment_1_amount será menor que el total del ticket entregado en «Obtener preticket por mesa».

El ticket se marcará como pagado en el terminal en el que se creó según el campo id_terminal.

curl --location --request PATCH 'https://api.glop.es/api/v1/cloud/pretickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 123' \
--data '{
    "id_ticket": "string",
    "id_terminal": "string",
    "num_ticket": "string",
    "sell_channel": "string",
    "pending_amount": "string",
    "date_new": "string",
    "id_mesa": "string",
    "payment_type": "2",
    "payment_channel": "string",
    "payments": {
        "payment_channel": "string",
        "payment_1_amount": "string"
    }
}
'

Pagos parciales por artículos del ticket

El campo payment_type debe ser igual a 1.
Se deberán enviar las líneas de los artículos que se pagan (en array ticket_lines) y la suma individual (campo de cada línea amount_item) de estas corresponderá al valor de payments.payment_1_amount (la cantidad que se está pagando).
El campo ud_item de las líneas de los artículos acepta como máximo 3 cifras decimales.
El campo ud_item podrá ser igual o inferior a la línea recibida del ticket original recibido de Obtener preticket por mesa.

curl --location --request PATCH 'https://api.glop.es/api/v1/cloud/pretickets' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 123' \
--data '
{
    "id_ticket": "string",
    "id_terminal": "string",
    "num_ticket": "string",
    "sell_channel": "string",
    "pending_amount": "string",
    "date_new": "string",
    "id_mesa": "string",
    "payment_type": "1",
    "payment_channel": "string",
    "payments": {
        "payment_channel": "string",
        "payment_1_amount": "string"
    },
    "ticket_lines": [
        {
            "id_item": "string",
            "id_lin_ticket": "string",
            "description_item": "string",
            "amount_item": "string",
            "ud_item": "string",
            "total_amount": "string",
            "tax_perc": "string",
            "tax_amount": "string",
            "tax": "string",
            "date_sale": "string",
            "id_terminal": "string",
            "id_employee": "string"
        }
    ]
}
'

Caso de uso:

Obtener lista productos: Obtenemos la lista de productos disponibles a través de la integración, asegurando que el sistema pueda recuperar con precisión la información sobre los productos que se ofrecen.
Obtener mesas por grupo de terminal: Continuamos verificando que el sistema pueda obtener de manera precisa la lista de mesas asociadas a un grupo específico de terminales de la integración, asegurando así que las mesas estén correctamente identificadas y disponibles para su uso.
Recibir pedidos: A continuación, procedemos a recibir pedidos desde la integración, asegurándonos de que el sistema pueda procesar adecuadamente los pedidos entrantes y asignarlos a las mesas correspondientes de manera precisa y eficiente.
Si la integración cuenta con la modalidad de pagos:
- Pago parcial Por artículo: Luego, realizamos una prueba de pago parcial por artículo utilizando la funcionalidad de la integración, asegurando que el sistema pueda gestionar correctamente el pago parcial de artículos individuales dentro de un pedido.
- Pago Parcial Por Importe: Continuamos con una prueba de pago parcial por importe utilizando la funcionalidad proporcionada por la integración, asegurándonos de que el sistema pueda gestionar correctamente el pago parcial de un pedido según el importe especificado.
- Pago completo del ticket: Finalmente, realizamos una prueba completa de pago del ticket utilizando la funcionalidad proporcionada por la integración, asegurándonos de que el sistema pueda procesar adecuadamente el pago completo del pedido.
Get Pre Ticket By Mesa y Grupo: Seguimos probando la funcionalidad para obtener un pre-ticket asociado a una mesa y grupo de terminales de la integración específicos, asegurando que el sistema pueda recuperar con precisión la información relevante para la gestión de pedidos.
Liberar Pre Ticket: Probamos la capacidad del sistema para liberar un pre-ticket asociado a un pedido en la integración, asegurándonos de que el sistema pueda cancelar adecuadamente la reserva de un pedido pendiente.
Save order (pedido mesa API): Finalizamos realizando pruebas para guardar un pedido de mesa utilizando la API de la integración, verificando que el sistema pueda registrar correctamente los detalles del pedido y mantener un registro adecuado de las transacciones.

Resumen:

Este documento proporciona información detallada sobre la integración con GLOP para las Mesas API.

Se requiere una licencia de Glop y la configuración del módulo de integración en el apartado Módulos/API/PEDIDOS MESA.
Se describen los diferentes casos de uso llevados a cabo con la integración.
Se presentan varios endpoints necesarios para la integración con GLOP, como obtener listado de productos, recibir pedidos y obtener mesas por id grupo de terminales.
Se detalla la estructura de los endpoints, ejemplos de respuestas y la importancia de ciertos parámetros como el User-id.