Referência HTTP

API /api/v1

Use esta API em integrações server-to-server para disparar ações nos agents, consultar status de tarefas e gerenciar recursos (consultas, templates), sempre com um token de API emitido pelo console.

URL base

O host do servidor de API em produção é https://api.vectorhub.ramme.dev/. Os endpoints desta referência usam o prefixo /api/v1 a partir desse host.

URL base completa da API de integração:

https://api.vectorhub.ramme.dev/api/v1

Em ambientes dedicados ou homologação, a sua equipe pode indicar outro host; a estrutura dos caminhos permanece a mesma.

Autenticação

Envie o token de API no cabeçalho Authorization:

Authorization: Bearer <seu-token-de-api>

Tokens são criados no console pelo administrador. O valor completo do token é mostrado apenas na criação; guarde-o em local seguro (variável de ambiente, cofre de segredos, etc.).

Em caso de falha de autenticação, a API responde com 401 e um JSON com error e message (por exemplo, token ausente, inválido ou desativado).

O que o token permite

Cada token opera dentro dos limites definidos no console:

  • Ações (jobs): só é possível solicitar ações cujo módulo foi liberado para aquele token. O nome da ação segue o padrão módulo.operação (ex.: print.send); apenas a parte antes do primeiro ponto conta como módulo.
  • Recursos: os tipos query e template só aparecem na API se tiverem sido autorizados para o token. Caso contrário, listagens e leituras não os incluem e gravações podem retornar 403.

Jobs

Um job representa uma solicitação de execução de uma ação no ambiente dos agents. Através desta API, cada token vê apenas os jobs que ele mesmo criou.

POST /jobs

Cria um job e o envia para execução. O modo de resposta depende dos campos opcionais sync e callbackUrl — veja Modos de resposta.

Corpo JSON

CampoObrigatórioDescrição
actionsimNome da ação (ex.: data.execute). Deve existir no catálogo de módulos e ser permitida para o token. Veja Ações.
paramsnãoObjeto JSON enviado ao agent. Padrão {}.
agentIdnãoAgente que deve executar a tarefa. Se omitido, o sistema escolhe um agente disponível capaz de executar a ação.
timeoutnãoLimite de tempo em milissegundos para a execução no agent.
prioritynãolow, normal ou high. Padrão normal.
syncnãoSe true, o servidor aguarda a conclusão do job e retorna o resultado na própria resposta. Veja Modos de resposta.
syncTimeoutnãoTempo máximo de espera em milissegundos no modo síncrono. Padrão 30000, máximo 60000.
callbackUrlnãoURL para notificação via webhook quando o job terminar. Veja Modos de resposta.

400 se action estiver ausente ou for desconhecida (code: "UNKNOWN_ACTION", sem criar o job); 403 se o módulo da ação não for permitido para o token; 408 se o timeout síncrono expirar; 500 em falha ao processar a solicitação.

GET /jobs

Lista os jobs criados por este token. Cada item tem o mesmo formato do objeto retornado por GET /jobs/:jobId (estado na hora da listagem). Resposta { "jobs": [ ... ] }.

GET /jobs/:jobId

Retorna o job atual pelo identificador, com { "job": { ... } }. 404 se não existir ou não estiver acessível com este token.

Quando a execução termina com sucesso (status completed), o objeto inclui o campo result com o retorno da ação no agent (objeto JSON, lista, texto, etc., conforme o módulo e a ação). Enquanto o job está pending, dispatched ou running, result em geral ainda não vem preenchido; durante running podem aparecer progress e progressMessage.

Se a execução falha ou é interrompida de forma terminal (failed, cancelled, timeout, agent_disconnected, entre outros), o objeto pode trazer error com code, message e, quando aplicável, details.

Jobs em estado terminal (completed, failed, cancelled, timeout, agent_disconnected, etc.) são removidos da memória do servidor 1 hora após o instante de conclusão (em geral o campo completedAt). Depois disso, GET /jobs/:jobId responde 404 e o job deixa de aparecer em GET /jobs. Enquanto estiver pending, dispatched ou running, não há expiração por esse prazo. Um reinício do serviço também apaga todos os jobs em memória. Para histórico duradouro, guarde result ou error no seu sistema assim que o job estiver terminal.

Modos de resposta

Por padrão o endpoint é assíncrono: retorna 202 Accepted imediatamente e o resultado deve ser consultado em GET /jobs/:jobId (polling). Dois campos opcionais alteram esse comportamento:

Modo síncrono (sync: true)

O servidor aguarda a conclusão do job antes de responder. Útil quando o resultado é necessário na sequência da chamada e a latência esperada é baixa.

  • Quando o job chega a um estado terminal dentro do prazo: resposta 200 OK com { "job": { ... } }. O resultado da ação está em job.status — em sucesso (completed) vem job.result; em falha (failed e afins) vem job.error com code/message. O HTTP 200 significa que o job terminou a tempo, não que a ação teve sucesso.
  • Quando o prazo expira antes de o job terminar: resposta 408 Request Timeout com { "job": { ... }, "error": "sync_timeout" }. O job continua rodando no servidor; consulte-o via GET /jobs/:jobId (polling).

Use syncTimeout para definir o prazo máximo (padrão 30 s, máximo 60 s). Consultas que podem passar de 60 s devem usar o caminho assíncrono + polling (abaixo), não o modo síncrono.

curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"data.execute","params":{"queryId":"minha-consulta"},"sync":true,"syncTimeout":10000}'

Polling (consultas longas)

