FACIL FLOW - HTTP REST

Painel de Testes — conexão, autenticação e dados

PAINEL DE TESTES — SERVIDOR API

Valide conexão HTTP, autenticação por token e acesso ao banco.

Endpoints de Teste LOCAL

URL da API

X-API-Token

Socket HTTP PENDENTE

GET /status. Valida porta aberta.

Aguardando comando...

Autenticação PENDENTE

POST /executar. Valida token.

Aguardando comando...

Leitura SQL PENDENTE

Servidor

Banco

Tabela

Campos

Aguardando comando...

GERADOR DE CONFIGURAÇÃO — SERVIDOR API

Exemplo independente: preencha os dados e copie ou baixe o ServidorAPI.ini e o config.js. Esta página não lê nem grava a configuração instalada.

Servidor HTTP e segurança

Instância

Serviço Windows

Porta da API

Timeout (segundos)

Base URL do navegador

Token

Limite do corpo (KB)

Máximo de conexões

Nível do log

Retenção (dias)

SQL Server

Ativo

Servidor

Porta

Banco

Usuário

Senha

Servidor padrão

PostgreSQL

Ativo

Servidor

Porta

Banco

Usuário

Senha

MariaDB

Ativo

Servidor

Porta

Banco

Usuário

Senha

MySQL

Ativo

Servidor

Porta

Banco

Usuário

Senha

HFSQL

Ativo

Servidor

Porta

Banco

Usuário

Senha

Oracle

Ativo

Servidor

Porta

DSN

Banco/serviço

Usuário

Senha

ServidorAPI.ini

config.js

Os arquivos são atualizados enquanto você digita.

CONTEÚDO PARA IA

Documentação publicada, prompt de início e memória persistente.

1. Content da API

Fonte: WEB\content.md. Manual vivo publicado pela API.

INSTRUÇÃO PARA IA — LEIA A API ANTES DE PROGRAMAR

Sites públicos:
https://facilapp.com.br/facil-rest-api/
https://facilapp.com.br/ia/

Servidor publico HTTPS: https://api.facilapp.com.br

Documentação:
https://api.facilapp.com.br/content
https://api.facilapp.com.br/openapi.json
https://api.facilapp.com.br/status
https://api.facilapp.com.br/diagnostico.html
https://api.facilapp.com.br/swagger
https://api.facilapp.com.br/prompt
https://api.facilapp.com.br/sqlserver-teste
https://api.facilapp.com.br/postgresql-teste
https://api.facilapp.com.br/hfsql-teste

A API serve arquivos de Exe\WEB\. A IA não acessa C:\; ela acessa somente https://api.facilapp.com.br/...

INTERNA — NÃO CHAMAR:
1. ConsultarSQLLivre
2. ConsultarDados
3. ConsultarMetadados
4. ManterHFSQL

CHAMADAS PÚBLICAS PADRÃO:
1. consultar_sqlserver
2. consultar_postgresql
3. consultar_mariadb
4. consultar_mysql
5. consultar_oracle
6. consultar_hfsql

CHAMADAS PÚBLICAS LIVRES:
1. consultar_sqlserver_livre
2. consultar_postgresql_livre
3. consultar_mariadb_livre
4. consultar_mysql_livre
5. consultar_oracle_livre

CHAMADAS PÚBLICAS HFSQL:
1. inserir_hfsql
2. alterar_hfsql
3. excluir_hfsql

REPOSITÓRIO DE ARQUIVOS:
1. arquivo_salvar — recebe categoria, desenvolvedor, usuario, nome_arquivo e conteudo_base64.
2. arquivo_ler — retorna conteudo_base64.
3. arquivo_listar — lista nome e tamanho.
4. arquivo_excluir — remove o arquivo.
O cliente nunca envia C:\; a API monta DiretorioBase\categoria\desenvolvedor\usuario.

GENÉRICAS: consultar, listar_tabelas, listar_campos, consulta_livre, inserir, alterar, excluir e status.

Ordem: leia /content -> leia /openapi.json -> valide /status -> use POST /executar com X-API-Token. Não invente caminhos, senhas, tabelas, funções ou parâmetros.

2. Prompt de início de sessão

