Como Importar Arquivos HAR para Apidog (Converta Tráfego Capturado em Endpoints)

Você viu um aplicativo fazer uma requisição no navegador. Funcionou. Os dados estão ali na aba Rede (Network). Agora você quer essa mesma chamada como um endpoint documentado que pode salvar, simular (mock) e testar, sem precisar digitar novamente a URL, os cabeçalhos e o corpo JSON manualmente.

Essa lacuna entre "tráfego que posso ver" e "um endpoint que posso reutilizar" é o que um arquivo HAR preenche. Seu navegador já registra cada requisição e resposta que ele faz. Exporte essa gravação, entregue-a ao Apidog, e cada chamada capturada se torna um endpoint real em seu projeto. Este guia percorre todo o caminho: capture um HAR no Chrome DevTools, importe-o com as opções corretas e organize os endpoints gerados para que a lista permaneça útil. Para uma visão mais ampla dos fluxos de trabalho de captura, nosso guia sobre ferramentas de captura de pacotes com Apidog aborda o terreno adjacente.

Você pode baixar o Apidog gratuitamente e acompanhar as mesmas telas.

O que é um arquivo HAR e por que vale a pena manter o tráfego capturado

HAR significa HTTP Archive. De acordo com a documentação do Apidog, um arquivo .har é "um arquivo em formato JSON usado para registrar a interação de um navegador da web com um site. Ele registra requisições da web, respostas, cabeçalhos e outros dados enviados entre o navegador e o servidor."

Simplificando: um arquivo HAR é uma transcrição completa de uma sessão de navegação. Cada GET, cada POST, os cabeçalhos das requisições, os corpos das respostas, o tempo. Por ser JSON, ele é facilmente transportável. Você pode enviá-lo por e-mail, anexá-lo a um relatório de bug ou fornecê-lo a uma ferramenta que saiba lê-lo.

Essa última parte é o motivo pelo qual isso importa aqui. Uma sessão capturada é um registro de como uma API realmente se comporta na prática, não como uma especificação diz que deveria. Quando você transforma esse registro em endpoints, você ganha algumas coisas de graça:

Um formato de requisição real. A URL exata, parâmetros de consulta (query params), cabeçalhos e corpo que o aplicativo enviou, não uma suposição.
Uma resposta real. O código de status e o payload que o servidor retornou, que você pode usar como um mock ou uma asserção de teste.
Um ponto de partida para a documentação. Uma API interna não documentada se torna um conjunto de endpoints nomeados que você pode anotar.

Isso é útil quando você herda um serviço sem uma especificação OpenAPI, quando você está fazendo engenharia reversa de como um widget de terceiros se comunica com seu backend, ou quando você quer reproduzir um bug com a chamada exata que o desencadeou.

Passo 1: capture o HAR nas Ferramentas de Desenvolvedor do seu navegador

A captura acontece no seu navegador, não no Apidog. Chrome e Edge usam as mesmas Ferramentas de Desenvolvedor (DevTools), então os passos são idênticos. Digamos que você queira capturar o tráfego por trás de uma página de histórico de pedidos.

Abra a página que você deseja gravar. Faça login primeiro se a API precisar de uma sessão, pois o HAR também incluirá essas requisições.
Abra as Ferramentas de Desenvolvedor. Pressione F12, ou Ctrl+Shift+I no Windows e Linux, ou Cmd+Opt+I no Mac.
Vá para a aba Rede (Network). É aqui que o DevTools lista todas as requisições que a página faz.
Atualize a página, ou clique nas ações cujo tráfego você deseja capturar. Carregar a visualização do histórico de pedidos dispara as chamadas para /api/orders, /api/orders/{id} e o que mais a página precisar. Cada uma delas aparece como uma linha.
Clique com o botão direito em qualquer linha de requisição e escolha Salvar tudo como HAR com conteúdo. Escolha um local e salve o arquivo, por exemplo order-history.har. Se a terminologia do menu o confundir, a referência de Rede do Chrome DevTools documenta o mesmo fluxo de captura e exportação.

Essa parte "com conteúdo" é importante. Ela diz ao DevTools para incluir os corpos das respostas, não apenas os metadados da requisição. Sem eles, seus endpoints importados teriam formatos de requisição, mas nenhuma resposta de exemplo.

Uma rápida verificação antes de sair do navegador: se você abrir o arquivo .har em um editor de texto, ele é um JSON legível. Você verá um array entries onde cada entrada tem um objeto request e um objeto response. Essa é a estrutura que o Apidog lê.

