# API do integrador T2 — pacote de homologação

Esta é uma API nova e separada dos endpoints antigos do ERP. O pacote não contém credenciais. A instalação completa do integrador Delphi ainda precisa ser concluída e validada antes da ativação em produção.

## Requisitos

- PHP 8.2 ou superior com PDO MySQL, DOM/libxml, JSON e hash.
- MySQL 8.0. Testes executados em MySQL 8.0.46; MariaDB e MySQL 5.7 não estão homologados.
- Banco ERP compatível com o `banco-estrutura.sql` deste projeto. Não importar esse arquivo sobre o banco existente.
- HTTPS válido, sem redirecionamento na URL da API. Relógios do servidor PHP e do servidor local sincronizados: a autenticação aceita diferença máxima de 60 segundos.

## Arquivos no servidor

Publique somente os arquivos da pasta `public/` do pacote em uma pasta própria, por exemplo `/integrador/`. A URL ficará `https://SEU_DOMINIO/integrador/index.php`. Mantenha SQLs, manifesto e este guia fora da pasta pública. Não substitua endpoints legados.

Configure a conexão em um arquivo PHP privado, sem variáveis de ambiente:

1. Copie `config/conexao.exemplo.php` para `/home/USUARIO_CPANEL/t2-integrador/conexao.php`, fora de `public_html`. Crie a pasta `t2-integrador` se necessário.
2. Publique `public/index.php` e `public/sync.php` em `/home/USUARIO_CPANEL/public_html/integrador/`.
3. Edite `host`, `porta`, `senha` e `segredo_mestre` no arquivo privado. Restrinja a leitura à conta que executa o PHP. Não publique senhas nem use `phpinfo()` para conferir a configuração.

```php
<?php
return [
    'host' => 'localhost',
    'porta' => 3306,
    'senha' => 'SENHA_DO_MYSQL',
    'segredo_mestre' => 'SEGREDO_ALEATORIO_HEXADECIMAL_DE_64_CARACTERES',
    'teste_local' => false,
];
```

No `Integrador.ini` do servidor local:

```ini
[ERP]
URL=https://SEU_DOMINIO/integrador/index.php
BANCO=nomebanco
CHAVE=CHAVE_HEXADECIMAL_DE_64_CARACTERES
```

Com `BANCO=nomebanco`, a API conecta ao banco **nomebanco**, usando o usuário **eewde_nomebanco** e a senha definida no PHP. O código não adiciona prefixo ao banco nem remove prefixos enviados: se `BANCO=eewde_loja`, o usuário será `eewde_eewde_loja`, conforme a regra literal solicitada. Use o nome real do banco e crie/autorize o usuário correspondente no cPanel. A senha nunca é enviada pelo integrador.

O nome do banco não fica no PHP: ele vem do `.ini` de cada cliente. Não há lista fixa de bancos nem origem fixa no arquivo de conexão. A API consulta a origem responsável em `t2_sync_config.par` dentro do banco selecionado, depois de autenticar. Cada banco ERP precisa ter suas próprias migrations e sua própria configuração de origem/empresa, correspondente ao seu servidor local.

Cada cliente utiliza uma chave vinculada ao nome exato do seu banco. Alterar `BANCO` mantendo a chave de outro banco retorna `AUTENTICACAO_INVALIDA`, antes de conectar ao MySQL. O segredo mestre fica somente no servidor PHP; nunca o coloque no `.ini` ou o entregue ao cliente. Não utilize uma chave comum para todos os clientes.

Para configurar:

1. Gere o segredo mestre uma vez, em terminal privado: `php -r "echo bin2hex(random_bytes(32)), PHP_EOL;"`. Salve o resultado em `segredo_mestre` do `conexao.php`.
2. Copie `config/gerar_chave.php` para a mesma pasta privada do `conexao.php`.
3. Pelo terminal do servidor, execute `php /home/USUARIO_CPANEL/t2-integrador/gerar_chave.php nomebanco`.
4. Copie a chave retornada para `[ERP] CHAVE` do `.ini` do cliente cujo `[ERP] BANCO=nomebanco`.
5. Para outro cliente, repita o comando com o banco dele. Não precisa editar o arquivo de conexão para cadastrar o novo banco.

O gerador funciona somente por linha de comando. A chave derivada usa HMAC-SHA256 com domínio `t2-sync-banco-v1` e o nome exato do banco. Alterar o segredo mestre invalida todas as chaves de clientes; guarde-o com segurança e planeje a distribuição de novas chaves em uma rotação. Esta versão não possui revogação individual por lista; para retirar o acesso de um banco, revogue o acesso MySQL do usuário correspondente. A senha de conexão deste modelo é comum aos usuários `eewde_...` e fica somente no arquivo privado.

O Delphi envia `BANCO` no cabeçalho `X-T2-Banco`, incluído na assinatura HMAC em todas as ações. São aceitos 1 a 64 caracteres, letras ASCII, números e sublinhado. Nome ausente ou inválido é rejeitado, assim como assinatura com chave de outro banco. O banco local continua em `T2.ini`, seção `CONFIG`, campo `EMPRESA`.