Fonte: WEB\prompt_inicio_sessao.md. Cole no começo de uma conversa nova.

Você vai integrar uma aplicação à FACIL FLOW - HTTP REST.

1. Leia https://api.facilapp.com.br/content.
2. Consulte https://api.facilapp.com.br/openapi.json.
3. Valide GET https://api.facilapp.com.br/status.
4. Use POST https://api.facilapp.com.br/executar com X-API-Token.
5. IP, porta e token pertencem à configuração local do aplicativo cliente; não inclua senhas de banco no JavaScript.
6. Credenciais, bancos, limites e pastas pertencem ao ServidorAPI.ini no servidor.
7. Ao ter dúvida, teste uma chamada pequena e mostre erro/resposta antes de alterar o projeto.

Não invente endpoint, tabela, campo, pasta local ou parâmetro que não esteja documentado.

3. Memória de contexto

Fonte: WEB\memoria_de_contexto.md. Contexto mestre para assumir o projeto.

MEMÓRIA — FACIL FLOW - HTTP REST PARA IA

Arquitetura: Aplicação cliente -> HTTP POST /executar -> Serviço WINDEV -> banco configurado no servidor.

Configuração: o cliente mantém somente IP/URL, porta e token. O servidor mantém token, bancos, usuários, senhas, limites, log e diretórios no ServidorAPI.ini. Nunca exponha senha de banco em HTML, JavaScript, content.md ou logs.

Bancos suportados: SQL Server, PostgreSQL, MariaDB, MySQL, Oracle e HFSQL.

Operação: GET /status não exige token. POST /executar exige X-API-Token quando segurança estiver ativa. Consultas estruturadas usam consultar. Consulta livre só é permitida se ConsultaLivre=1. Para HFSQL use funções específicas com sufixo _hfsql.

Fluxo: ler content -> conferir openapi -> testar status -> testar autenticação -> testar banco -> implementar. Sempre mostrar resposta e erro real. Não criar uma segunda ponte de API sem necessidade.

DOCUMENTAÇÃO TÉCNICA — SERVIDOR API

Configuração, rotas, bancos suportados, segurança e publicação.

Estado atual da API 22/07/2026

Bancos: SQL Server, PostgreSQL, MariaDB, MySQL, Oracle via ODBC e HFSQL Client/Server.

Consultas: modo estruturado por tabela/campos em todos os bancos. SELECT livre somente em SQL Server, PostgreSQL, MariaDB, MySQL e Oracle quando ConsultaLivre=1.

HFSQL: usa porta 4900 e HDeclareExternal para tabelas fora da análise. A tabela de homologação é apenas um exemplo; tabela e campos são enviados dinamicamente.

Testes: HFSQL, SQL Server, PostgreSQL, MariaDB, MySQL e Oracle.

Benchmark: carga de 5.000 requisições com o script 07-Benchmark-ServidorApi.ps1, medindo sucessos, falhas, RPS e latências média, P50, P95 e máxima.

JSON: envie funcao, servidor, banco e, conforme o modo, tabela/campos ou sql. O token vai somente no cabeçalho X-API-Token.

Manual para IA: arquivo instalado em WEB\MANUAL_COMPLETO_SERVIDOR_API_PARA_IA.md e fonte em Manuais e Prompt.

Servidor HTTP REST FACILAPP

Servidor HTTP em WINDEV 28 que recebe chamadas JSON, autentica pelo token e acessa SQL Server, PostgreSQL, MariaDB, Oracle e HFSQL sem depender de IIS, WEBDEV ou Node.js.

PORTA TCP 5000

Início rápido

Configurar No monitor, informe servidor SQL, porta, usuário, senha e token.

Reiniciar Reinicie a API pelo menu para recarregar o arquivo ServidorAPI.ini.

Testar HTTP Confirme primeiro GET /status.

Testar token e SQL Execute os testes desta página na ordem apresentada.

Endereços de acesso

Origem	Endereço
Máquina local	`http://127.0.0.1:5000`
Rede interna	`http://192.168.2.100:5000`
Internet testada	`https://api.facilapp.com.br`
Tailscale/VPN	Use o IP privado fornecido pela VPN.

