Manual da API

1. Visão geral

A API é dividida em três componentes:

Todas as requisições usam Content-Type: application/json e o método POST (exceto o coletor por GET/CLI). Respostas são JSON em UTF-8.

2. Autenticação (AppToken)

O api.php é público e usa o token padrão do sistema para falar com a SEFAZ. Se você tiver um token próprio da SEFAZ, envie-o no cabeçalho AppToken:

AppToken: seu_token_da_sefaz

O app.php usa sessão por cookie: após login ou registrar, o cookie de sessão é enviado automaticamente pelo navegador (use credentials: 'same-origin' no fetch).

3. Pesquisa de Produtos

POST api.php?metodo=produto

Pesquise por nome (descricao) ou código de barras (gtin).

Exemplo (cURL):

curl -X POST 'https://alequizao.com/economizaalagoas/api.php?metodo=produto' \
  -H 'Content-Type: application/json' \
  -d '{ "descricao": "COCA COLA 2L", "latitude": -9.6498, "longitude": -35.7089, "raio": 10, "dias": 5 }'

Exemplo por código de barras (JavaScript):

fetch('https://alequizao.com/economizaalagoas/api.php?metodo=produto', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ gtin: '7894900011517', raio: 15 })
}).then(r => r.json()).then(d => console.log(d.conteudo));

4. Pesquisa de Combustíveis

POST api.php?metodo=combustivel

Informe o tipoCombustivel desejado:

Exemplo:

curl -X POST 'https://alequizao.com/economizaalagoas/api.php?metodo=combustivel' \
  -H 'Content-Type: application/json' \
  -d '{ "tipoCombustivel": 1, "latitude": -9.6498, "longitude": -35.7089, "raio": 15, "dias": 3 }'

O formato de resposta segue o mesmo padrão da pesquisa de produtos.

5. Formato da resposta

Cabeçalho X-Cache indica a origem: HIT (cache) · MISS (consulta nova) · STALE (cache antigo por indisponibilidade da SEFAZ).

{
  "totalRegistros": 3436,
  "totalPaginas": 35,
  "pagina": 1,
  "registrosPorPagina": 100,
  "conteudo": [
    {
      "produto": {
        "codigo": "123456",
        "descricao": "COCA COLA 2L",
        "descricaoSefaz": "REFRIG COCA COLA PET 2L",
        "gtin": "7894900011517",
        "ncm": "22021000",
        "unidadeMedida": "UN",
        "venda": { "dataVenda": "2026-06-08T10:01:15Z", "valorDeclarado": 8.49, "valorVenda": 7.99 }
      },
      "estabelecimento": {
        "cnpj": "08950629000104",
        "nomeFantasia": "MERCADO EXEMPLO",
        "endereco": { "nomeLogradouro": "AV FERNANDES LIMA", "numeroImovel": "1500",
                      "bairro": "FAROL", "municipio": "MACEIO", "latitude": -9.6569, "longitude": -35.7330 }
      },
      "historico": [
        { "price": "8.4900", "date": "2026-06-01 09:12:00" },
        { "price": "7.9900", "date": "2026-06-08 10:01:15" }
      ]
    }
  ]
}

O campo historico é exclusivo do Economiza Alequizão (evolução dos preços coletados por este sistema).

6. Contas de usuário

Endpoints em app.php?acao=... (POST JSON). Respondem { "ok": true|false, ... }.

Registrar — app.php?acao=registrar

{ "nome": "João", "email": "[email protected]", "senha": "minhasenha" }
→ { "ok": true, "usuario": { "id": 1, "nome": "João", "email": "[email protected]" } }

Login — app.php?acao=login

{ "email": "[email protected]", "senha": "minhasenha" }
→ { "ok": true, "usuario": { "id": 1, "nome": "João", "email": "[email protected]" } }

Sessão atual — app.php?acao=sessao

→ { "ok": true, "usuario": { "id": 1, "nome": "João", "email": "..." } }   // ou usuario: null

Logout — app.php?acao=logout

→ { "ok": true }

As senhas são gravadas com hash (bcrypt via password_hash). A sessão dura 30 dias.

7. Monitoramento de preços

Requer login. Permite acompanhar tudo que foi vendido de um produto ou combustível desde a última conferida.

Adicionar — app.php?acao=monitor_add

Informe um critério: gtin, descricao ou tipoCombustivel (1–6).

// Produto por código de barras
{ "gtin": "7894900011517", "raio": 15, "latitude": -9.65, "longitude": -35.73 }

// Produto por descrição
{ "descricao": "CAFE 500G", "raio": 10 }

// Combustível
{ "tipoCombustivel": 1, "descricao": "Gasolina Comum", "raio": 15 }
→ { "ok": true, "id": 7 }

Listar — app.php?acao=monitor_list

→ { "ok": true, "monitoramentos": [
     { "id": 7, "rotulo": "CAFE 500G", "tipo": "descricao", "novidades": 3, "raio": 10, "ultima_checagem": "2026-06-08 12:00:00" }
   ] }

novidades = quantas vendas novas existem desde a última visualização.

Ver detalhes — app.php?acao=monitor_ver

Faz uma consulta ao vivo na SEFAZ, acumula no histórico, retorna as vendas novas e o histórico completo, e marca como visto.

{ "id": 7 }
→ {
  "ok": true,
  "monitor": { "id": 7, "rotulo": "CAFE 500G", ... },
  "novas":     [ { "descricao": "...", "valor": 12.9, "data_venda": "...", "loja": "...", "endereco": "...", "latitude": -9.6, "longitude": -35.7 } ],
  "historico": [ ... ]
}

Remover — app.php?acao=monitor_remove

{ "id": 7 } → { "ok": true }

8. Coletor (cron)

Consulta a SEFAZ periodicamente para cada item monitorado, acumulando as vendas mesmo quando o usuário não está pesquisando.

# Linha de comando (sem token):
php /www/wwwroot/alequizao.com/economizaalagoas/coletar.php

# HTTP (com token do .env):
curl "https://alequizao.com/economizaalagoas/coletar.php?token=SEU_TOKEN"

# Crontab — a cada 30 minutos:
*/30 * * * * php /www/wwwroot/alequizao.com/economizaalagoas/coletar.php >> /var/log/economiza_coletor.log 2>&1

9. Códigos de erro

{ "message": "Informe descricao ou gtin do produto." }
{ "ok": false, "message": "E-mail ou senha incorretos." }

10. Boas práticas

• Respeite o cache de 15 minutos; evite repetir a mesma consulta em intervalos curtos.
• Cada loja define a própria descrição — use palavras-chave e abreviações ao pesquisar produtos.
• As datas seguem o padrão UTC (ISO 8601). Converta para o fuso de Alagoas (UTC-3).
• Para monitorar produtos, prefira o código de barras (GTIN) — é mais preciso que a descrição.
• O acesso é gratuito; para alta demanda, monte uma camada intermediária própria.

Suporte: WhatsApp (82) 98871-7072 · [email protected] · Maceió - AL · Desenvolvido por Alex Junior Calado (Alequizão).