Enviar arquivos para uma API: multipart ou Base64 e como evitar uploads corrompidos

O endpoint determina como o arquivo é enviado

Enviar um arquivo para uma API consiste em incluir seu conteúdo em uma solicitação HTTP que o servidor consiga interpretar. Não existe um formato universal que sirva para todos os endpoints: um pode esperar um envio multipart/form-data, outro um objeto JSON com conteúdo codificado e outro um mecanismo diferente, descrito em seu contrato. A extensão do arquivo ou o fato de uma solicitação usar POST não bastam para decidir qual estrutura enviar. A primeira tarefa é identificar a operação específica e seguir o que ela declara.

Separar a representação do arquivo da lógica de negócios ajuda a diagnosticar problemas. A representação determina como os bytes e os campos são transmitidos; o endpoint determina quais campos exige, quais tipos aceita e que resposta produz. Se for enviado um corpo válido para outra operação, o servidor poderá rejeitá-lo ou processá-lo de forma inesperada. Antes de escrever o código, anote o método, a rota, a autenticação, o tipo de conteúdo, os campos obrigatórios, os limites documentados e as respostas de erro.

• Não deduza o formato aceito pelo nome da rota nem por uma integração de outro provedor.
• Use os exemplos de solicitação como orientação, mas confirme se correspondem à mesma versão e operação.

Multipart/form-data e Base64 em JSON

Com multipart/form-data, o corpo é dividido em partes separadas. Cada parte tem seus próprios cabeçalhos e conteúdo, portanto uma solicitação pode combinar o arquivo com campos adicionais, se o endpoint permitir. O cliente cria a separação entre as partes; por isso, ao usar uma biblioteca HTTP, normalmente é melhor deixar que ela gere o cabeçalho Content-Type completo e seu delimitador. Defini-lo manualmente sem manter o delimitador correspondente ao corpo é uma causa frequente de solicitações que o servidor não consegue analisar.

Com Base64, os bytes do arquivo são codificados como texto e esse texto é incluído em um documento JSON, em uma propriedade definida pelo contrato. Não presuma o nome da propriedade, se é exigido um prefixo de tipo de mídia ou se o endpoint aceita Base64: essas decisões dependem do esquema. Antes de escolher essa representação, confira também os limites e requisitos documentados para a operação.

• Multipart é adequado quando o contrato descreve partes de formulário e uma parte de arquivo.
• Base64 só é uma opção se o endpoint declarar essa representação; o fato de o corpo ser JSON não é suficiente.

Inspecione o OpenAPI sem fazer suposições

Consulte a especificação OpenAPI disponível e localize a operação exata pela rota e pelo método. Verifique o tipo de conteúdo aceito pelo corpo da solicitação, o esquema associado e as propriedades obrigatórias. Para multipart, confirme como o arquivo é declarado e quais são os nomes das partes; para JSON, procure a estrutura e o tipo de dado indicados para cada campo. Como referência sobre essa orientação, a documentação da Frends, “How to Accept File Uploads & Multipart data to an API”, explica que a aceitação de uploads de arquivos e dados multipart deve ser especificada na OpenAPI: https://docs.frends.com/guides/development/how-to-accept-file-uploads-and-multipart-data-to-an-api.

Leia também as respostas documentadas, os requisitos de autenticação e quaisquer limites ou restrições associados à operação. Um exemplo não documenta necessariamente todos os casos válidos, e a falta de informações não significa que seja permitido enviar arquivos arbitrários. Se o esquema estiver ausente, o tipo de conteúdo não estiver claro ou as instruções forem contraditórias, peça confirmação à pessoa responsável pela API antes de programar. Registre a versão do contrato usada para implementar e testar.

• Confirme: método, rota, Content-Type, esquema do corpo, campos obrigatórios e respostas possíveis.
• Não deduza limites, permissões, formatos aceitos ou armazenamento a partir de uma descrição geral do produto.

Exemplos genéricos e erros comuns

Os exemplos a seguir são ilustrativos: não descrevem uma operação específica da Apification. Em um envio multipart, uma chamada genérica com curl poderia ser `curl -X POST "https://api.exemplo.test/rota" -F "arquivo=@./exemplo.pdf"`. Substitua a URL e o nome de campo pelos valores exatos do contrato. Ao usar `-F`, deixe o curl montar o cabeçalho multipart e o delimitador correspondente ao corpo.

