Documentação da API EXATA (SEAC API v1)

Esta documentação destina-se a usuários finais e desenvolvedores que necessitam integrar ou consultar dados do sistema SEAC através da API RESTful JSON da EXATA Sistemas.

1. Visão Geral e Suporte

A API permite o acesso aos dados da empresa, incluindo cadastros, vendas, produtos e entregas.

Contato para Suporte: Se precisar de ajuda ou informações adicionais não cobertas nesta documentação:

Email: suporte@exatasistemas.com
Desenvolvedor: EXATA Sistemas

2. Primeiros Passos

Autenticação

A segurança da API é garantida através de chaves e tokens fornecidos pelo administrador de TI da sua empresa. Todas as requisições devem ser autenticadas.

Importante
Requisições sem autenticação válida retornarão o erro HTTP 401 (Não Autorizado).

Como Autenticar: Envie o cabeçalho (header) Authorization em suas requisições seguindo este formato:

Authorization: Basic [API_KEY]

Limites e Desempenho

Para garantir a estabilidade do sistema, existem regras de limites:

Rate Limit (Requisições por segundo):

O limite específico da sua chave é informado no cabeçalho X-RateLimit-Limit.
O quanto ainda pode ser usado é informado em X-RateLimit-Remaining.

Tamanho da Requisição:

O limite máximo é de 5 MB.

Nota
Se você exceder o limite de velocidade ou tamanho, receberá um erro HTTP 429 (Throttle Limit Reached).

Códigos de Erro Comuns

400 - Requisição Inválida (Bad Request).
401 - Não Autorizado (Unauthorized).
404 - Não Encontrado (Not Found).
422 - Entidade Não Processável (Dados inválidos).
429 - Limite de Requisições Excedido.
500 - Erro Interno do Servidor.

3. Padrões de Consulta

Paginação de Dados

Por padrão, todas as consultas GET retornam 100 registros por página.

Navegar entre páginas: Use o parâmetro page=X na URL.
Saber o total: O JSON de resposta contém o campo total_pages.

Exemplo: Ir para a página 15 da lista de pessoas:

entity_getter/person?page=15

Consultas Avançadas (Filtros)

Você pode filtrar resultados usando o parâmetro search.

Regras de Sintaxe:

A consulta deve estar entre colchetes [].
Separe múltiplas condições com ponto e vírgula ;.
Use aspas para textos (String) e datas.
Formato de data obrigatório: aaaa-mm-dd hh:mm:ss.
Use apenas campos que existem na entidade pesquisada.

Exemplos Práticos:

Filtrar por ID e Nome: Busca no grupo com ID maior que 3 e nome igual a 'Argamassas'.

entity_getter/group?search=[id>3;name='Argamassas']

Filtrar por Data de Alteração: Busca registros alterados após 1º de Novembro de 2021.

entity_getter/group?search=[updated_at>'2021-11-01 00:00:00']

4. Módulos e Recursos (GET)

Abaixo estão listados os endpoints disponíveis para consulta de dados, organizados por módulo.

🏢 Gerencial e Cadastros Básicos

Dados estruturais e de localização.

Empresas: /entity_getter/company
Países: /entity_getter/country
Estados (UF): /entity_getter/state
Cidades: /entity_getter/city
Bairros: /entity_getter/district
Planos de Pagamento: /entity_getter/payment_plan
Métodos de Pagamento: /entity_getter/payment_method

👥 Pessoas e Equipe

Colaboradores: /entity_getter/employee
Vendedores: /entity_getter/seller
Profissionais: /entity_getter/professional (Arquitetos, projetistas, etc.)
Fornecedores: /entity_getter/provider

📦 Produtos

Informações completas para gestão de estoque e catálogo.

Estrutura Mercadológica (Árvore de Categorias):

Grupo (Nível 1): /entity_getter/group - Categorias principais.
SubGrupo (Nível 2): /entity_getter/subgroup - Ligado ao Grupo.
Controle (Nível 3): /entity_getter/control - Ligado ao SubGrupo.

Detalhes do Produto:

Produto (Cadastro): /entity_getter/product
Marcas: /entity_getter/brand
Cores: /entity_getter/color
Voltagem: /entity_getter/voltage
Unidades: /entity_getter/unit
Imagens: /entity_getter/image (Usa EAN como referência).
Estoque (Quantidade): /entity_getter/stock
Preço de Venda: /entity_getter/sell_price

👤 Clientes

Pessoa Física: /entity_getter/person
Pessoa Jurídica: /entity_getter/legalperson

🚚 Entregas

Histórico (Eventos): /entity_getter/delivery_event
Status Atual: /entity_getter/delivery_status

💰 Vendas (Consultas)

Vendas (Lista Geral): /entity_getter/cashier
Venda Sintética (Resumo): /entity_getter/sale_master
Venda Analítica (Detalhada): /entity_getter/sale_detail

5. Fluxo de Vendas (Criação e Gestão)

Para criar, confirmar ou cancelar vendas, utilize o endpoint /entity_import.

Criar uma Nova Venda (POST)

Permite registrar uma venda e os dados do cliente.

Importante
Todos os campos são obrigatórios. Se não houver valor, envie o campo vazio (ex: "").

Lógica de Status na Criação:

Venda Concluída: Se você informar o número da Nota Fiscal (receipt).
Aguardando Confirmação: Se não informar o número da Nota Fiscal.

Atenção para Clientes Pessoa Jurídica (PJ): Se o cliente for PJ, substitua os campos iniciados por client.person pelos campos client.legalPerson (ex: client.legalPerson.trade_name, client.legalPerson.ie, etc).

Exemplo simplificado do corpo da requisição:

{
  "entity": "cashier",
  "products": [
    { "id": 4523, "quantity": 20, "price": 25.20, "discount_percentage": 10 }
  ],
  "client.person.cpf": "12345678921",
  "client.person.first_name": "Henrique",
  "delivery.address.street": "Avenida Brasil",
  "total_value": 5428.5,
  "net_value": 5050
}

Confirmar uma Venda (PUT)

Utilize este método para atualizar uma venda que estava "Aguardando Confirmação".

Objetivo: Inserir o número da Nota Fiscal para mudar o status para "Confirmado".
Restrição: Apenas o campo receipt (número do documento fiscal) pode ser atualizado aqui.

Possíveis Retornos:

success: Atualizado com sucesso.
error: "Venda não localizada", "Venda já confirmada" ou "Venda já cancelada".

Cancelar uma Venda (DELETE)

Permite cancelar uma venda existente.

Nota
Condições Obrigatórias:

A venda deve estar com status awaiting confirmation (aguardando confirmação).

Vendas já confirmadas (com nota fiscal) não podem ser canceladas via API.

A ação é irreversível.