Esquema de Integración de PDV por API

Introducción

La integración entre AlterVision y el sistema de PDV de las tiendas tiene como objetivo importar los resúmenes diarios de ventas de cada vendedor a la plataforma. AlterVision debe mostrar la misma información que los usuarios ven en los reportes de sus sistemas de ventas; es decir, el usuario necesita confirmar que los números en AlterVision coinciden exactamente con los del PDV.

Nuestro modelo de integración busca mantener el historial de datos de las tiendas siempre actualizado. Para evitar discrepancias derivadas de ajustes realizados después de la lectura en la API (como, por ejemplo, la cancelación o consolidación de una transacción ocurrida uno o dos días antes), se realizan solicitudes diarias. Estas solicitudes consultan los datos de los últimos 5 días y los envían a la plataforma.

La actualización diaria tiene como objetivo alimentar AlterVision con la información de ventas a medida que las transacciones ocurren. Las solicitudes se realizan cada 20 minutos. Cada tienda se actualiza de forma individual, es decir, se realizará una solicitud por cada CNPJ (o código de sucursal) registrado en AlterVision en cada consulta.

Atención

Cabe destacar que el flujo de información siempre será iniciado por una solicitud realizada por AlterVision, y la respuesta a esta solicitud será responsable de alimentar la plataforma.

Parámetros

En cada una de las solicitudes se enviarán los siguientes parámetros:

• CNPJ (o código de la tienda)
• Fecha de inicio
• Fecha de fin

Estos parámetros son requeridos en la especificación estándar de AlterVision y se enviarán en todas las solicitudes. El autor de la API debe indicar si los parámetros deben enviarse por headers, body o URL, respetando el verbo HTTP utilizado en la solicitud.

Por ejemplo, utilizando el verbo GET para el endpoint genérico:

http://126.18.716.14:8078/api/Exemplo/

Se enviarían los parámetros:

• Cnpj: 12345678000100
• Data_inicio: 2019-06-01
• Data_fim: 2019-06-30

Y con ello, la URL de consulta sería:

http://526.18.716.14:8078/api/Exemplo?Data_inicio=01/06/2019&Data_fim=30/06/2019&Cnpj=12345678000100

Los nombres de los parámetros no necesariamente deben ser Cnpj, Data_inicio y Data_fim. Sin embargo, es necesario que la API acepte parámetros en la URL de consulta que permitan filtrar por CNPJ, fecha de inicio y fecha de fin o, como mínimo, por fecha de inicio y fecha de fin cuando cada CNPJ tenga su propio login/token.

Retorno de datos

Al enviar una solicitud de consulta a la API, la respuesta esperada por nuestro entorno de integración deberá contener la siguiente información:

• Fecha de la venta (tipo string: YYYY-MM-DD)
• Hora de la venta (tipo string: HH)
• Nombre del vendedor (tipo string)
• Código único o CPF del vendedor (tipo string)
• Cantidad de ventas (neto) (tipo integer o float)
• Cantidad de artículos (neto) (tipo integer o float)
• Valor total vendido (neto) (tipo integer o float)

Es decir, la API de consulta debe devolver, para el CNPJ o código informado, el resumen de las ventas realizadas entre las fechas seleccionadas en el momento en que se ejecutó la solicitud.

Para la representación de los datos, la empresa podrá elegir la mejor forma/tecnología que ya utilice para integraciones, como JSON o XML, por ejemplo. Si se nos ofrece la opción de elegir, siempre preferimos el formato .json, debido a la facilidad de manejo de la información.

Ejemplo en JSON

[
  {
    "data": "2025-01-01",
    "hora": "09",
    "nome": "Teste",
    "cpf": "1234567890",
    "numVendas": 30,
    "numItens": 60,
    "valor": 4000.00
  },
  {
    "data": "2025-01-01",
    "hora": "10",
    "nome": "Teste2",
    "cpf": "0987654321",
    "numVendas": 40,
    "numItens": 70,
    "valor": 4500.00
  }
]

Período de consulta de la información de ventas

Como se describe en la sección 2, las solicitudes siempre estarán filtradas por un período de fecha de inicio y fecha de fin. Esto significa que la información de ventas de la tienda, tanto histórica como actual, debe estar disponible para consulta en cualquier momento.

Por lo tanto, en caso de que la API tenga un límite de información, para la integración con AlterVision es necesario que los datos de ventas de la tienda estén disponibles para consulta en un rango de al menos 60 días anteriores a la fecha actual.

Consideraciones sobre cambios/devoluciones

Para que los datos en AlterVision reflejen exactamente lo que los usuarios ven en los reportes del PDV, es importante que los valores de cantidad de ventas, cantidad de artículos y valores totales de ventas de cada vendedor ya correspondan a los totales netos del día.

Normalmente, los cambios/devoluciones se descuentan de los totales contabilizados; sin embargo, como cada PDV puede manejar estos movimientos de manera diferente, necesitamos recibir esta información ya consolidada.

Verbos HTTP

Aunque las buenas prácticas recomiendan obtener datos de un recurso mediante el verbo GET, la solicitud de consulta en la API puede realizarse mediante los verbos HTTP GET o POST.

Es necesario que el responsable del entorno indique qué verbo ha sido adoptado para el retorno de las solicitudes.

Métodos de autenticación (login)

En caso de que exista un método específico de autenticación en la API, es necesario describir cómo invocarlo y cuáles son los parámetros involucrados (generalmente username y password). Nuestro backend está preparado para autenticarse en APIs mediante header, body o access token.

La autenticación Basic Authorization es siempre una opción muy conveniente para nosotros.

Ejemplos de métodos de la API

En los procesos de integración con APIs ya existentes, muchas veces nos encontramos con documentaciones que no son lo suficientemente claras, no presentan descripciones detalladas del entorno o no explican con claridad la autenticación y/o el uso de los métodos.

Por ello, para optimizar el proceso, proporcionar ejemplos de uso de los métodos, descripciones breves de lo que cada método devuelve o indicar en qué métodos se encuentran las informaciones solicitadas hará que el proceso sea mucho más ágil.