API Externa SEAC

Visão geral

A API expõe três grupos de recurso, todos com resposta JSON:

• Consulta de entidades — GET /entity_getter/{entidade}: clientes, produtos, vendas, vendedores, formas de pagamento, etc. Listas paginadas, com filtro e ordenação por query string.
• Relatórios — GET|POST /report/{relatorio}: relatórios paramétricos (ex.: KPI de vendas, sintético ou analítico).
• Webhooks — a API recebe eventos de sistemas parceiros (ex.: confirmação de pagamento de boleto).

Todos os recursos de dado exigem autenticação. O acesso é concedido pela EXATA por integração: cada token enxerga um conjunto específico de entidades/relatórios e os dados de uma empresa.

URL base

Health check público: GET /test → responde o texto Teste.

Autenticação

Envie o token fornecido pela EXATA no header Authorization, com o prefixo Bearer:

Authorization: Bearer SEU_TOKEN_AQUI

Envie o header em toda requisição de dado (inclusive nas de leitura). Requisições sem token, ou com token inválido, são rejeitadas.

Estrutura da resposta

Lista:

{
  "status": "success",
  "meta":   { "page": 1, "limit": 50, "total": 120, "pages": 3 },
  "data":   [ { "id": 1, "name": "..." }, { "id": 2, "name": "..." } ]
}

Busca por id (/entity_getter/{entidade}/{id}): quando encontra 1 registro, data vem como objeto; quando não encontra, data vem como {}.

Erro:

{ "status": "error", "message": "descrição do erro" }

As respostas são UTF-8 (Content-Type: application/json; charset=utf-8) e podem vir comprimidas (gzip) se o cliente enviar Accept-Encoding: gzip.

Paginação

meta.total considera os filtros aplicados; meta.pages é o total de páginas.

GET /entity_getter/client?page=2&limit=20

Filtros & operadores

Qualquer parâmetro de query que corresponda a um campo do resultado é usado como filtro. Além da igualdade, há operadores de comparação:

Regras:

• O nome do campo aceita apenas letras, números e _. Campos cujo nome contenha ponto (ex.: company.id, client.person.name) não podem ser usados como filtro nem em sort.
• Filtros se combinam com AND. Não há OR, LIKE ou IN por query string.
• Para intervalo, use os dois limites: ?vl_total>=500&vl_total<=2000.
• Datas: AAAA-MM-DD ou AAAA-MM-DD HH:MM:SS.

# produtos alterados a partir de uma data, ordenados por id desc, 20 por página
GET /entity_getter/product?updated_at>=2026-08-01&sort=id&dir=DESC&limit=20

Ordenação

Erros

Consulta de dados — GET /entity_getter

curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://seac-api.seacweb.com.br/entity_getter/client?limit=50&page=1"

Entidades disponíveis

A disponibilidade de cada entidade depende da liberação do seu token. Campos com ponto no nome (company.id…) não servem para filtro/sort.

Orçamentos — proposal_master / proposal_detail

• Situação: status_id = 0 aberto (open), 1 aceito — virou venda (accepted), 2 recusado (refused). Para listar só os abertos: ?status_id=0. No recusado, refusal_reason_id traz o motivo.
• Itens de um orçamento: GET /entity_getter/proposal_detail?proposal_id=<id> (o id do proposal_master).
• Valores do cabeçalho: total_value (bruto dos itens) − discount + shipping_value = net_value.
• Valores do item: price é o preço unitário; discount é o desconto da linha inteira; total_value = quantity × price; net_value = total_value − discount.
• Sincronização incremental: ?updated_at>=2026-10-01 00:00:00.

Precisa de uma entidade ou campo que não está aqui? Fale com a EXATA — dá para incluir/ajustar.

Relatórios — GET /report

Passe os parâmetros do relatório na query string (mesmos nomes documentados abaixo). Relatórios que gravam o resultado numa tabela temporária exigem o parâmetro _temp_table (o valor é informado junto com a documentação do relatório). O resultado é paginado (limit/page) e aceita os mesmos filtros/operadores do entity_getter sobre as colunas de saída.

KPI de vendas — sp_gerar_kpi_venda

Indicadores de venda no período, em visão sintética (agregada pelas chaves de agrupamento) ou analítica (linha a linha).

GET /report/sp_gerar_kpi_venda
    ?_temp_table=relatorio_final_temp
    &p_tipo_relatorio=ANALITICO           # ou SINTETICO
    &p_dataI=2026-08-01
    &p_dataF=2026-08-31
    &p_group_by_key=vendedor              # chave principal
    &p_group_by_secundario1=grupo         # até 9 quebras adicionais
    &p_comissao=0                         # 1 = calcula comissão/premiação
    &limit=50&page=1

Colunas — SINTETICO

Coluna(s) de agrupamento escolhidas + Venda Líquida(R$), Venda Bruta(R$), Devolução(R$), Devolução(%), Operações, Ticket Médio, Itens por Nota, CMV (%), Desconto Extra (%), Markup (%), Total Clientes, Novos Clientes, Total Profissionais, Novos Profissionais, Comissão(R$), Premiação(R$), Frete(R$), Qtd Movimentada.

Colunas — ANALITICO

Tipo (Venda / Devolução / Recebimento / Contratos), Operação, Data, coluna(s) de agrupamento, ID Loja, ID Vendedor, ID Profissional, ID Cliente, ID Grupo, ID Subgrupo, ID Fornecedor, ID Controle, Venda Líquida(R$), Venda Bruta(R$), Devolução(R$), Custo(R$), Desconto Extra(R$), ID Produto, Qtd Movimentada, Comissão(R$), Premiação(R$), Frete(R$).

Qtd Movimentada: quantidade do item na operação (negativa nas devoluções, para o sintético abater corretamente).

Webhooks

A API recebe notificações de sistemas parceiros. Hoje: