Você construiu um endpoint que aceita um arquivo. Um usuário faz upload de uma foto de perfil para POST /avatars, ou seu aplicativo envia um PDF assinado para POST /documents. A rota funciona na sua cabeça. Agora você precisa provar que ela funciona via HTTP: escolha um arquivo real, anexe-o a um campo de formulário, envie a requisição e verifique a resposta.
É aqui que muitas ferramentas de API ficam complicadas. Uploads de arquivos usam multipart/form-data, não JSON, então você não pode simplesmente colar um corpo e clicar em enviar. Você precisa de um construtor de requisições que entenda campos de arquivo, e um executor de testes que possa encontrar o arquivo quando o teste for executado mais tarde. O Apidog lida com ambos, e este guia percorre todo o caminho: enviando um único upload, enviando um arquivo junto com JSON, validando a resposta, e então a parte honesta sobre a qual ninguém avisa, que é o que acontece quando essa mesma etapa de upload é executada sem interface gráfica no Runner ou CLI e não consegue encontrar o arquivo. Se você quiser primeiro o contexto sobre o formato em si, o guia upload de arquivos em APIs aborda como as requisições multipart são estruturadas. A referência MDN sobre FormData é um bom complemento para o lado do navegador.
O que é multipart/form-data e por que os uploads precisam dele
Um corpo de requisição de API pode assumir várias formas. Na seção Corpo da requisição do Apidog, você pode escolher form-data, x-www-form-urlencoded, JSON, XML, raw ou binário. Na maioria das vezes, você opta por JSON. Uploads de arquivos são a exceção.
O tipo de corpo form-data mapeia para o cabeçalho Content-Type: multipart/form-data. É o formato construído para fazer upload de arquivos junto com outros dados. Em vez de um único bloco de dados (blob), o corpo é dividido em partes, cada uma com seu próprio nome e conteúdo. Uma parte pode ser uma string simples, como uma legenda, outra parte pode ser os bytes brutos de uma imagem. É por isso que um upload de foto e seus metadados podem viajar na mesma requisição.
O parente próximo é x-www-form-urlencoded. Ele parece similar no editor, pares chave-valor enviados no corpo, mas é destinado a formulários simples sem arquivos. Se seu endpoint aceita um arquivo, form-data é o que você quer. Use x-www-form-urlencoded apenas quando cada campo for um escalar curto e nenhum byte estiver envolvido.
Em form-data, o Apidog mostra cada parâmetro como um par chave-valor, e cada parâmetro possui um tipo: string, inteiro, arquivo e assim por diante. Esse tipo por parâmetro é todo o segredo. Defina um campo como file e o Apidog tratará seu valor como um arquivo a ser anexado, em vez de texto a ser enviado.
Enviar um único upload de arquivo e validar a resposta
Digamos que você esteja testando POST /avatars. Ele recebe um campo, avatar, contendo uma imagem, e retorna JSON com a URL armazenada. Aqui está o passo a passo.
1. Abra a seção Corpo e escolha form-data. No seu endpoint ou em uma nova requisição, defina o método como POST e a URL para a rota de avatares. Abra a aba Corpo e selecione o tipo de corpo form-data. O Apidog define Content-Type: multipart/form-data para você.
2. Adicione o parâmetro de arquivo e defina seu tipo como file. Adicione um parâmetro com a chave avatar. Ao lado da chave, use o seletor de tipo para mudar seu tipo de string para file. A célula de valor se transforma em um seletor de arquivos em vez de uma caixa de texto.
3. Clique em Upload e escolha um arquivo local. Clique em Upload na linha avatar e escolha uma imagem da sua máquina, por exemplo jane-profile.png. O Apidog registra o caminho para esse arquivo.
4. Envie a requisição. Clique em Enviar. O Apidog lê o arquivo do caminho local armazenado, constrói o corpo multipart e o envia. Importante saber de antemão: o Apidog envia o arquivo na requisição, mas não o armazena na nuvem. Ele salva apenas o caminho local, não os bytes. Esse detalhe importa mais tarde, então guarde essa informação.
Uma chamada bem-sucedida retorna algo assim:
{
"id": "usr_8842",
"avatarUrl": "https://cdn.example.com/avatars/usr_8842.png",
"sizeBytes": 48210,
"contentType": "image/png"
}
5. Valide a resposta. Um envio que retorna 200 não é um teste aprovado por si só. Adicione validações para que a verificação seja real. No Apidog, você as adiciona como validações pós-requisição no endpoint ou na etapa do cenário. Em termos simples, você quer confirmar o status e que o corpo carrega uma URL utilizável:
status code == 200
$.avatarUrl exists
$.contentType == "image/png"
Essas validações mapeiam diretamente para a interface de usuário de validação do Apidog: uma validação no código de status, uma na presença de $.avatarUrl via JSONPath, uma em $.contentType. Se você é novo em validações, o guia de validações de API mostra o conjunto completo de operadores e como o JSONPath segmenta um campo.
Para uma verificação rápida fora da ferramenta, o mesmo upload no curl se parece com isto:
curl -X POST https://api.example.com/avatars \
-F "avatar=@jane-profile.png"
A flag -F é a maneira do curl de construir uma parte multipart, e @ indica que ele deve ler o conteúdo do arquivo. O parâmetro de arquivo form-data do Apidog faz a mesma coisa com um seletor em vez de uma flag.
Enviar um arquivo e JSON juntos
Endpoints reais raramente aceitam um arquivo puro. POST /documents pode querer o arquivo mais metadados: um título, uma categoria, talvez um array de tags. Você tem duas maneiras claras de fazer isso em uma única requisição multipart.
O caso simples são os campos escalares. Adicione mais parâmetros form-data ao lado do seu campo de arquivo e os deixe como string ou integer. Uma string title, uma string category, um file definido como tipo file. Todos os três viajam na mesma requisição.
Quando os metadados são estruturados, como um objeto aninhado ou um array, você os envia como JSON dentro de uma parte de string. Adicione um parâmetro form-data chamado metadata, mantenha seu tipo como string e cole o JSON diretamente no valor:
{
"title": "Q3 Invoice",
"category": "billing",
"tags": ["invoice", "2026", "paid"]
}
Então, a requisição tem duas partes: file (tipo file) contendo q3-invoice.pdf, e metadata (tipo string) contendo aquele JSON. O servidor lê o arquivo de uma parte e analisa o JSON da outra. Muitas APIs públicas aceitam uploads exatamente dessa forma; a documentação de upload de arquivos do Stripe é um bom exemplo de um endpoint multipart real que emparelha uma parte de arquivo com campos simples. Este padrão é comum o suficiente para que usuários do Postman também o encontrem; se você estiver migrando, o passo a passo sobre como fazer upload de um arquivo e dados JSON no Postman se aplica de forma limpa aos campos form-data do Apidog.
Precisa anexar mais de um arquivo? Adicione outro parâmetro com o tipo file. Um POST /documents que aceita um arquivo principal e uma miniatura recebe duas linhas de arquivo, file e thumbnail, cada uma com seu próprio botão Upload. Não há um modo especial para múltiplos arquivos; você apenas adiciona parâmetros do tipo arquivo até cobrir todas as partes que o endpoint espera.
Transforme a requisição em um cenário de teste repetível
Um único envio prova que o endpoint funciona uma vez. Para detectar regressões, você quer o upload dentro de um cenário de teste salvo que seja executado sob demanda ou em uma programação. Encadeie as etapas: faça upload do avatar, capture o id retornado, então chame GET /users/{id} e valide que a URL do avatar persistiu.
Construa isso da mesma forma que você construiu a requisição única, então salve-a como uma etapa em um cenário. O guia como escrever um cenário de teste com Apidog aborda o encadeamento de etapas e a passagem de valores entre elas. Uma vez que o upload esteja em um cenário, você pode executá-lo contra o ambiente de staging a cada deploy, adicionar ramificações condicionais com lógica condicional em cenários de teste de API, ou colocá-lo em um cronômetro com testes de API agendados.
Tudo o que foi dito acima funciona bem na sua máquina, porque sua máquina tem o arquivo. Essa suposição é exatamente o que quebra a seguir.
A pegadinha: uploads que rodam em outro lugar
Aqui está a parte que o caminho feliz esconde. O Apidog armazena o caminho do arquivo, não o arquivo em si. No seu laptop, isso é invisível, porque o caminho sempre aponta para um arquivo real. No momento em que a mesma etapa é executada em uma máquina diferente, o caminho não aponta para nada.
Você encontrará isso em dois lugares.
Colaboração em equipe. Quando um colega de equipe abre sua requisição POST /avatars, ele vê o parâmetro do arquivo e o caminho que você escolheu, digamos /Users/jane/pics/jane-profile.png. Ele pode ver a requisição, mas não pode enviá-la, porque esse arquivo está no seu disco, não no dele. O caminho é local à máquina que o escolheu.
Execuções no Runner e CLI. Este é o que causa problemas na automação. Seu cenário de upload passa localmente, você o agenda no Runner ou o executa a partir da CLI, e a etapa de upload de arquivo falha. Não há nada de errado com suas validações. O runner simplesmente não consegue encontrar um arquivo no caminho que seu laptop salvou, porque esse caminho não existe no host do runner.
A solução decorre da causa. O arquivo precisa existir na máquina que está realizando o envio, e o caminho da etapa precisa apontar para ele lá.
Para o Runner: o Runner lê arquivos de um diretório do host montado em seu volume. Você configura essa montagem ao implantar o Runner, usando a flag -v. Copie seu arquivo de upload para esse diretório do host montado. Em seguida, abra os detalhes da etapa de upload de arquivo no cenário, clique no botão Batch Edit no canto superior direito e substitua o valor do campo de arquivo pelo caminho dentro do diretório do Runner, por exemplo:
/opt/runner/jane-profile.png
Para a CLI: mesma forma. Coloque o arquivo na máquina da CLI, então use Batch Edit na etapa para apontar o caminho para sua localização lá, por exemplo:
/opt/apidog/runner/jane-profile.png
Mais limpo do que codificar manualmente: use uma variável. Em vez de fixar um caminho literal na etapa, substitua o valor por uma variável e defina o valor da variável para o caminho real do arquivo por ambiente. Assim, o mesmo cenário é executado no seu laptop, no Runner e na CI sem precisar editar a etapa a cada vez. Você aponta a variável para /Users/jane/pics/jane-profile.png localmente e para /opt/runner/jane-profile.png no runner, e a etapa em si nunca muda.
Um pré-requisito que vale a pena deixar claro: o Runner só acessa arquivos do host que estão dentro do diretório que você montou com -v no momento da implantação. Se seu arquivo não estiver sob essa montagem, nenhum caminho o encontrará. Esse é um detalhe de configuração de implantação, não um limite do plano. A documentação do Apidog sobre requisições de upload de arquivos detalha as etapas de montagem e edição em massa, caso você queira a versão canônica.
Automatize o fluxo de trabalho com a CLI do Apidog
Uma vez que seu cenário de upload esteja salvo, você pode executá-lo sem interface gráfica na CI. Instale a CLI e autentique-se:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Então execute o cenário salvo por id, apontando-o para um ambiente:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Aqui -t é o ID do cenário de teste, -e é o ID do ambiente, e -r é o reporter (use cli, html ou junit, separados por vírgula para vários). A CLI executa seus cenários salvos do projeto na nuvem e relata aprovação/falha com códigos de saída, o que permite que ela controle um pipeline. Os detalhes de configuração estão no guia de instalação da CLI do Apidog.
Uma ressalva honesta, e é a mesma da seção anterior: um cenário com uma etapa de upload de arquivo precisa que o arquivo esteja presente na máquina da CLI, e o caminho da etapa precisa apontar para ele lá. Coloque o arquivo no runner, então use Batch Edit no caminho (ou uma variável) antes da execução. Pular isso fará com que a etapa de upload falhe ao encontrar o arquivo, mesmo que o restante do cenário esteja correto. Para uma configuração de CI mais completa, incluindo a passagem de entradas por linha, consulte testes orientados a dados com a CLI do Apidog.
FAQ
Por que meu colega de equipe não consegue enviar minha requisição de upload de arquivo? O Apidog armazena o caminho local do arquivo, não o arquivo em si, e nunca faz upload do arquivo para a nuvem. Seu colega de equipe vê a requisição e o caminho que você escolheu, mas esse caminho aponta para um arquivo no seu disco, não no dele. Peça a ele para colocar uma cópia do arquivo na máquina dele e apontar o campo para o próprio caminho. O mesmo mecanismo explica por que testes agendados e trabalhos do Runner precisam que o arquivo esteja preparado onde são executados.
Como envio JSON junto com um arquivo na mesma requisição? Mantenha o tipo de corpo como form-data. Adicione seu campo de arquivo com o tipo file, então adicione outro parâmetro com o tipo string e cole o JSON em seu valor. O servidor recebe ambas as partes em uma requisição multipart: o arquivo em uma parte, a string JSON em outra. Esta é a maneira padrão de anexar metadados a um upload.
Que caminho devo usar para um arquivo no Runner? Use um caminho dentro do diretório do host que você montou no volume do Runner com a flag -v no momento da implantação, por exemplo /opt/runner/seuarquivo.jpg. Copie o arquivo para esse diretório montado, então abra a etapa, clique em Batch Edit e defina o valor do campo para esse caminho. O equivalente na CLI se parece com /opt/apidog/runner/seuarquivo.jpg.
Existe um limite de tamanho de arquivo ou uma lista de tipos de arquivo permitidos? O comportamento de upload no Apidog refere-se a como a requisição é construída e de onde o arquivo é lido. Seus limites reais de tamanho e tipo vêm da API que você está testando, então verifique as próprias regras de validação do seu servidor e escreva validações contra as respostas que ele retorna para arquivos muito grandes ou rejeitados.
Devo usar form-data ou x-www-form-urlencoded para uploads? Use form-data. Ele mapeia para multipart/form-data e é construído para transportar arquivos. x-www-form-urlencoded é para formulários simples com campos escalares curtos e sem arquivos, então ele não transportará sua imagem ou PDF.
Conclusão
O teste de upload de arquivos se resume a duas coisas: construir a requisição multipart corretamente e garantir que o arquivo esteja acessível onde quer que o teste seja executado. No Apidog, você define o Corpo como form-data, muda o tipo do seu campo para file, clica em Upload, adiciona qualquer JSON como uma parte de string, então envia e valida. Quando você move o mesmo cenário para o Runner ou CLI, prepare o arquivo nessa máquina e reponte o caminho com Batch Edit ou uma variável, e a execução automatizada se comportará como a sua local.
Quer experimentar em seu próprio endpoint? Baixe o Apidog, aponte uma requisição form-data para sua rota de upload e observe a resposta retornar. É gratuito para começar, sem necessidade de cartão de crédito.