- Enriquecimento: envio de bases para processamento em massa.
- Armazenamento: envio de arquivos para organização no espaço de storage da conta.
O upload não deve ser feito enviando arquivos diretamente para endpoints comuns da API. O fluxo recomendado usa uma assinatura temporária de upload.
Fluxo geral
O fluxo de upload é dividido em etapas para manter segurança, controle de tamanho e rastreabilidade.Solicite a assinatura de upload
A aplicação informa o destino do upload, nome do arquivo, tamanho e tipo de conteúdo.
Envie o arquivo para a URL assinada
Use a URL temporária retornada para enviar o arquivo diretamente ao storage.
Quando usar upload
| Caso | Uso recomendado |
|---|---|
| Enviar planilha para enriquecimento | Use o fluxo de upload para enriquecimento. |
| Salvar arquivo na conta | Use o fluxo de upload para armazenamento. |
| Enviar imagem para comparação facial | Não use o fluxo de upload; envie a imagem em Base64 no endpoint de validação facial. |
| Enviar documento pequeno como parâmetro de uma consulta | Use o corpo da requisição quando o endpoint documentado aceitar esse formato. |
Segurança
As URLs assinadas são temporárias e devem ser usadas apenas para o arquivo informado na solicitação. Boas práticas:- Gere uma assinatura por arquivo.
- Não reutilize URLs assinadas.
- Não exponha a URL assinada em logs públicos.
- Valide tamanho e tipo do arquivo antes de solicitar a assinatura.
- Envie o arquivo logo após obter a assinatura.
- Trate expiração da assinatura solicitando uma nova URL.
Limites
| Item | Regra |
|---|---|
| Tamanho máximo por arquivo | Até 1024 MB quando o destino permitir. |
| Quantidade de arquivos | Depende do recurso usado e dos limites da conta. |
| Espaço disponível | Para armazenamento, o upload respeita o limite de storage da conta. |
| Tipos aceitos | Variam conforme o destino: enriquecimento ou armazenamento. |
Enriquecimento
Use upload para enriquecimento quando precisar enviar uma base que será processada em massa. Normalmente esse fluxo envolve:- Enviar o arquivo de entrada.
- Criar ou configurar o enriquecimento.
- Mapear colunas, datasets e opções de processamento.
- Acompanhar execução.
- Baixar o arquivo final quando estiver concluído.
Upload para enriquecimento
Veja formatos aceitos, regras de arquivo e como o upload se conecta ao fluxo de enriquecimento.
Armazenamento
Use upload para armazenamento quando quiser salvar arquivos no espaço da conta. Normalmente esse fluxo envolve:- Selecionar a pasta de destino.
- Solicitar a assinatura de upload.
- Enviar o arquivo.
- Registrar ou confirmar o arquivo no storage.
- Listar, renomear, baixar ou apagar o arquivo posteriormente.
Upload para armazenamento
Veja como enviar arquivos para pastas e manter os dados organizados no armazenamento da conta.
Metadados comuns
Ao solicitar uma assinatura de upload, normalmente serão necessários metadados como:| Campo | Descrição |
|---|---|
filename | Nome original do arquivo. |
content_type | Tipo MIME do arquivo, como text/csv ou application/pdf. |
size | Tamanho do arquivo em bytes. |
target | Destino do upload, como enriquecimento ou armazenamento. |
path_id | Pasta de destino, quando o upload for para armazenamento. |
Os campos exatos podem variar conforme o endpoint específico de enriquecimento ou armazenamento.
Respostas e erros
Uploads podem falhar por motivos como:| Motivo | Exemplo |
|---|---|
| Arquivo grande demais | O tamanho informado ultrapassa o limite permitido. |
| Tipo não permitido | O formato não é aceito para o destino escolhido. |
| Assinatura expirada | A URL temporária expirou antes do envio. |
| Storage insuficiente | A conta não possui espaço disponível para armazenar o arquivo. |
| Permissão ausente | A credencial da API não possui escopo para o recurso. |
Códigos de erro
Consulte os erros específicos relacionados a upload de arquivos.
Boas práticas
- Calcule o tamanho do arquivo antes de solicitar a assinatura.
- Use o
content_typereal do arquivo. - Para enriquecimento, valide cabeçalhos e colunas antes do envio.
- Para armazenamento, confirme se a pasta de destino existe.
- Não tente enviar novamente para uma URL assinada expirada.
- Se o upload falhar no envio para o storage, solicite uma nova assinatura.
- Mantenha o identificador retornado pelo fluxo para vincular o arquivo ao recurso correto.