Funcionamento das consultas de dados e filtros

🚧 Atenção sobre o consumo da nossa API

Durante períodos de alta carga operacional, especialmente em horários de pico, pode haver atrasos de D+1 na atualização dos dados disponíveis via API. Isso pode resultar no retorno de informações temporariamente desatualizadas em chamadas feitas nesse intervalo.

Para mitigar esse risco e garantir maior acurácia nos dados, recomendamos que agendamentos automatizados de consumo da API sejam configurados preferencialmente a partir das 05:00 (horário de Brasília), período em que o ambiente apresenta maior estabilidade e menor concorrência de processamento.

Filtros/Parâmetros obrigatórios

Todas as consultas disponíveis na API possuem como obrigatoriedade filtro das informações por um intervalo de datas.

Estão disponíveis em todas as consultas 3 opções de atributos de data para filtro de período, sendo eles:

shift_date: Filtro pela data do turno da venda, recomendado para situações para buscar vendas de um período maior e sem a necessidade de ser próximo à real time. Ex: Buscar vendas do dia de ontem, dos últimos 7 dias, etc.
created_at: Filtro pela Data/hora de criação da venda, recomendado para buscar vendas em um intervalo menor de tempo e mais próximo à realtime, exemplo, vendas criadas nas últimas 6 horas.
updated_at: Filtro pela data de alteração da venda. Vale lembrar que se uma venda for criada e não for mais alterada a data de criação e alteração será a mesma. Recomendado para situações de sincronismo de dados para outra base e atualização de alterações realizadas na Saipos em dados já extraídos pela API em outro momento. Ao usar esse filtro serão retornadas não só as vendas criadas no intervalo de tempo solicitada, mas também as vendas que sofreram alterações no período, ex: consultar vendas de ontem e alterações que ocorreram ontem (data da última consulta/sincronização). Com isso serão retornadas vendas criadas ontem e a título de exemplo, vendas de 3 dias atrás que foram canceladas.

Sendo assim, os 3 parâmetros obrigatórios nas consultas são:

p_date_column_filter: campo texto que deverá ser preenchido com o campo de data conforme disponível na qual deseja realizar a consulta.
p_filter_date_start: data inicial a ser aplicada no filtro
p_filter_date_end: data final a ser aplicada no filtro

🚧
Funcionamento da data do turno
Na Saipos o turno existe para concentrar em uma data/turno específico as vendas. No cadastro de um turno é definido a hora de início que começa o turno e a partir daquele horário todas as vendas realizadas serão incluídas como sendo daquele turno até o horário de início do próximo turno, ou seja, não é cadastrado horário de "fim" do turno, sendo que o fim de um é o horário de início do próximo.
Já a data do turno (shift date) também sobre influência, registrando a data em que o turno começou, independente da data que a venda foi incluída. Isso possui uma particularidade principalmente em restaurantes que atuam em períodos noturnos, conforme exemplo abaixo:
Restaurante possui os seguintes turnos cadastrados:
Dia - com início às 08h
Noite - com início às 18h
Há noites em que o estabelecimento está com bastante movimento e permanece aberto após 23h59min e nesse caso vendas cadastradas após às 00h são mantidas no turno da noite, uma vez que ele se iniciou às 18h e o próximo turno inicia-se apenas às 08h e o campo "shift_date" permanecerá com a data do último turno aberto.
Ou seja, a venda pode ter a seguinte data de criação (created_at) "2024-04-01 00:25:34" e o turno na configuração do exemplo cima permanecerá "2024-03-31", no dia anterior.
Essa regra foi desenvolvida com o objetivo de responder "dúvidas" dos clientes em relatórios quando querem saber "Quanto vendi ontem?" ou "Quantos produtos X vendi ontem?" e o desejo deles não é olhar apenas a "data" de ontem e excluindo vendas após à meia noite e sim possuem o objetivo de saber quanto vendeu nas operações que se iniciaram ontem, independente do horário que elas terminaram.
Vale destacar que todos os relatórios da Saipos quando existe um filtro de data (sem hora) utilizará o campo shift_date para realizar o filtro. Dessa forma, recomendamos que filtros na API de dados também sejam feitos com base nesse campo.

Filtros/parâmetros opcionais

p_limit: limite máximo de registros a serem retornados na requisição
p_offset: offset de paginação dos registros, começando sempre em 0