Collection Postman
Faça o download da collection do Postman abaixo:
Introdução
A API SysOp expõe três endpoints. Todos recebem requisições POST com corpo em JSON e exigem autenticação por token — veja a seção Autenticação abaixo.
/api/db — executa uma instrução SQL, seja para consultar dados ou para alterá-los.
/api/script — executa uma lista de instruções SQL em sequência, como um script.
/api/anx — consulta anexos. É o único em que a instrução SQL não é enviada por você: a API a monta a partir das propriedades informadas.
Toda resposta traz informações sobre a instalação nos headers:
x-api-versao — Versão da API.
x-api-total — Quantidade de registros retornados pela query.
x-api-driver — Driver utilizado para o acesso ao banco de dados.
x-api-escopo — Modo de operação da API: read-only (somente leitura) ou read-write (leitura e gravação), conforme a configuração da instalação.
Quando o escopo é read-only, consultas continuam funcionando, mas comandos de INSERT, UPDATE e DELETE são recusados com a mensagem: “A API está configurada em modo somente leitura. Para realizar alterações nos dados, habilite a permissão de gravação nas configurações da API.”
# A opção -i exibe os headers da resposta junto com o corpo
curl -i -X POST "http://SEU_SERVIDOR:PORTA/api/db" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{"query":"SELECT * FROM t_0;"}'
# Headers retornados
HTTP/1.1 200 OK
Content-Type: application/json
x-api-versao: 300126
x-api-driver: Microsoft ACE OLEDB 12 (OLEDB)
x-api-escopo: read-write
x-api-total: 1
Autenticação
Os endpoints da API SysOp exigem autenticação por token JWT. Requisições enviadas sem token, ou com token inválido ou expirado, são recusadas com status 401.
O processo tem duas etapas: primeiro o token é obtido no endpoint /api/auth/login; depois ele é enviado no header Authorization de todas as demais requisições.
1. Obtendo o token
Envie uma requisição POST para /api/auth/login, com Content-Type: application/json e as credenciais no corpo. O usuário e a senha são fornecidos pela SysOpRS no momento da contratação.
POST /api/auth/login HTTP/1.1
Host: SEU_SERVIDOR:PORTA
Content-Type: application/json
{
"usuario": "SEU_USUARIO",
"senha": "SUA_SENHA"
}
Com credenciais válidas, a resposta vem com status 200 e o token no corpo:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expires_in": 3600,
"expires_at": "2026-10-23T17:35:12.4821376Z"
}
access_token — o token que deve ser enviado nas demais requisições.expires_in — validade do token em segundos (3600 = 1 hora).expires_at — data e hora em UTC em que o token expira.
Credenciais incorretas retornam status 401, sem corpo na resposta.
2. Enviando o token nas requisições
O token é enviado no header Authorization, precedido da palavra Bearer e de um espaço — o padrão Bearer Token. Vale para /api/db, /api/script e /api/anx, e os headers já existentes continuam os mesmos.
POST /api/db HTTP/1.1
Host: SEU_SERVIDOR:PORTA
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
{
"query": "SELECT codigo, nome FROM usuarios"
}
O mesmo fluxo, das duas etapas, usando cURL:
# 1. Obter o token
curl -X POST "http://SEU_SERVIDOR:PORTA/api/auth/login" \
-H "Content-Type: application/json" \
-d '{"usuario":"SEU_USUARIO","senha":"SUA_SENHA"}'
# 2. Usar o token na requisição
curl -X POST "http://SEU_SERVIDOR:PORTA/api/db" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{"query":"SELECT codigo, nome FROM usuarios"}'
3. Validade e erros
O token é válido por 1 hora. Depois desse prazo é necessário chamar /api/auth/login novamente para obter um novo token — não existe endpoint de renovação (refresh). Recomenda-se obter o token uma vez e reaproveitá-lo durante a sessão, renovando-o apenas quando expirar.
Requisições sem o header Authorization, ou com token inválido ou expirado, retornam status 401 com o corpo abaixo:
{
"message": "Token inválido ou expirado. Por favor, forneça um token válido."
}
Endpoint /api/db
O corpo da requisição tem uma propriedade obrigatória: query (string), onde vai a instrução SQL a ser executada.
O retorno depende do tipo de instrução:
Um SELECT devolve os dados em JSON, com status 200, como no exemplo abaixo.
Um INSERT, UPDATE ou DELETE não tem dados para devolver: a resposta é um array vazio ([]), também com status 200. Ou seja, array vazio aqui significa sucesso, não ausência de resultados.
curl -X POST "http://SEU_SERVIDOR:PORTA/api/db" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{"query":"SELECT * FROM t_0;"}'
# Resposta — 200 OK
[
{
"ID1": 1,
"razao": "Demonstração",
"fantasia": "Demonstração",
"CNPJ": "11111111111111"
}
]
Há ainda a propriedade opcional callback, para quando você precisa de uma informação depois de executar o comando. As duas trabalham juntas: query executa, callback devolve o resultado.
O caso mais comum é inserir um registro e precisar saber o ID que o banco acabou de gerar — o INSERT vai em query e a consulta do ID em callback:
curl -X POST "http://SEU_SERVIDOR:PORTA/api/db" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{
"query": "INSERT INTO t_0 VALUES...",
"callback": "SELECT MAX(ID1) AS RETORNO FROM t_0"
}'
# Resposta — 200 OK
[
{
"RETORNO": 1
}
]
Endpoint /api/script
Aqui a propriedade é script (array de strings): uma lista de comandos SQL que o servidor executa um após o outro, na ordem informada.
Dando tudo certo, a resposta é sempre {"message": "OK"} com status 200 — este endpoint não devolve dados, mesmo que algum comando da lista seja um SELECT.
curl -X POST "http://SEU_SERVIDOR:PORTA/api/script" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{
"script": [
"DELETE FROM tabela...",
"INSERT INTO tabela VALUES...",
"UPDATE tabela SET..."
]
}'
# Resposta — 200 OK
{
"message": "OK"
}
Se um dos comandos falhar, a execução para imediatamente naquele ponto e a resposta é status 500 com a descrição do erro. Atenção: os comandos executados antes da falha não são desfeitos — a lista não roda dentro de uma transação. Cabe a você reverter o que for necessário.
{
"message": "Erro de sintaxe na consulta. Cláusula de consulta incompleta."
}
Endpoint /api/anx
O endpoint /api/anx é utilizado para consultar os anexos.
As propriedades aceitas no corpo da requisição são:
tabela — string. Nome da tabela de anexos a ser consultada.criterio — string, opcional. Condição de filtro, aplicada como cláusula WHERE. Se omitida, nenhum filtro é aplicado.top — inteiro, opcional. Limita a quantidade de registros retornados. O padrão é 500.
Como os demais endpoints, exige o header Authorization.
curl -X POST "http://SEU_SERVIDOR:PORTA/api/anx" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer SEU_TOKEN" \
-d '{
"tabela": "Anexos",
"criterio": "ID1 = 1",
"top": 10
}'
# Resposta — 200 OK (as colunas variam conforme a tabela consultada)
[
{
"ID": 1,
"ID1": 1,
"Nome": "contrato.pdf",
"Anexo": "H4sIAAAAAAAACk1Ry07DMBD8lT1x..."
}
]
A coluna Anexo, quando presente, é devolvida comprimida em GZip e codificada em Base64 — o conteúdo precisa ser decodificado e descomprimido no lado do cliente antes de ser utilizado.
Neste endpoint, o header x-api-total traz o total de registros existentes na tabela, desconsiderando o criterio e o top — diferente de /api/db, onde ele indica a quantidade de registros retornados pela consulta.
Os registros são ordenados por ID, portanto a tabela consultada precisa possuir essa coluna. Em caso de falha, a resposta é status 500 com a descrição do erro na propriedade message.
Formatações
A instrução SQL viaja dentro de um JSON, e aspas duplas ou quebras de linha soltas quebrariam esse JSON. Para esses dois casos existem substitutos, que a API converte antes de executar a consulta:
_newline_ — vira uma quebra de linha.chr(34) — vira uma aspa dupla (").
No exemplo abaixo, o nome fica entre aspas e a descrição ocupa duas linhas:
INSERT INTO usuarios (nome, descricao) VALUES (chr(34)João Silvachr(34), chr(34)Linha 1_newline_Linha 2chr(34))
