Documentação da API SEAC versão 2

Esta documentação fornece detalhes sobre como consultar a API, incluindo regras de paginação, filtros e estrutura de resposta (JSON).

Endpoint Base

O endpoint varia conforme o ambiente (Desenvolvimento ou Produção). Exemplo Local: http://localhost:8091

Autenticação

A maioria dos endpoints requer autenticação. Certifique-se de enviar os tokens/headers necessários conforme implementado no Middleware de Autenticação.

---

Consultando Entidades (Getters)

A rota principal para consulta de dados é a entity_getter. Ela permite acessar Views do banco de dados de forma segura.

Rotas Disponíveis

• Listar/Filtrar Registros: GET /entity_getter/{entidade}

• Buscar Registro por ID: GET /entity_getter/{entidade}/{id}

Parâmetros de Consulta (Query Parameters)

Você pode passar parâmetros na URL para filtrar, ordenar e paginar os resultados.

1. Filtros (Equality)

Qualquer parâmetro que corresponda a uma coluna válida da tabela/view será tratado como um filtro de igualdade.

Exemplo: Buscar clientes ativos (status=A) na cidade de Sao Paulo: GET /entity_getter/clientes?status=A&cidade=Sao Paulo

2. Paginação

A API retorna os resultados paginados por padrão (50 registros por página).

• limit: Quantidade de registros por página (Padrão: 50).
• page: Número da página atual (Padrão: 1).

Exemplo: Página 2, com 20 registros por página: GET /entity_getter/clientes?page=2&limit=20

3. Ordenação

É possível ordenar os resultados por qualquer coluna.

• sort: Nome da coluna para ordenação.
• dir: Direção da ordenação (ASC para ascendente ou DESC para descendente). Padrão: ASC.

Exemplo: Ordenar por data de criação decrescente: GET /entity_getter/clientes?sort=created_at&dir=DESC

---

Estrutura da Resposta

A resposta é sempre um objeto JSON contendo o status, metadados de paginação e os dados solicitados.

Exemplo de Resposta (Lista)

{
    "status": "success",
    "meta": {
        "page": 1,
        "limit": 50,
        "total": 120,
        "pages": 3
    },
    "data": [
        { "id": 1, "nome": "Cliente A", "status": "A" },
        { "id": 2, "nome": "Cliente B", "status": "A" }
    ]
}

Exemplo de Resposta (Busca por ID ou Resultado Único)

Se a consulta for feita especificamente por ID (ex: /entity_getter/clientes/10), o campo data pode retornar o objeto diretamente ao invés de um array, dependendo da implementação específica do cliente.

{
    "status": "success",
    "meta": { ... },
    "data": { "id": 10, "nome": "Cliente X" }
}

---

Outros Endpoints

Saldo de SMS

Retorna o saldo de SMS disponível.

• GET /smsCredits

Stored Procedures (Dinâmico)

Executa qualquer Stored Procedure disponível no banco de dados. A API descobre automaticamente os parâmetros necessários consultando o banco de dados.

• GET /report/{procedure_name}
• POST /report/{procedure_name}

Parâmetros: Passe os parâmetros com o MESMO nome definido na Procedure do banco de dados (Ex: p_dataI).

Tabelas Temporárias: Se a procedure salva os dados em uma tabela temporária (ao invés de retornar direto), informe o nome da tabela no parâmetro reservado _temp_table.

Exemplo: GET /report/sp_gerar_kpi_venda?p_tipo_relatorio=ANALITICO&p_dataI=2025-01-01&_temp_table=relatorio_final_temp

Isso executará:

1. CALL sp_gerar_kpi_venda(params...)
2. SELECT * FROM relatorio_final_temp

Importação e Sincronização

• POST /entity_import: Importação genérica de entidades.
• POST /entity_post: Criação de registros.
• GET /verify_image: Sincronização de imagens.
• GET /verify_temp_folder: Limpeza de arquivos temporários.

---

Tratamento de Erros

Em caso de erro, a API retornará um JSON com status de erro e mensagem descritiva.

{
    "status": "error",
    "message": "Entidade não encontrada."
}

---

Detalhamento: sp_gerar_kpi_venda

Procedure responsável pela geração de KPIs de vendas, permitindo visão Sintética (agrupada) ou Analítica (detalhada).