Atenção: o IP público pode mudar. Para acesso remoto permanente, prefira IP fixo, DNS ou Tailscale.

Desempenho: se o banco está na máquina da API, configure-o em 127.0.0.1. Não use o IP público para a conexão interna.

Rotas disponíveis

Método	Rota	Token	Finalidade
`GET`	`/status`	Não	Confirma que o socket e a porta estão respondendo.
`GET`	`/` ou `/diagnostico.html`	Não	Abre esta página de diagnóstico e operação.
`GET`	`/config.js`	Não	Carrega URL, token e timeout usados pela página.
`GET`	`/servidor-api.js`	Não	Carrega o helper JavaScript.
`POST`	`/executar`	Sim	Executa `status`, `consultar`, `consulta_livre`, `inserir`, `alterar` e `excluir`.

Configuração do INI

O arquivo deve ficar ao lado do executável: Exe\ServidorAPI.ini. Usuário, senha e token permanecem no servidor.

[ServidorHTTP]
Ativo=1
Porta=5000

[Seguranca]
ExigirToken=1
Token=SEU_TOKEN

[SQL]
Servidor=127.0.0.1
Porta=1433
Usuario=SEU_USUARIO
Senha=SUA_SENHA

[PostgreSQL]
Servidor=127.0.0.1
Porta=5432

[MariaDB]
Servidor=127.0.0.1
Porta=3306

[HFSQL]
Servidor=127.0.0.1
Porta=4900

Regra: o INI define a conexão padrão. O JSON pode informar outro servidor ou banco autorizado. Nos exemplos e testes use FACILAPP_API.

Configuração JavaScript

Em config.js, use o mesmo token do INI. Em seguida carregue os arquivos nesta ordem:

window.SERVIDOR_API_CONFIG = {
  baseURL: "https://api.facilapp.com.br",
  token: "MESMO_TOKEN_DO_INI",
  timeoutMs: 15000
};

<script src="config.js"></script>
<script src="servidor-api.js"></script>

Nunca envie o usuário ou a senha SQL pelo JavaScript.

Função status

COMANDO JavaScript

const retorno = await ServidorAPI.executar("status");
console.log(retorno);

RESULTADO Resposta esperada

{
  "ok": true,
  "servico": "online",
  "tipo": "socket"
}

Função consultar

A consulta aceita somente nomes seguros de banco, tabela e campos. O backend limita a leitura a no máximo 500 registros.

COMANDO JavaScript

const retorno = await ServidorAPI.executar("consultar", {
  tipo_banco: "sqlserver",
  servidor: "127.0.0.1",
  banco: "FACILAPP_API",
  tabela: "API_TESTE",
  campos: "ID_API_TESTE,NOME"
});

console.log(retorno);

RESULTADO Exemplo

{
  "ok": true,
  "dados": [
    { "ID_API_TESTE": "1", "NOME": "DANIEL" }
  ]
}

Comandos reais para SQL Server, PostgreSQL, MariaDB e Oracle

Use uma única rota: POST /executar. Informe tipo_banco como sqlserver, postgresql, mariadb ou oracle.

Função externa	Campos do JSON	Uso
`consultar`	`tipo_banco, servidor, banco, tabela, campos`	Consulta estruturada.
`consulta_livre`	`tipo_banco, servidor, banco, sql`	Executa SELECT livre quando `ConsultaLivre=1`.
`inserir`	`tipo_banco, servidor, banco, sql`	Executa INSERT.
`alterar`	`tipo_banco, servidor, banco, sql`	Executa UPDATE.
`excluir`	`tipo_banco, servidor, banco, sql`	Executa DELETE.

await ServidorAPI.executar("inserir", {
  tipo_banco: "mariadb",
  servidor: "127.0.0.1",
  banco: "FACILAPP_API",
  sql: "INSERT INTO API_TESTE (NOME) VALUES ('DANIEL')"
});

HFSQL: use consultar_hfsql, inserir_hfsql, alterar_hfsql e excluir_hfsql. HFSQL não usa consulta_livre.

Regra para browse/update