Algo a ter em mente. O carregamento de uma página carrega mais do que apenas chamadas de API. Ele também busca imagens, folhas de estilo e scripts, e cada um deles vai parar no HAR. Você não precisa filtrá-los no navegador; o Apidog oferece uma opção para descartá-los na importação, conforme abordado a seguir.

Passo 2: importe o HAR para o Apidog

Com o arquivo salvo, vá para o Apidog. O importador fica em um só lugar.

Abra seu projeto e vá para Configurações (Settings) > Importar Dados (Import Data) > Manual.
Selecione HAR como o formato.
Faça upload do seu arquivo .har, por exemplo, o order-history.har que você salvou há pouco.

Antes de confirmar, o Apidog mostra três opções de importação. Elas determinam o quão limpo será o resultado, então vale a pena entender cada uma em vez de apenas prosseguir.

Opção 1: como a BaseURL é tratada

Toda requisição capturada tem uma URL completa, algo como https://api.shop.example.com/v1/orders/123. Você tem duas opções para o que fazer com a parte do host:

Hardcode (Fixar) mantém a BaseURL dentro do caminho de cada endpoint. Cada endpoint carrega o prefixo completo https://api.shop.example.com.
Remove (Remover - Recomendado) remove a BaseURL para que o caminho do endpoint se torne /v1/orders/123. O host é então gerenciado globalmente por meio de variáveis de ambiente.

Escolha a opção Remover (Remove), a menos que você tenha um motivo para não fazê-lo. É a configuração recomendada por uma razão: quando a URL base reside em uma variável de ambiente, você pode apontar os mesmos endpoints para produção, staging ou um servidor local simplesmente trocando os ambientes, sem nenhuma edição nos próprios endpoints. A fixação (hardcoding) bloqueia cada endpoint ao host do qual você o capturou, o que se torna problemático no momento em que você precisa testar contra um servidor diferente.

Opção 2: excluindo recursos estáticos

Esta é a opção que evita uma lista de endpoints desordenada. A opção Recurso Estático (Static Resource), configurada para Excluir (Exclude), diz ao Apidog para ignorar as imagens, CSS e arquivos JavaScript capturados. Um único carregamento de página pode produzir dezenas desses, e nenhum deles são endpoints de API que você deseja documentar.

Ative a opção Excluir (Exclude) para quase todas as importações. O que sobra após o filtro é o tráfego real da API: as chamadas JSON para /api/orders e semelhantes, não a requisição para logo.png.

Opção 3: gerando um caso de teste por endpoint

A terceira opção é Geração de Caso de Endpoint (Endpoint Case Generation). Ative-a (ON) e o Apidog criará um caso de teste padrão para cada endpoint à medida que o importa. Um caso de teste é uma invocação salva e executável do endpoint com os valores capturados já preenchidos.

Este é um pequeno passo que compensa mais tarde. Se o seu objetivo é testar esses endpoints, ter um caso pronto por endpoint significa que você pode executar um imediatamente em vez de construí-lo do zero. Se você só quer documentação por enquanto, pode deixá-lo desativado e adicionar os casos mais tarde.

Confirme a importação. O Apidog lê o HAR, aplica suas opções e converte as interações capturadas do navegador em endpoints de API dentro do seu projeto. Abra a árvore de endpoints e você os verá agrupados e prontos.

Aqui está, aproximadamente, como um endpoint importado se parece depois de ser adicionado, usando a chamada de pedido como exemplo:

GET /v1/orders/123
Host: api.shop.example.com
Authorization: Bearer <token-from-capture>
Accept: application/json

E a resposta capturada que o Apidog armazena junto com ele:

{
  "id": 123,
  "status": "shipped",
  "total": 48.5,
  "currency": "USD",
  "items": [
    { "sku": "TSHIRT-BLK-M", "qty": 2, "price": 19.25 }
  ],
  "createdAt": "2026-07-14T09:31:00Z"
}

Essa resposta são dados reais que o servidor retornou, o que a torna uma base sólida para um mock ou uma asserção de teste.

Passo 3: organize os endpoints gerados

A importação de um HAR é um primeiro rascunho rápido, não uma definição de API finalizada. O tráfego capturado é inerentemente desorganizado, então reserve alguns minutos para arrumar o resultado.