Parâmetros Obrigatórios

Parâmetros de Agrupamento

O relatório permite até 10 níveis de agrupamento simultâneos (1 Principal + 9 Secundários). Os valores possíveis para as chaves de agrupamento são:

• vendedor
• cliente
• profissional
• grupo
• subgrupo
• cidade
• loja
• fornecedor
• controle

Parâmetros de Filtro (Opcionais)

Envie 0 ou null para ignorar o filtro (considerar todos).

Saídas

1. Sintético (p_tipo_relatorio='SINTETICO')

Retorna dados agregados pelas chaves de agrupamento escolhidas. Colunas:

• Nomes das colunas de agrupamento (Ex: Vendedor, Cidade).
• Métricas Financeiras: Venda Líquida(R$), Venda Bruta(R$), Devolução(R$), Comissão(R$), Frete(R$).
• Indicadores: Devolução(%), Ticket Médio, Itens por Nota, CMV (%), Markup (%).
• Contagens: Operações, Total Clientes, Novos Clientes.

2. Analítico (p_tipo_relatorio='ANALITICO')

Retorna a lista plana de operações, sem somatórios (exceto os calculados por item). Colunas:

• Tipo (Venda, Devolução), Operação (ID), Data.
• Colunas de identificação (IDs de Loja, Vendedor, Cliente, etc).
• Valores monetários individuais (Valor Líquido, Bruto, Custo).

Exemplos de Uso (Casos de Uso)

Abaixo estão exemplos práticos de como construir requisições para diferentes necessidades de análise.

1. Performance Geral: Loja e Vendedor

Objetivo: Ver o total vendido por cada loja e, dentro de cada loja, o desempenho de cada vendedor. Configuração:

• Tipo: SINTETICO
• Agrupamento Principal: loja
• Agrupamento Secundário 1: vendedor

GET /report/sp_gerar_kpi_venda?_temp_table=relatorio_final_temp&p_tipo_relatorio=SINTETICO&p_group_by_key=loja&p_group_by_secundario1=vendedor&p_dataI=2024-01-01&p_dataF=2024-01-31

2. Mix de Produtos por Vendedor (3 Níveis)

Objetivo: Analisar o que um vendedor específico (ID 99) está vendendo, quebrando por Grupo e Subgrupo de produtos. Configuração:

• Tipo: SINTETICO
• Filtro Vendedor: p_vendedor=99
• Agrupamento Principal: vendedor (ou grupo, já que o vendedor é fixo pelo filtro)
• Agrupamento Secundário 1: grupo
• Agrupamento Secundário 2: subgrupo

GET /report/sp_gerar_kpi_venda?_temp_table=relatorio_final_temp&p_tipo_relatorio=SINTETICO&p_vendedor=99&p_group_by_key=vendedor&p_group_by_secundario1=grupo&p_group_by_secundario2=subgrupo&p_dataI=2024-01-01&p_dataF=2024-01-31

3. Relatório de Comissão de Profissionais

Objetivo: Gerar relatório focado em comissão e premiação para profissionais, considerando apenas vendas liquidadas/faturadas. Configuração:

• Tipo: SINTETICO
• Flag Comissão: p_comissao=1
• Agrupamento Principal: profissional

GET /report/sp_gerar_kpi_venda?_temp_table=relatorio_final_temp&p_tipo_relatorio=SINTETICO&p_comissao=1&p_group_by_key=profissional&p_dataI=2024-01-01&p_dataF=2024-01-31

4. Extrato Analítico de Devoluções

Objetivo: Listar detalhadamente todas as operações que tiveram devolução de um cliente específico (ID 500). Configuração:

• Tipo: ANALITICO
• Filtro Cliente: p_cliente=500
• (Opcional) Filtro Custom: p_filtro_custom_venda="AND 1=0" (Para trazer apenas devoluções, se desejado forçar exclusão de vendas, embora o relatório traga ambos por padrão se houver movimento). Nota: O relatório padrão já separa por tipo de operação.

GET /report/sp_gerar_kpi_venda?_temp_table=relatorio_final_temp&p_tipo_relatorio=ANALITICO&p_cliente=500&p_dataI=2024-01-01&p_dataF=2024-12-31