DEV Community

Cover image for Como Importar Arquivos HAR para Apidog (Converta Tráfego Capturado em Endpoints)
Lucas
Lucas

Posted on • Originally published at apidog.com

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 na aba Rede (Network). Agora você quer transformar essa chamada em um endpoint documentado, reutilizável, simulável (mock) e testável, sem redigitar URL, cabeçalhos e corpo JSON manualmente.

Experimente o Apidog hoje

Essa lacuna entre “tráfego que posso ver” e “um endpoint que posso reutilizar” é o que um arquivo HAR preenche. O navegador já registra requisições e respostas. Exporte essa gravação, importe-a no Apidog e transforme cada chamada capturada em um endpoint no projeto.

Este guia mostra como:

  1. Capturar um HAR no Chrome DevTools.
  2. Importá-lo com opções que evitam ruído.
  3. Organizar os endpoints gerados.
  4. Reutilizar a captura para documentação, mocks e testes.

Para outros fluxos de captura, consulte o guia sobre ferramentas de captura de pacotes com Apidog.

Você pode baixar o Apidog gratuitamente e acompanhar o processo.

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

HAR significa HTTP Archive. Um arquivo .har é um JSON que registra a interação entre o navegador e um site: requisições, respostas, cabeçalhos, corpos e tempos.

Na prática, um HAR é uma transcrição de uma sessão de navegação. Ele pode incluir:

  • Requisições GET, POST, PUT, DELETE e outros métodos.
  • URLs completas e parâmetros de consulta.
  • Cabeçalhos de autenticação.
  • Corpos JSON enviados e recebidos.
  • Códigos de status e tempos de resposta.

Como o formato é JSON, você pode anexá-lo a um bug report, compartilhá-lo internamente ou importá-lo em ferramentas que entendem HAR.

Ao transformar uma captura em endpoints, você obtém:

  • Um formato de requisição real: URL, query params, cabeçalhos e corpo usados pelo aplicativo.
  • Uma resposta real: status HTTP e payload retornados pelo servidor.
  • Um ponto de partida para documentação: chamadas internas deixam de ser apenas tráfego e passam a ser endpoints nomeados.

Esse fluxo é útil quando você:

  • Herdou um serviço sem uma especificação OpenAPI.
  • Precisa entender como um widget de terceiros conversa com o backend.
  • Quer reproduzir um bug usando a chamada exata que o disparou.
  • Precisa criar rapidamente uma coleção de endpoints a partir de um sistema existente.

Passo 1: capture o HAR nas Ferramentas de Desenvolvedor

A captura ocorre no navegador, não no Apidog. Chrome e Edge usam DevTools semelhantes, portanto o fluxo é praticamente idêntico.

Suponha que você queira capturar as chamadas feitas pela tela de histórico de pedidos.

  1. Abra a página que deseja gravar.
  2. Faça login antes de iniciar a captura caso a API dependa de sessão ou token.
  3. Abra o DevTools:
    • F12
    • Ctrl+Shift+I no Windows/Linux
    • Cmd+Opt+I no macOS
  4. Abra a aba Rede (Network).
  5. Atualize a página ou execute as ações que deseja registrar.
  6. Clique com o botão direito em uma requisição da lista.
  7. Escolha Salvar tudo como HAR com conteúdo.
  8. Salve o arquivo, por exemplo: 
order-history.har
Enter fullscreen mode Exit fullscreen mode

A opção com conteúdo é importante: ela inclui os corpos das respostas. Sem ela, a importação pode ter os formatos das requisições, mas não terá exemplos completos de resposta.

Se quiser revisar o arquivo antes de importar, abra o .har em um editor. Você encontrará um JSON com um array entries. Cada item normalmente inclui objetos request e response.

