1. Visão geral

A API permite que um ERP leia os resultados da pesquisa de preços sem acesso direto ao banco. Ela é somente de consulta e possui três métodos: listar, obter e indicadores.

1.1 Segurança e escopo

• Somente administradores geram ou revogam tokens.
• O token completo aparece uma única vez; o banco guarda apenas SHA-256.
• O token só enxerga pesquisas de sua unidade administrativa.
• Tokens expirados, inativos ou revogados são recusados.
• O último uso é registrado a cada autenticação válida.

1.2 Como gerar

1. Acesse Recursos avançados → API para ERP.
2. Informe um nome que identifique sistema e ambiente, por exemplo “ERP Produção”.
3. Defina uma expiração quando possível.
4. Clique em Gerar token e copie a credencial imediatamente.
5. Cadastre a credencial no cofre do ERP e teste o método listar.

2. Requisição

2.1 Endpoint

POST https://SEU-DOMINIO/admin/rest.php

Por compatibilidade, erp_token também é aceito no corpo. O cabeçalho X-ERP-Token é preferível para evitar exposição acidental.

2.2 Exemplo com cURL

curl --request POST "https://SEU-DOMINIO/admin/rest.php" \
  --header "Authorization: Basic CHAVE_REST" \
  --header "X-ERP-Token: cpp_SEU_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "class": "CompraPesquisaErpApiService",
    "method": "listar",
    "limite": 50,
    "apos_id": 0
  }'

2.3 Envelope de sucesso

{
  "status": "success",
  "data": {
    "versao_api": "1.0",
    "gerado_em": "2026-07-29T14:00:00-04:00",
    "resultado": {}
  }
}

2.4 Envelope de erro

{
  "status": "error",
  "data": "Token ERP inválido, revogado ou expirado."
}

O ERP deve validar tanto o código HTTP quanto o campo status. Mensagens de erro podem mudar; não use o texto como regra permanente de negócio.

3. Métodos

3.1 listar

Retorna pesquisas da unidade em ordem crescente de ID.

{
  "class": "CompraPesquisaErpApiService",
  "method": "listar",
  "limite": 50,
  "apos_id": 120
}

Campos principais: ID, número da pesquisa, processo, objeto, datas, valor estimado, status e data da última atualização.

3.2 obter

Retorna uma pesquisa da unidade com itens, aprovações e metadados do documento final.

{
  "class": "CompraPesquisaErpApiService",
  "method": "obter",
  "id": 123
}

As aprovações incluem método, hash e data da assinatura. O documento final inclui o SHA-256 registrado, mas o arquivo PDF não é transferido por este método.

3.3 indicadores

Retorna a mesma visão consolidada do painel BI da unidade.

{
  "class": "CompraPesquisaErpApiService",
  "method": "indicadores"
}

A resposta contém métricas gerais, distribuição por status, série mensal, fontes mais utilizadas e indicadores de qualidade.

4. Sincronização recomendada

1. Guarde no ERP o maior ID confirmado.
2. Chame listar com esse valor em apos_id.
3. Para cada registro, chame obter e faça upsert pelo ID da pesquisa.
4. Atualize o cursor somente depois de persistir o lote inteiro.
5. Como pesquisas antigas podem ser atualizadas, execute também uma reconciliação periódica por updated_at.

4.1 Tratamento de falhas

• Use timeout de conexão e leitura.
• Repita falhas transitórias com espera exponencial e limite de tentativas.
• Não repita indefinidamente token inválido, revogado ou expirado.
• Registre ID de correlação no ERP sem gravar os cabeçalhos secretos.
• Alarme quando a integração ficar sem sucesso por período anormal.

4.2 Rotação e revogação

1. Gere um novo token e cadastre-o no ERP.
2. Valide uma chamada com a nova credencial.
3. Troque o segredo no ambiente de produção.
4. Revogue o token antigo na tela da API.
5. Confirme que chamadas com o token antigo são recusadas.

4.3 Checklist de homologação

• □ HTTPS válido e verificação de certificado habilitada.
• □ Credencial REST e token ERP armazenados em cofre.
• □ Isolamento da unidade conferido.
• □ Paginação com 0, 1, 50 e mais de 100 registros testada.
• □ Pesquisa inexistente tratada sem interromper o lote.
• □ Token expirado e revogado testados.
• □ Reconciliação de alterações por updated_at definida.
• □ Logs sem credenciais e com retenção definida.