# API Clientes / Deconto

API PHP legada responsável pela integração de vendas, vendedores, lojas e metas da rede Deconto com o AUDAX.

## Estrutura principal

- `import_sells*`: indicadores de vendedores, lojas e grupos.
- `import_sellers` e `import_stores`: sincronização cadastral.
- `goals`: consulta e manutenção das metas diarizadas.
- `redistribute_goals`: redistribuição diária do saldo da meta.
- `regional-indicators`: consultas regionais.
- `premia/v1`: API somente leitura, versionada e isolada para lojas e pedidos
  do PS consumidos pelo PREMIA+. Os dados do comprador acompanham o pedido para
  que o CRM crie o contato e preserve a loja de origem.

A sincronização de lojas usa `group_id + external_id` como identidade. Ela só
inclui filiais ainda inexistentes e preserva o nome cadastrado no Audax, evitando
que nomes personalizados sejam revertidos ou que a mesma loja seja duplicada.

## Configuração

As credenciais não são versionadas. Configure no ambiente as variáveis documentadas em `.env.example`:

- `MYSQL_HOST`, `MYSQL_DATABASE`, `MYSQL_USER`, `MYSQL_PASSWORD`
- `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DATABASE`, `POSTGRES_USER`, `POSTGRES_PASSWORD`
- `OPENAI_API_KEY`, `OPENAI_PROJECT_ID`

O servidor web e o cron precisam receber essas variáveis no ambiente do PHP.

## Redistribuição de metas

O servidor executa diariamente:

```bash
/usr/bin/php /var/www/html/redistribute_goals/index.php
```

Antes de publicar alterações, valide a sintaxe:

```bash
find . -type f -name '*.php' -exec php -l {} \;
```

Valide os cenários de redistribuição sem acessar o banco:

```bash
php tests/redistribute_goals_test.php
```

## Configuração da integração

- `DECONTO_API_TOKEN`: quando configurado na API PHP, protege todos os endpoints que carregam `DatabaseController.php`. Configure o mesmo valor na API Node; sem a variável, o modo legado continua funcionando durante a migração.
- `DECONTO_API_URL`: permite à API Node apontar para outro host da integração sem alteração de código. O padrão permanece `http://deconto.sistemas.host`.
- `PREMIA_API_TOKEN`: chave obrigatória e exclusiva dos endpoints
  `/premia/v1/*`. Ela não substitui `DECONTO_API_TOKEN` e não muda a
  autenticação ou os contratos usados pelo Audax.
- Em instalações PHP legadas, as variáveis podem ficar em um arquivo `.env` não versionado na raiz da aplicação. `DECONTO_ENV_FILE` permite apontar para outro caminho protegido.

As rotas de indicadores são somente leitura: elas não atualizam mais loja, vínculo ou cadastro de usuário durante uma consulta.

## API PREMIA+ v1

As rotas novas são aditivas e não alteram nenhum endpoint legado do Audax:

- `GET /premia/v1/health/` valida a credencial e o banco;
- `GET /premia/v1/stores/?limit=100&after=0` lista filiais;
- `GET /premia/v1/orders/?storeId=4&from=2026-09-01&until=2026-09-30&limit=10`
  lista pedidos, devoluções, itens e o comprador. A resposta informa
  `nextCursor`; a próxima chamada deve repetir os filtros e enviar esse cursor.

Use `Authorization: Bearer ...` ou `X-Premia-Api-Key`. A chave nunca deve ser
enviada pelo navegador: somente o servidor PREMIA+ consulta esta API. As
consultas usam parâmetros, paginação com limite aceito de 200 (pedidos são
entregues internamente em páginas de até 10 para respeitar o tempo do ERP),
timeout e transação somente leitura.

No servidor, simule a redistribuição completa sem gravar alterações:

```bash
php redistribute_goals/index.php --dry-run
```

O redistribuidor é exclusivo do Grupo Deconto (`group_id = 25`), recupera todos
os dias anteriores do mês e ignora vendas e usuários do canal online.

Não versione planilhas em `goals/xlsx`, dependências em `vendor`, logs ou arquivos `.env`.