🌐 यह पृष्ठ अभी तक हिंदी में अनुवादित नहीं किया गया है। पुर्तगाली (BR) संदर्भ दिखाया जा रहा है। अनुवाद में मदद करें।
Roqueman API Client
O Roqueman é o cliente de API do RoqueOS, um Postman/Insomnia que roda dentro do seu desktop web. Monte e dispare requisições HTTP, WebSocket e GraphQL, organize tudo em coleções, use variáveis e ambientes, escreva scripts de teste, e automatize fluxos com encadeamento de respostas e o runner de coleção, sem instalar nada.
Por que isso é útil
Você testa suas APIs no mesmo lugar onde já trabalha, com os dados sincronizados na sua conta. Sem app separado, sem login extra, abre o Roqueman pelo Launchpad e começa.
Admins: coleção do servidor automática
Administradores conectados a um servidor recebem a coleção RoqueOS Server (todos os endpoints da API do servidor) carregada automaticamente, junto com um ambiente apontando pro servidor ativo, pronta pra rodar.
Fazendo a primeira requisição, em quatro passos
- Abra o Roqueman e clique em Nova Requisição.
- Escolha o método e cole a URL na barra do topo. Se você copiou um comando cURL (o "Copiar como cURL" do navegador, por exemplo), cole o comando inteiro: método, URL, cabeçalhos, corpo e usuário/senha entram de uma vez.
- Preencha cabeçalhos e corpo nas abas logo abaixo, se a chamada precisar.
- Clique em enviar, ou aperte Ctrl+Enter (Cmd+Enter no Mac). A resposta abre ao lado, com status, tempo, cabeçalhos e corpo. Ctrl+S salva a requisição.
Se a requisição falhar antes de ter resposta, a área da resposta mostra o motivo no lugar dela, com uma dica do que fazer quando houver uma. A resposta anterior sai da tela, para você não confundir um 200 antigo com o resultado da tentativa que falhou. Um 404 ou um 500 não é falha: é a resposta do servidor, e aparece como resposta.
Quando a requisição não vai
| O que acontece | Por quê | O que fazer |
|---|---|---|
Failed to fetch num endereço que funciona no navegador | o alvo não libera CORS para o RoqueOS | use o modo que roda pelo servidor, que não passa pelo CORS do navegador |
Connection refused num endereço da sua rede | o RoqueOS está no navegador e não enxerga a sua LAN | rode pelo servidor, se ele estiver na mesma rede do alvo |
A variável sai literal, como | nenhum ambiente está selecionado, ou a variável não existe nele | escolha o ambiente no seletor e confira o nome |
| O Runner para no meio da coleção | uma requisição falhou e a seguinte dependia dela | veja o histórico: ele mostra em qual passo parou |
| 401 com a mesma chave que funciona no curl | a chave ficou num ambiente diferente do selecionado | ambientes não se misturam; confira qual está ativo |
Modos de execução
Toda requisição roda em um de três modos (seletor ao lado da URL), pra contornar CORS conforme o cenário:
- Navegador (Axios): dispara direto do navegador. Ideal para APIs públicas com CORS liberado. É o modo necessário para upload de arquivo (o navegador monta o
multipart/boundary). Quando dá erro de rede neste modo, o Roqueman avisa que o motivo mais provável é CORS. - Servidor (Proxy): encaminha pelo seu RoqueOS Server (requer Server Mode conectado). Resolve CORS server-side. Com um servidor conectado, toda aba nova já sai por ele.
- Função (Proxy): encaminha por uma Cloud Function do RoqueOS. É o padrão quando nenhum servidor está conectado, e resolve CORS sem precisar de servidor próprio.
Toda requisição tem timeout (30s por padrão): um endpoint lento não trava mais o app, você recebe um aviso de tempo esgotado, distinto de um cancelamento manual.
Montando uma requisição
- Método + URL: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.
- Params: tabela chave/valor da query string, com liga/desliga por linha. A tabela e a URL andam juntas: digitar
?page=2na URL cria a linha, e editar a linha reescreve a URL. Um parâmetro nunca vai duplicado. - Headers: tabela chave/valor.
- Body:
- JSON / XML / Text: editor com realce de sintaxe.
- Form (urlencoded): tabela chave/valor.
- Multipart (form-data): cada linha alterna entre texto e arquivo (com seletor de arquivo). Upload de arquivo real requer o modo Navegador.
- Binary: envia um arquivo cru com o content-type dele.
- Auth: Nenhuma, Bearer, Basic, API Key (no cabeçalho ou na query), OAuth 2.0 e Digest.
- Scripts: pré-requisição e pós-resposta, com a API
pmdo Postman:pm.test,pm.expect(comto.be.an,to.have.property,to.include,to.have.lengthOfe o resto do estilo Chai),pm.response.to.have.status(200),pm.environment.setepm.globals.set. O que o script grava comsetfica salvo no ambiente ativo ou nas globais, pronto para a próxima requisição. Oconsole.logdos scripts aparece na aba Console da resposta.
Os scripts rodam isolados num quadro sem acesso à sua sessão do RoqueOS: um script colado de outro lugar não enxerga seus dados nem sua conta.
OAuth 2.0, obter token automaticamente
Na aba Auth → OAuth 2.0 → Configurações Avançadas, preencha a URL do Token, Client ID/Secret e Scope e clique em Obter token. O Roqueman busca o token via client credentials (pelo modo de execução da aba, então o proxy resolve o CORS) e preenche o Access Token automaticamente.
Variáveis e ambientes
Use em qualquer campo (URL, headers, params, body, auth). A resolução segue a ordem: globais → variáveis da coleção → ambiente ativo → runtime (scripts). Há também variáveis dinâmicas como , , , etc.
Antes de enviar, o Roqueman avisa (de forma não-bloqueante) se alguma não foi encontrada, assim um não vai silenciosamente como string vazia.
Gerencie ambientes pelo seletor no topo (engrenagem), crie, edite, duplique, importe/exporte e troque o ambiente ativo.
Encadeamento response → variável
Na aba Extrair, defina regras para salvar valores da resposta em variáveis para a próxima requisição, sem escrever script:
- De: Body (caminho JSON, ex.:
data.token), Header (nome) ou Status. - Variável de destino + Escopo (Environment ou Global).
Depois de cada resposta com sucesso, o valor é extraído e salvo (toast "Variáveis salvas"). É o que permite, por exemplo, fazer login e usar o token retornado nas requisições seguintes automaticamente.
Coleções e o Runner
Organize requisições em coleções com pastas aninhadas. Salve, duplique, mova, importe (Postman v2.1, cURL, OpenAPI 3, Swagger 2, RoqueOS, ou documentação escrita, com a IA) e exporte (Postman v2.1 e RoqueOS).
No menu de contexto da coleção, Rodar coleção abre o runner: ele executa todas as requisições em sequência (raiz e pastas), roda os scripts de teste e mostra o resultado ao vivo por requisição (status, tempo, testes ✓/✕) e um resumo de aprovados/reprovados. O encadeamento response→variável funciona dentro do runner, então fluxos com dependência entre requisições rodam de ponta a ponta.
Resposta
O visualizador mostra status, tempo e tamanho, e abas de Body (com realce e modo bruto), Headers, Cookies, Testes (com a contagem de aprovados, como 3/4, no rótulo da aba) e Console (o que os scripts escreveram, e o erro do script quando houver). Você pode copiar, baixar e gerar código da requisição em 9 linguagens (cURL, Fetch, Axios, Python, PHP, Go, Java, C#, Ruby).
WebSocket e GraphQL
Use o botão + (ao lado das abas) para criar uma aba WebSocket ou GraphQL:
- WebSocket: conecte, envie texto/JSON e veja o log de mensagens. Com Reconectar automaticamente ligado (padrão), uma queda inesperada dispara reconexão com backoff exponencial, uma desconexão manual não reconecta.
- GraphQL: editor de query + variáveis + introspection do schema.
Abas e histórico
- Abas multi-requisição com estado "não salvo"; as abas abertas e o rascunho sobrevivem ao reload (não se perde trabalho ao recarregar).
- Fechar uma aba com alteração não salva pergunta antes, pelo X, pela tecla Delete ou pelo menu da aba. O que já está salvo na coleção não muda.
- Histórico das requisições enviadas, agrupado por data, com busca e replay.
No celular
O Roqueman funciona na tela pequena: a barra lateral de coleções vira uma gaveta pelo botão de menu, e o layout acompanha o tamanho da janela quando você redimensiona ou gira o aparelho.
A barra da requisição cabe em duas linhas: método e URL em cima; modo de execução, IA, salvar e enviar embaixo.
A janela de exportar também cabe em telas estreitas, então dá para tirar uma coleção no formato Postman ou RoqueOS direto do celular.
A IA do RoqueOS no Roqueman
O Roqueman usa os agentes que você salvou no Estúdio de IA, inclusive um modelo local. Precisa de Modo Servidor ativo e de pelo menos um agente.
Nenhum valor de credencial vai para o modelo. Antes de qualquer pergunta, o Roqueman troca por ‹oculto› o valor de todo cabeçalho, parâmetro ou campo de JSON com nome de credencial (Authorization, Cookie, token, password, api_key, secret e parecidos). O agente vê que o campo existe, não o que tem nele.
Entender uma resposta ou uma falha
Com uma resposta na tela, o botão ✨ (ao lado de copiar, baixar e gerar código) abre o painel de IA com a requisição, a resposta, os testes e o console. A ação Diagnosticar diz o que aconteceu, a causa mais provável e o que mudar na requisição: um 422 que não diz o que faltou, um 401 com a chave certa no lugar errado, um CORS no modo Browser.
Quando a requisição falha antes de ter resposta, o botão Explicar com IA aparece no lugar dela e já pergunta o diagnóstico. O Roqueman não reescreve a resposta do servidor: a explicação fica no painel.
Descrever a requisição
Descrever com IA (na tela inicial, ou o ✨ ao lado de salvar na barra de URL) recebe uma frase, como "criar um usuário na API do GitHub com nome e e-mail", e preenche método, URL, cabeçalhos e corpo na aba aberta. Credenciais entram como variável (), nunca inventadas, e as variáveis que você já tem são reaproveitadas.
Gerar testes
Na aba Scripts, Gerar testes com IA lê a requisição e a resposta na tela e escreve testes pm.test no script pós-resposta, com o que você já tinha escrito preservado em cima. Dá para dizer o foco, como "conferir que todo item tem id e preço". Os testes rodam no próximo envio e aparecem na aba Testes.
Coleção a partir de uma especificação ou documentação
Em Importar → OpenAPI / doc, cole (ou abra) uma especificação OpenAPI 3 ou Swagger 2 em JSON: a coleção sai na hora e sem IA, com uma pasta por tag, o endereço do servidor, os parâmetros obrigatórios ligados e os opcionais desligados, um corpo de exemplo tirado do schema e a autenticação declarada virando variável.
Se o que você colou é YAML, uma página de documentação ou texto solto, o botão Montar coleção com IA entrega o texto ao agente e mostra a prévia do que saiu antes de importar. Endpoint que a documentação não descreve não entra.
FAQ
O upload de arquivo não funciona. Troque o modo de execução para Navegador (Axios), só ele monta o multipart/form-data real. O proxy de servidor/função não encaminha upload de arquivo.
Onde meus dados ficam salvos? Coleções, requisições, ambientes, globais e histórico ficam na sua conta (Firebase), sincronizados entre dispositivos. As abas abertas ficam no navegador local.
Variáveis de ambiente são secretas? São armazenadas como texto na sua conta. Não coloque segredos de produção sensíveis em ambientes compartilhados.
Deu "tempo esgotado". A requisição passou de 30s. Verifique o endpoint, a rede ou o modo de execução.