Elimine o ruído. Mesmo com Recurso Estático (Static Resource) definido para Excluir (Exclude), você pode encontrar pings de análise, verificações de saúde ou chamadas de terceiros que não lhe interessam. Exclua os endpoints que você não usará para que a árvore reflita sua API real.
Renomeie e agrupe. Os endpoints capturados são nomeados de acordo com seus caminhos, o que é funcional, mas genérico. Dê a eles nomes claros ("Obter pedido por ID" em vez de /v1/orders/123) e organize-os em pastas que correspondam à estrutura da sua API.
Corrija os parâmetros de caminho (path parameters). Uma captura de /v1/orders/123 importa como um caminho literal. Se 123 for realmente um ID de pedido, edite o endpoint para que esse segmento se torne um parâmetro de caminho {orderId}. Essa única mudança transforma uma chamada capturada em um endpoint reutilizável que funciona para qualquer pedido.
Limpe segredos antes de compartilhar. Este é fácil de esquecer. Seu HAR capturou qualquer token de autenticação que estivesse ativo naquela sessão, e ele foi junto para os cabeçalhos. Antes de enviar o projeto ou compartilhá-lo com colegas de equipe, mova os tokens para variáveis de ambiente e limpe as credenciais capturadas dos exemplos. A documentação do Stripe faz a mesma observação sobre nunca permitir que chaves de produção vazem para artefatos compartilhados, e um HAR é exatamente o tipo de artefato que as vaza.
Verifique os corpos (bodies). Se um corpo estiver vazio onde você esperava dados, você provavelmente exportou sem "com conteúdo". Recapture usando Salvar tudo como HAR com conteúdo e importe novamente.

Depois que os endpoints estiverem limpos, eles se comportam como qualquer outro endpoint no Apidog. Você pode documentá-los, gerar um mock a partir de cada resposta e construir testes. O guia para escrever um cenário de teste no Apidog continua naturalmente a partir daqui, e se você quiser código cliente tipado desses endpoints, consulte como gerar código cliente com Apidog.

Variações e limites reais

Algumas situações ocorrem com frequência suficiente para serem destacadas.

Ainda não há um gravador automático

Você pode esperar que o Apidog funcione em segundo plano e grave o tráfego ao vivo, como um proxy faria. Ele não faz isso, e vale a pena ser direto sobre isso. A documentação afirma claramente: "Atualmente, o Apidog não oferece suporte à função de gravação automática de endpoints, mas há planos para suportá-la no futuro."

Então, o caminho suportado hoje é exatamente o que está neste guia: capture com as Ferramentas de Desenvolvedor do seu navegador, exporte o HAR e importe-o. O fluxo recomendado que a documentação descreve é abrir o DevTools enquanto você exercita um endpoint no navegador, exportar o HAR quando terminar, importá-lo para o Apidog com um clique, e então criar um cenário de teste e importar todas as requisições para reprodução. É uma etapa de captura manual seguida por uma importação de um clique, não um gravador ao vivo. Quando o recurso de gravação automática for lançado, esta seção mudará, mas não espere por ele.

A Extensão do Navegador Apidog é uma ferramenta diferente

Existe uma Extensão do Navegador Apidog, e é fácil presumir que ela captura o tráfego HAR. Não é o caso. A extensão permite que você use as ferramentas de teste e depuração de API do Apidog diretamente no navegador sem abrir o cliente desktop. É para executar requisições, não para gravá-las.

A captura de HAR vem das próprias Ferramentas de Desenvolvedor do seu navegador, ponto final. Se você usar a extensão para testes, saiba que o navegador impõe limites a ela: ele bloqueia certos cabeçalhos como Cookie, Host, Origin e Content-Length, não enviará corpos em requisições GET ou HEAD, e não pode acessar código local ou um banco de dados por trás de sua máquina. Para capturar tráfego para importação, use o DevTools e a exportação HAR. Para depuração mais pesada que requer controle total dos cabeçalhos, o Cliente Desktop Apidog não tem tais limites impostos pelo navegador.

Outros formatos são importados da mesma forma

HAR é um dos vários formatos que a mesma tela Configurações (Settings) > Importar Dados (Import Data) > Manual aceita. Se você já tem um arquivo OpenAPI ou Swagger, importá-lo oferece um resultado mais limpo do que uma captura, porque uma especificação é estruturada propositalmente. Nosso tutorial sobre migrar a documentação da API Swagger para o Apidog aborda essa rota, e se você vem do Postman, o guia de migração de ambientes e coleções do Postman também o faz. Recorra ao HAR quando uma especificação real não existe e o tráfego capturado é o melhor registro que você tem.

Automatize o fluxo de trabalho com a CLI do Apidog

