POS API Integration Schema

Introduction

The integration between AlterVision and the store’s POS system aims to import daily sales summaries for each salesperson into the platform. AlterVision must display the same information that users see in their sales system reports; in other words, users need to confirm that the numbers in AlterVision exactly match those in the POS.

Our integration model is designed to keep store data history always up to date. To avoid discrepancies caused by adjustments made after data is retrieved from the API (such as the cancellation or consolidation of a transaction that occurred one or two days earlier), daily requests are performed. These requests query data from the last 5 days and send it to the platform.

The daily update is intended to continuously feed AlterVision with sales information as transactions occur. Requests are made every 20 minutes. Each store is updated individually, meaning one request will be made per CNPJ (or branch code) registered in AlterVision at each cycle.

Note

It is important to note that the flow of information will always be initiated by a request made by AlterVision, and the response to this request will be responsible for populating the platform.

Parameters

In each request, the following parameters will be sent:

• CNPJ (or store code)
• Start date
• End date

These parameters are required in the AlterVision standard specification and will be included in all requests. The API author must specify whether the parameters should be passed via headers, body, or URL, according to the HTTP verb used in the request.

For example, using the GET verb for the generic endpoint:

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

We would send the following parameters:

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

Thus, the request URL would be:

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

Parameter names do not necessarily need to be Cnpj, Data_inicio, and Data_fim. However, the API must accept query parameters that filter results by CNPJ, start date, and end date—or at minimum by start and end date when each CNPJ has its own login/token.

Data Response

When sending a query request to the API, the expected response must include the following information:

• Sale date (string format: YYYY-MM-DD)
• Sale hour (string format: HH)
• Salesperson name (string)
• Unique identifier or CPF of the salesperson (string)
• Number of sales (net) (integer or float)
• Number of items (net) (integer or float)
• Total sales value (net) (integer or float)

In other words, the API must return, for the given CNPJ or code, a summary of sales made between the selected dates at the time the request was triggered.

For data representation, the company may choose the most suitable format/technology already used for integrations, such as JSON or XML. If given the option, we always prefer the .json format due to its ease of handling.

JSON Example

[
  {
    "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
  }
]

Sales Data Query Period

As described in section 2, requests will always be filtered by a start date and an end date. This means that store sales data—both historical and current—must be available for querying at any time.

Therefore, if the API imposes data limits, it is necessary for the AlterVision integration that sales data be available for at least the past 60 days relative to the current date.

Considerations for Exchanges/Returns

To ensure that AlterVision data reflects exactly what users see in POS reports, it is important that the values for number of sales, number of items, and total sales per salesperson already represent the net totals of the day.

Typically, exchanges/returns are deducted from the totals. However, since each POS system may handle these transactions differently, we require this information to be already consolidated.

HTTP Verbs

Although best practices recommend retrieving resource data using the GET method, API query requests may be performed using either GET or POST HTTP verbs.

It is necessary for the system owner to inform which verb is used for handling request responses.

Authentication Methods (Login)

If the API uses a specific authentication method, it is necessary to describe how to invoke it and which parameters are involved (typically username and password). Our backend is prepared to authenticate with APIs via headers, body, or access token.

Basic Authorization is always a very convenient option for us.

API Method Examples

In integration processes with existing APIs, we often encounter documentation that is not sufficiently clear, lacks detailed descriptions of the environment, or does not clearly explain authentication and/or method usage.

Therefore, to streamline the process, providing method usage examples, brief descriptions of what each method returns, or indicating which methods contain the requested information will significantly speed up the integration.