Se a pasta pública do domínio tiver outra estrutura, ajuste somente o caminho `$file` em `sync_config()` de `sync.php` para o caminho absoluto do arquivo privado. Nunca receba o caminho da configuração por URL ou POST.

Não habilite `teste_local` em produção. Se houver proxy reverso, configure o servidor web para informar HTTPS ao PHP apenas a partir do proxy confiável; o código não confia em cabeçalhos encaminhados pelo cliente.

Atualize PHP e integrador juntos. Esta API não utiliza mais `T2_SYNC_*` do ambiente nem as linhas `SetEnv` anteriores, que podem ser removidas do `.htaccess`.

## Banco: instalação revisada antes da ativação

1. Faça backup e ensaie a instalação em uma cópia descartável. Os SQLs criam triggers nas tabelas comerciais; use janela de manutenção. DDL MySQL confirma implicitamente, portanto não há rollback global das migrations.
2. Revise `001_integridade_e_indices.sql`: modifica os tipos de XML/quantidade e cria índices. Se já foi aplicada, não repita sem conferir os índices existentes.
3. Na primeira instalação, execute `002_integrador_estrutura.sql`, `003_integrador_rotinas.sql`, `004_integrador_aplicacao.sql` e `005_integrador_confirmacoes.sql`, nessa ordem. São migrations desta versão inicial; não constituem um atualizador automático de versões anteriores.
4. Cadastre UMA configuração em `t2_sync_config`, usando os IDs reais de empresa em cada banco. Exemplo abaixo é modelo, não deve ser executado sem substituir os valores:

```sql
INSERT INTO t2_sync_config(id,lado,origem,par,empresa,empresa_par)
VALUES(1,'ERP','IDENTIFICADOR_ERP','IDENTIFICADOR_ESTAVEL_DA_LOJA',ID_EMPRESA_ERP,ID_EMPRESA_LOCAL);
```

No banco local a configuração é invertida: lado `PDV`, origem da loja, par do ERP, empresa local e empresa_par do ERP. Cada banco admite um par de integração/empresa em sua própria configuração. A mesma API atende vários bancos, cada um com sua chave derivada e sua configuração de origem. Não misture lojas independentes na mesma configuração de banco.

O usuário de instalação precisa de permissões para tabelas, triggers e rotinas. Use um usuário exclusivo para execução da API com as permissões comerciais/técnicas necessárias às rotinas e respectivos definers, sem privilégios administrativos globais. Teste com o usuário de execução, não apenas com o instalador. Configure limite de execução PHP/web compatível com o timeout do cliente; não permita requisições sem limite de duração.

## Operação e protocolo

Somente POST autenticado por HMAC-SHA256: `pull`, `push`, `ack`, `status`, `nack`. O integrador Delphi produz os cabeçalhos de autenticação; abrir a URL no navegador não é teste de sincronização. GET retorna `METODO_INVALIDO`; POST sem assinatura retorna `AUTENTICACAO_INVALIDA`.

Cada operação possui UUID, hash e revisão. O recibo só é gravado junto da transação no destino. Repetições não devem reaplicar estoque ou recebimentos. O envio só é concluído após confirmação. Registros pendentes ficam nas tabelas técnicas e sobrevivem a reinícios. Exclusões físicas e conflitos que exijam conciliação são retidos para revisão; ERP prevalece nos conflitos definidos de caixa e NFC-e. Não apague filas ou recibos para tentar reenviar.

Os triggers capturam mudanças após a configuração. A carga inicial de registros existentes e os vínculos entre cadastros já existentes precisam de preparação explícita; publicar PHP não faz a carga inicial automaticamente. Os utilitários de administração e o integrador ainda estão em finalização.

Consulta de pendências, sem dados sensíveis:

```sql
SELECT entidade,chave,estado,tentativas,proxima_tentativa,erro_codigo
FROM t2_sync_fila WHERE estado<>'concluido'
ORDER BY proxima_tentativa;

SELECT criado,operacao,entidade,codigo
FROM t2_sync_log ORDER BY id DESC LIMIT 100;
```

Não exponha essas consultas como endpoint público nem registre corpos das requisições: contêm dados pessoais e fiscais. Os erros HTTP retornam códigos sem senha ou SQL. Consulte também os logs protegidos do servidor web/PHP.

## XML

A API valida identidade fiscal, protocolo e correspondência com os dados, rejeitando DTD/entidades externas. Preserva o XML original no banco: não emite, renumera nem reescreve notas. Esta validação não equivale a validar assinatura criptográfica ou consultar a SEFAZ. A API não muda a pasta XML do ERP. No destino local, o integrador utiliza o arquivamento mensal existente em `Docs`, após gravação; o original não é movido ou excluído.

## Limites da entrega

Pacote destinado a homologação. A integração completa depende de configuração dos dois bancos, carga inicial, mapeamento dos IDs existentes e conclusão da validação do Delphi. Não trocar o executável operacional atual apenas por ter publicado a API. Os resultados do teste desta versão acompanham `VALIDACAO.txt` no pacote.