Para ilustrar o formato JSON com Base64, o texto `Olá` codificado em UTF-8 pode aparecer assim: `{"arquivo_base64":"T2zDoQ=="}`. O nome `arquivo_base64` é apenas um exemplo; use a propriedade indicada pelo esquema e confirme que a operação aceita essa representação. A integração da Apification inclui REST API e OpenAPI, mas as informações disponíveis aqui não especificam qual operação aceita arquivos nem qual esquema utiliza.

Verifique se o arquivo abre corretamente antes de enviá-lo e se o programa não está lendo um caminho errado, um arquivo vazio ou uma versão parcial. Não confunda o nome ou a extensão com o tipo MIME: eles podem não corresponder, e o valor a ser transmitido depende do contrato. Evite truncar o Base64 ao registrar solicitações ou transportar JSON entre componentes. Confira também os limites documentados, pois uma rejeição pode ocorrer antes de o endpoint processar o corpo.

• Erros comuns: nome de campo incorreto, JSON malformado, delimitador multipart ausente, conteúdo Base64 truncado e tipo MIME não aceito.
• Não registre o conteúdo completo do arquivo nos logs; registre os metadados necessários para diagnosticar o problema sem expor o documento.

Verifique de ponta a ponta se não houve corrupção

Uma resposta HTTP bem-sucedida, por si só, não prova que o conteúdo recebido corresponde ao arquivo de origem. Crie um teste com um arquivo representativo e, depois, obtenha o objeto recebido usando o mecanismo documentado pela API. Se não houver uma forma documentada de recuperá-lo, confirme qual verificação o serviço oferece; não presuma que a resposta contenha o arquivo nem que exista uma operação de download. Mantenha o original de teste sem alterações e registre seu tamanho e, se o fluxo permitir, um valor de hash calculado localmente.

Compare o arquivo recuperado com o original por meio de uma comparação binária ou calculando o mesmo valor de hash para ambos. Faça testes com tipos e tamanhos pertinentes à integração, incluindo arquivos próximos do limite documentado. Confira também o código de resposta, o corpo do erro e os logs seguros do cliente. Se os resultados forem diferentes, investigue os pontos do fluxo: leitura local, codificação, transporte, processamento do servidor ou download posterior.

• Teste um arquivo binário e um com conteúdo textual; inclua nomes com espaços ou caracteres não ASCII se o contrato permitir.
• Teste situações acima dos limites somente em um ambiente controlado e confirme se a rejeição é clara e não deixa um objeto parcial.

Lista de verificação antes da integração

Antes de implantar, transforme o contrato em uma lista de verificação: operação e versão corretas, tipo de conteúdo declarado, campos e nomes exatos, autenticação necessária, limites conhecidos e forma de interpretar as respostas. Implemente a solicitação com uma biblioteca que gerencie multipart corretamente ou com uma serialização JSON confiável. Defina o que acontecerá em caso de erros de rede, rejeição por tamanho, credenciais inválidas ou resposta malformada. Repetir automaticamente um envio nem sempre é inofensivo: determine se o endpoint permite repeti-lo sem criar duplicatas ou resultados ambíguos.

Conclua a revisão com controles operacionais. Limite o acesso ao arquivo de origem conforme as necessidades da integração, evite incluir credenciais ou conteúdo confidencial nos logs e elimine arquivos temporários quando não forem mais necessários. Documente como reproduzir um envio com falha usando um arquivo de teste e como validar o recebimento. A Apification oferece integração com o Cloud e seus serviços por meio de REST API, OpenAPI, webhooks, iframe e JavaScript; os detalhes de envio, permissões e recursos de cada endpoint devem ser confirmados na documentação aplicável, e não extrapolados dessa capacidade geral.

• Contrato revisado e versionado.
• Representação e limites confirmados para o endpoint específico.
• Testes de integridade, erros e tentativas repetidas concluídos.
• Acesso, logs e arquivos temporários revisados.

Perguntas frequentes