{
  "log": {
    "entries": [
      {
        "request": {
          "method": "GET",
          "url": "https://api.shop.example.com/v1/orders/123"
        },
        "response": {
          "status": 200
        }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Um HAR também inclui imagens, CSS, JavaScript e outros recursos estáticos carregados pela página. Não é necessário filtrá-los manualmente no navegador: você pode excluí-los durante a importação.

Para mais detalhes sobre a aba Rede, consulte a referência de Rede do Chrome DevTools.

Passo 2: importe o HAR para o Apidog

Com o arquivo salvo, importe-o no projeto:

  1. Abra seu projeto no Apidog.
  2. Vá para Configurações (Settings) > Importar Dados (Import Data) > Manual.
  3. Selecione o formato HAR.
  4. Envie o arquivo .har, como order-history.har.

Antes de confirmar, configure as opções de importação.

Opção 1: tratamento da BaseURL

Cada requisição capturada contém uma URL completa, por exemplo:

https://api.shop.example.com/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

O importador oferece duas estratégias:

  • Hardcode (Fixar): mantém a BaseURL completa em cada endpoint.
  • Remove (Remover — Recomendado): remove o host e mantém apenas o caminho.

Com Remover, o endpoint fica assim:

/v1/orders/123
Enter fullscreen mode Exit fullscreen mode

A BaseURL passa a ser controlada por uma variável de ambiente. Isso permite alternar entre produção, staging e ambiente local sem editar cada endpoint.

Exemplo de variável de ambiente:

baseUrl = https://api.shop.example.com
Enter fullscreen mode Exit fullscreen mode

Depois, você pode usar:

{{baseUrl}}/v1/orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

Escolha Remover na maioria dos casos. Use Fixar apenas quando você realmente precisa manter a URL completa dentro de cada endpoint.

Para entender o uso de ambientes, consulte como a BaseURL pode ser gerenciada globalmente por meio de variáveis de ambiente.

Opção 2: excluir recursos estáticos

Ative Recurso Estático (Static Resource) > Excluir (Exclude).

Isso remove itens como:

  • Imagens.
  • Arquivos CSS.
  • Arquivos JavaScript.
  • Fontes.
  • Outros assets da página.

Sem esse filtro, uma única página pode gerar dezenas de entradas irrelevantes. Com ele, a lista tende a ficar focada nas chamadas da API:

GET /api/orders
GET /api/orders/123
POST /api/orders
Enter fullscreen mode Exit fullscreen mode

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

A opção Geração de Caso de Endpoint (Endpoint Case Generation) cria um caso executável para cada endpoint importado.

Ative essa opção se você pretende testar as chamadas logo após importar. O Apidog cria casos com os valores capturados já preenchidos, reduzindo o trabalho manual.

Deixe desativada se seu objetivo imediato for apenas documentar ou limpar os endpoints primeiro.

Depois de revisar as opções, confirme a importação.

Um endpoint importado pode se parecer com isto:

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

A resposta capturada pode ficar associada ao endpoint como exemplo:

{
  "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"
}
Enter fullscreen mode Exit fullscreen mode

Esse payload pode servir como base para documentação, mock ou asserções de teste.

Passo 3: organize os endpoints gerados

A importação do HAR cria um primeiro rascunho da API. Reserve alguns minutos para transformar as chamadas capturadas em endpoints reutilizáveis.

Elimine o ruído

Mesmo excluindo recursos estáticos, a captura pode conter:

  • Eventos de analytics.
  • Health checks.
  • Telemetria.
  • Chamadas para serviços de terceiros.
  • Endpoints internos que não fazem parte da API que você deseja manter.

Exclua o que não será usado. A árvore de endpoints deve refletir a API que sua equipe realmente mantém ou consome.

Renomeie e agrupe

Um caminho capturado é funcional, mas não necessariamente descritivo.

Em vez de manter:

GET /v1/orders/123
Enter fullscreen mode Exit fullscreen mode

renomeie para algo como:

Obter pedido por ID
Enter fullscreen mode Exit fullscreen mode

Organize os endpoints em pastas por domínio:

Pedidos
├── Listar pedidos
├── Criar pedido
├── Obter pedido por ID
└── Cancelar pedido

Clientes
├── Listar clientes
└── Obter cliente por ID
Enter fullscreen mode Exit fullscreen mode

Converta valores capturados em parâmetros de caminho

Uma captura específica:

GET /v1/orders/123
Enter fullscreen mode Exit fullscreen mode

pode ser importada como um caminho literal. Se 123 representa um ID variável, altere o endpoint para:

GET /v1/orders/{orderId}
Enter fullscreen mode Exit fullscreen mode

Defina o parâmetro:

Nome Local Exemplo
orderId Path 123

Esse ajuste transforma uma chamada única em um endpoint reutilizável para qualquer pedido.

Mova segredos para variáveis de ambiente

HARs podem incluir tokens, cookies e cabeçalhos reais da sessão. Não compartilhe o arquivo sem revisar seu conteúdo.

Por exemplo, substitua:

Authorization: Bearer eyJhbGciOi...
Enter fullscreen mode Exit fullscreen mode

por:

Authorization: Bearer {{accessToken}}
Enter fullscreen mode Exit fullscreen mode

Armazene o valor em uma variável de ambiente:

accessToken = <token-do-ambiente>
Enter fullscreen mode Exit fullscreen mode

Antes de compartilhar o projeto:

  1. Remova tokens e cookies dos exemplos.
  2. Use variáveis de ambiente para credenciais.
  3. Evite anexar HARs em issues públicas.
  4. Revogue tokens expostos acidentalmente.

A documentação do Stripe segue a mesma orientação: chaves de produção não devem aparecer em artefatos compartilhados.

Verifique os corpos de requisição e resposta

Se um endpoint foi importado sem o corpo que você esperava, verifique se o HAR foi exportado usando Salvar tudo como HAR com conteúdo.

Se necessário:

  1. Recapture a sessão.
  2. Exporte novamente com conteúdo.
  3. Reimporte o arquivo.
  4. Compare o endpoint gerado com a captura original.

Depois da limpeza, os endpoints funcionam como qualquer outro endpoint do Apidog: você pode documentá-los, criar mocks e automatizar testes.

Próximos passos úteis:

Variações e limites reais

Ainda não há um gravador automático

O Apidog não atua como um proxy que fica em segundo plano gravando automaticamente o tráfego do navegador.

O fluxo suportado é:

  1. Capturar no DevTools.
  2. Exportar o arquivo HAR.
  3. Importar o HAR no Apidog.
  4. Ajustar os endpoints.
  5. Criar cenários de teste quando necessário.

Ou seja, a captura é manual e a importação é direta. Não espere uma gravação ao vivo dentro do Apidog para esse caso de uso.

A Extensão do Navegador Apidog é uma ferramenta diferente

A Extensão do Navegador Apidog não substitui a exportação HAR do DevTools.

Ela é voltada a executar e depurar requisições no navegador, não a gravar uma sessão de tráfego como HAR.

Além disso, extensões de navegador podem ter restrições impostas pelo próprio navegador, incluindo limitações em cabeçalhos como:

  • Cookie
  • Host
  • Origin
  • Content-Length

Elas também não enviam corpos em requisições GET ou HEAD e não acessam diretamente recursos locais protegidos pela máquina.

Para importar tráfego capturado, use o DevTools e a exportação HAR. Para depuração que exige controle completo de cabeçalhos, use o cliente desktop.

Outros formatos usam a mesma tela de importação

A tela Configurações (Settings) > Importar Dados (Import Data) > Manual também aceita outros formatos, como OpenAPI, Swagger e coleções de ferramentas de API.

Se você já possui uma especificação, prefira importá-la: uma definição OpenAPI costuma gerar resultados mais limpos do que uma captura HAR porque já descreve a API de forma estruturada.

Consulte também:

Use HAR quando não houver uma especificação confiável e o tráfego capturado for o melhor registro disponível.

Automatize o fluxo com a CLI do Apidog

Não é obrigatório importar HARs pela interface gráfica. A CLI do Apidog oferece um comando import para ler um arquivo HAR diretamente.

Isso é útil quando:

  • A captura ocorre em um servidor.
  • Você quer automatizar importações em um pipeline.
  • Um agente de IA gera ou processa capturas.
  • Você precisa repetir o mesmo fluxo em múltiplos projetos.

Instale e autentique a CLI:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

Importe um HAR:

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

A flag --format também aceita formatos como:

openapi
postman
wsdl
insomnia
Enter fullscreen mode Exit fullscreen mode

Depois de criar e salvar um cenário de teste, execute-o sem interface em CI:

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

Nesse comando:

  • -t é o ID do cenário de teste.
  • -e é o ID do ambiente.
  • -r cli seleciona a saída no console.

Use o guia para escrever um cenário de teste no Apidog para montar os testes e o guia de CI/CD da CLI do Apidog para integrá-los ao pipeline.

FAQ

Quais navegadores podem exportar um arquivo HAR?

Navegadores baseados em Chromium, como Chrome e Edge, oferecem esse fluxo pelo DevTools usando a aba Rede (Network) e a opção Salvar tudo como HAR com conteúdo.

Outros navegadores também podem exportar HAR, mas os nomes dos menus podem variar.

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

Provavelmente você importou recursos estáticos junto com as chamadas da API.

Reimporte o arquivo com:

Recurso Estático (Static Resource) > Excluir (Exclude)
Enter fullscreen mode Exit fullscreen mode

Depois, remova manualmente qualquer evento de analytics, health check ou chamada de terceiro que ainda permaneça.

Devo escolher “Hardcode” ou “Remove” para a BaseURL?

Escolha Remover (Remove — Recomendado) na maioria dos casos.

Isso permite usar uma variável de ambiente para alternar a BaseURL:

Produção: https://api.example.com
Staging: https://staging-api.example.com
Local: http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Assim, o mesmo endpoint pode ser executado em diferentes ambientes sem editar o caminho.

A mesma configuração é usada quando você executa cenários de teste no Apidog.

O HAR inclui meus tokens de autenticação?

Sim. Um HAR registra cabeçalhos e cookies enviados durante a sessão, incluindo bearer tokens e credenciais ativas.

Trate o arquivo como um segredo:

  • Não publique o HAR.
  • Não envie-o para issues públicas.
  • Mova tokens para variáveis de ambiente após importar.
  • Limpe credenciais de exemplos compartilhados.

Posso importar um HAR pela linha de comando?

Sim. Use:

apidog import --project <id> --format har --file <path>
Enter fullscreen mode Exit fullscreen mode

A CLI é especialmente útil para importações automatizadas, capturas feitas em servidores ou fluxos de CI.

A interface gráfica continua sendo útil quando você quer ajustar interativamente opções como tratamento da BaseURL e exclusão de recursos estáticos.

Depois da importação, use apidog run para executar os cenários de teste criados a partir desses endpoints.

Concluindo

Um arquivo HAR conecta o tráfego que você observa aos endpoints que pode reutilizar.

O fluxo é direto:

  1. Capture a sessão no DevTools.
  2. Exporte com Salvar tudo como HAR com conteúdo.
  3. Importe em Configurações (Settings) > Importar Dados (Import Data) > Manual.
  4. Use Remover (Remove) para a BaseURL.
  5. Defina Recurso Estático (Static Resource) como Excluir (Exclude).
  6. Renomeie endpoints, converta IDs em parâmetros e remova segredos.

O resultado é uma coleção de endpoints reais que você pode documentar, simular e testar.

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

Top comments (0)