Solicitar CREATE TABLE, SELECT do browse e SELECT por ID.
Confirmar chave, autonumeração, obrigatórios e validações.
Não enviar ID autonumérico no INSERT.
UPDATE/DELETE usam o ID da linha selecionada; nunca ID zero.
Após gravar, atualizar o browse uma única vez.
Buscar nos dados carregados, sem nova requisição por tecla.

Padrão CSS das telas

Cabeçalho #1673aa, fundo #edf2f5, cards brancos, borda #cad9e3, botões de 36 px e resultado JSON #0b3445.

header { background:#1673aa; color:#fff; }
.card { background:#fff; border:1px solid #cad9e3; }
button { height:36px; border-radius:4px; }
button.primary { background:#1673aa; color:#fff; }
pre.resultado { background:#0b3445; color:#bcecff; }
th:first-child, td:first-child { width:120px; }

Fetch e conversões WINDEV

Estas procedures são referências internas do projeto e não são valores enviados em funcao.

Procedure	Uso correto
`Fetch`	Executa `SELECT TOP 1` simples e posiciona o arquivo real da análise por `FetchManual`.
`FetchSQL`	Executa SELECT em `dsTabela/CONN`; fechar o Data Source ao terminar.
`FetchSQLUpdate`	Contrato legado; o Data Source retornado não confirma linhas alteradas.
`FetchManual`	Posiciona por chave simples/composta; em código novo use `HFound(pTabela)`.
`ConverteDataParaInteiro`	Data WINDEV para inteiro Clarion antes de gravar ou filtrar.
`ConverteInteiroParaData`	Inteiro Clarion para data WINDEV depois da leitura.

Datas variam conforme o projeto. Primeiro confirme o tipo real da coluna. Se ela armazenar uma data como inteiro Clarion, use as funções oficiais de conversão. Se for DATE, DATETIME ou TIMESTAMP, use o tipo nativo do banco. Não presuma o formato.

Teste pelo PowerShell

SEM TOKEN Porta e status

Invoke-RestMethod "http://localhost:5000/status"

COM TOKEN Backend

$h = @{ "X-API-Token" = "SEU_TOKEN" }
$b = @{ funcao = "status" } | ConvertTo-Json
Invoke-RestMethod "http://localhost:5000/executar" `
  -Method Post -Headers $h `
  -ContentType "application/json" -Body $b

Diagnóstico por sintoma

Conexão recusada: processo parado ou porta sem listener.
HTTP funciona e token falha: compare INI e config.js.
Token funciona e SQL falha: confira servidor, porta, credenciais, banco e tabela.
Funciona local e não na rede: confira firewall e IP interno.
Funciona na rede e não na Internet: confira NAT, IP público e CGNAT.
Rota não encontrada: use somente as rotas listadas neste manual.

Segurança e operação

Não registre token, usuário, senha ou dados pessoais no log.
Para acesso privado, prefira Tailscale ou outra VPN.
HTTP público não cifra token nem dados; para produção pública use HTTPS por proxy reverso/IIS.
Depois de alterar o INI, reinicie a API pelo monitor.
Use o painel de testes sempre na ordem: HTTP, autenticação e SQL.

Resultado saudável: os três testes ficam com o estado OK e o cabeçalho mostra SISTEMA OK.

Endpoints de Teste LOCAL

Socket HTTP PENDENTE

Autenticação PENDENTE

Leitura SQL PENDENTE

Diagnóstico da falha

Servidor HTTP e segurança

SQL Server

PostgreSQL

MariaDB

MySQL

HFSQL

Oracle

ServidorAPI.ini

config.js

1. Content da API

2. Prompt de início de sessão

3. Memória de contexto

Estado atual da API 22/07/2026

Servidor HTTP REST FACILAPP

Início rápido

Endereços de acesso

Rotas disponíveis

Configuração do INI

Configuração JavaScript

Função status

COMANDO JavaScript

RESULTADO Resposta esperada

Função consultar

COMANDO JavaScript

RESULTADO Exemplo

Comandos reais para SQL Server, PostgreSQL, MariaDB e Oracle

Regra para browse/update

Padrão CSS das telas

Fetch e conversões WINDEV

Teste pelo PowerShell

SEM TOKEN Porta e status

COM TOKEN Backend

Diagnóstico por sintoma

Segurança e operação