O caminho recomendado para consultas que podem passar do máximo síncrono (60 s): crie o job sem sync (resposta 202) e consulte GET /jobs/:jobId a cada poucos segundos até status terminal.

# 1) cria o job (assíncrono)
curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"data.execute","params":{"queryId":"consulta-pesada"}}'
# → { "job": { "id": "<jobId>", "status": "pending", ... } }

# 2) polling até completed / failed / …
curl -s "https://api.vectorhub.ramme.dev/api/v1/jobs/<jobId>" \
  -H "Authorization: Bearer <seu-token-de-api>"

Modo webhook (callbackUrl)

O endpoint retorna 202 Accepted imediatamente. Quando o job atinge um estado terminal (sucesso, falha, timeout, desconexão do agent, etc.), o servidor faz um POST para a URL informada com o objeto do job no corpo.

  • O corpo enviado ao webhook é { "job": { ... } } com Content-Type: application/json.
  • O servidor tenta a entrega uma única vez (timeout de 10 s). Falhas de entrega são registradas em log, mas não alteram o status do job.
  • Recomenda-se que o endpoint do webhook responda com 2xx em até 10 s. Para processar o resultado de forma assíncrona, enfileire internamente assim que receber a chamada.
curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"print.execute","params":{"templateResourceId":"meu-template"},"callbackUrl":"https://meuservico.com/webhook/jobs"}'

Ações

O campo action deve ser um nome declarado por um módulo. Ações inventadas (ex.: data.query) respondem 400 com code: "UNKNOWN_ACTION" antes de criar o job. NO_AGENT só aparece quando a ação existe e nenhum agente online pode executá-la.

  • data: data.execute, data.testConnection, data.querySyncAll, data.cacheList
  • print: print.execute, print.list, print.status

Para executar uma consulta cadastrada como recurso type: "query", use data.execute com params.queryId igual ao resourceId do recurso. SQL livre no job é recusado (assertNoArbitrarySQL). Parâmetros nomeados da consulta vão em params.params, na ordem de paramOrder do recurso.

curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"data.execute","params":{"queryId":"minha-consulta","params":{"cod":"ABC"},"dateFormat":"date"},"sync":true}'

dateFormat: "date" (também aceito no recurso via PUT /resources) é opt-in no Firebird: colunas DATE voltam como YYYY-MM-DD. Sem a opção, o formato permanece o histórico (timestamp ISO), para não quebrar consumidores existentes. TIMESTAMP não muda.

Campos úteis no objeto de job

  • id, action, params, status
  • priority, timeout, agentId (preenchido após o encaminhamento)
  • Instantes em milissegundos: createdAt, dispatchedAt, startedAt, completedAt
  • result — preenchido quando status é completed; formato depende da ação executada
  • error — em estados de falha, com code, message e opcionalmente details
  • progress, progressMessage — durante a execução, quando o agent reporta andamento

Valores típicos de status: pending, dispatched, running, completed, failed, cancelled, timeout, agent_disconnected.

Recursos

Recursos são itens configuráveis (por exemplo, consultas SQL ou templates) associados à sua conta. A API lista e altera apenas o que o token pode acessar.

GET /resources

Lista recursos permitidos para o token.

Parâmetros de consulta

  • ?type=query ou ?type=template — filtra por tipo. Se o tipo não estiver autorizado para o token, a resposta é 403.

Resposta: { "resources": [ ... ] }.

GET /resources/:resourceId

Obtém um recurso pelo identificador. 404 se não existir; 403 se o tipo não for permitido.

PUT /resources/:resourceId

Cria ou atualiza o recurso com o identificador informado. Resposta { "resource": { ... } }.

Corpo JSON

CampoObrigatórioDescrição
typesimquery ou template, conforme autorizado para o token.
datasimTexto (string) ou objeto JSON (não array).
descriptionnãoDescrição legível.
paramOrdernãoLista ordenada de nomes de parâmetros (strings).
paramsnãoObjeto com metadados dos parâmetros.
targetAgentIdnãoAgente preferencial; omitido grava "*" (igual ao console).
dateFormatnãoSó para query: "date" para serializar colunas Firebird DATE como YYYY-MM-DD em data.execute.

O documento gravado inclui resourceId e id (iguais ao identificador da URL), para aparecer corretamente no console. Recursos antigos sem esses campos: um novo PUT no mesmo id corrige. data permanece string ou objeto como enviado (sem normalização para objeto QueryDefinition).

400 se type ou data forem inválidos; 403 se o tipo não for permitido.

Campos comuns na resposta

  • resourceId, id, type, data, updatedAt, updatedBy, targetAgentId
  • Opcionais: description, paramOrder, params, dateFormat

Erros

As respostas de erro seguem em geral o formato JSON com error e, quando aplicável, message.

HTTPSignificado
400Requisição malformada, campos obrigatórios ausentes, ou ação desconhecida (code: "UNKNOWN_ACTION").
401Autenticação ausente ou inválida.
403Operação não permitida para este token.
404Recurso ou job inexistente, ou não visível com este token.
408Timeout síncrono expirou antes do job terminar. O job continua rodando; consulte GET /jobs/:jobId.
500Erro no processamento da solicitação.

Exemplo

curl -s -X POST "https://api.vectorhub.ramme.dev/api/v1/jobs" \
  -H "Authorization: Bearer <seu-token-de-api>" \
  -H "Content-Type: application/json" \
  -d '{"action":"data.execute","params":{"queryId":"exemplo-consulta"},"sync":true}'

Voltar ao site