Importar um HAR não precisa ser uma etapa da interface gráfica (GUI). A CLI do Apidog possui um comando import que lê um arquivo HAR diretamente, o que é ideal quando a captura acontece em um servidor, quando você automatiza a importação em um pipeline, ou quando você deixa um agente de codificação de IA transformar uma captura em endpoints:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

# Transforme um HAR capturado em endpoints no seu projeto
apidog import --project <PROJECT_ID> --format har --file ./capture.har

A flag --format também aceita openapi, postman, wsdl, insomnia e outros, então um único comando cobre a maioria das fontes de importação. Uma vez que os endpoints existam e você os tenha salvo em um cenário de teste, execute esse cenário sem interface (headless) em CI:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t <SCENARIO_ID> -e <ENV_ID> -r cli

Aqui, -t é o ID do cenário de teste salvo, -e é o ID do ambiente (as mesmas variáveis de ambiente que contêm sua BaseURL), e -r seleciona o relatório, cli para saída no console. Construa o cenário com o guia para escrever um cenário de teste no Apidog, então conecte ambos os comandos ao seu pipeline com o guia de CI/CD da CLI do Apidog.

FAQ

Quais navegadores podem exportar um arquivo HAR?

Qualquer navegador baseado em Chromium com DevTools faz isso da mesma forma, então Chrome e Edge usam a aba Rede (Network) e o item de menu Salvar tudo como HAR com conteúdo. A documentação do Apidog aborda especificamente o caminho do Chrome e Edge. Outros navegadores têm seus próprios menus de exportação, mas o rótulo pode diferir, então adapte-se à terminologia das Ferramentas de Desenvolvedor do seu navegador.

Minha lista de endpoints importados está enorme. O que deu errado?

Você provavelmente deixou a opção Recurso Estático (Static Resource) configurada para incluir tudo. O carregamento de uma página carrega imagens, CSS e scripts, e todos eles vão parar no HAR. Reimporte o arquivo com a opção Recurso Estático (Static Resource) definida como Excluir (Exclude), e a lista se restringirá às chamadas de API reais. Você também pode excluir os itens restantes manualmente depois.

Devo escolher "Hardcode" ou "Remove" para a BaseURL?

Escolha Remover (Remove - Recomendado) em quase todos os casos. Isso retira o host de cada caminho de endpoint para que você o gerencie globalmente por meio de uma variável de ambiente, o que permite alternar entre produção, staging e local sem editar os endpoints. Essa mesma configuração é o que um cenário de teste no Apidog lê quando é executado. Escolha Fixar (Hardcode) apenas quando você especificamente quiser a URL completa inserida em cada caminho.

O HAR inclui meus tokens de autenticação?

Sim, e esse é o ponto crucial. Um HAR registra os cabeçalhos reais enviados durante a sessão, então qualquer token de portador (bearer token) ou cookie que estivesse ativo estará no arquivo. Trate um HAR como um segredo: não o cole em um problema público e, após a importação, mova as credenciais para variáveis de ambiente e limpe-as dos exemplos salvos antes de compartilhar o projeto.

Posso pular a interface gráfica (GUI) e importar um HAR pela linha de comando?

Sim. O comando apidog import --project <id> --format har --file <path> da CLI do Apidog importa um HAR para seu projeto sem abrir o aplicativo, o que é o ideal quando a captura ocorre em um servidor ou dentro de um trabalho de CI. A GUI ainda oferece as opções interativas de importação (tratamento de BaseURL, filtragem de Recurso Estático) para uma captura única, então escolha o que for mais adequado: a CLI para importações roteirizadas ou orientadas por agente, a GUI quando você quiser ajustar a importação manualmente. Após a importação, apidog run reproduz os cenários de teste que você constrói a partir desses endpoints.

Concluindo

Um arquivo HAR é a ponte entre o tráfego que você pode ver e os endpoints que você pode reutilizar. Capture a sessão nas Ferramentas de Desenvolvedor do seu navegador com Salvar tudo como HAR com conteúdo, importe-o através de Configurações (Settings) > Importar Dados (Import Data) > Manual com Remover (Remove) para a BaseURL e Recurso Estático (Static Resource) configurado para Excluir (Exclude), então gaste alguns minutos renomeando, parametrizando e limpando segredos. O que você obtém é um conjunto de endpoints funcionando que você pode documentar, simular (mock) e testar.

Pronto para transformar sua próxima captura em endpoints reais? Baixe o Apidog e experimente gratuitamente, sem necessidade de cartão de crédito.