Upload grande

Tipo

Como fazer

Para

Desenvolvedor

A API guarda arquivos do Tenant por dois caminhos. O envio multipart (POST /tenant/files/upload) aceita até 200 MiB num pedido só. Acima disso, até 2 GB, o arquivo vai por URL pré-assinada: você pede a URL à API, manda os bytes direto ao armazenamento e confirma. As outras operações de arquivo (listar, tornar público, gerar link, excluir) estão no grupo Arquivos do menu.

Antes de começar

O Tenant Token do Tenant onde o arquivo vai ficar.

Qual caminho usar

	Multipart	URL pré-assinada
Tamanho máximo	200 MiB	2 GB
Pedidos	1	3 (pedir URL, PUT, confirmar)
Os bytes passam pela API	Sim	Não
origin do arquivo	api	hec
Mesmo nome de novo	Substitui o conteúdo, mesmo id	Cria outro arquivo

Acima de 200 MiB, o multipart responde 413 com o texto File size limit has been reached, sem JSON.

Enviar até 200 MiB

curl -X POST "https://api.horusbi.com.br/v1/tenant/files/upload" \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -F "file=@vendas-setembro.csv" \
  -F "filename=vendas-setembro.csv"

O campo do arquivo precisa se chamar file. A resposta traz id e url. O arquivo entra privado.

Enviar até 2 GB

1. Peça a URL de envio. O mime que você manda aqui é o Content-Type que o PUT vai ter de usar:

   curl -X POST "https://api.horusbi.com.br/v1/tenant/files/presign" \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"file_name": "vendas-2026.parquet", "mime": "application/vnd.apache.parquet"}'

   A resposta traz id e uploadUrl. A URL vale 15 minutos.

2. Mande o arquivo com PUT na uploadUrl, com o mesmo Content-Type:

   curl -X PUT "$UPLOAD_URL" \
     -H "Content-Type: application/vnd.apache.parquet" \
     --upload-file vendas-2026.parquet

   Esse pedido vai direto ao armazenamento e não leva o Tenant Token.

3. Confirme o envio com o id do passo 1:

   curl -X POST "https://api.horusbi.com.br/v1/tenant/files/confirm" \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "mime": "application/vnd.apache.parquet"}'

   A API lê o tamanho real no armazenamento e devolve os dados do arquivo, com file_size e url. O arquivo entra privado.

Até a confirmação, o arquivo não aparece em GET /tenant/files. O que não for confirmado em 24 horas é apagado.

O mesmo fluxo em Node.js:

import { readFile } from "node:fs/promises";

const BASE = "https://api.horusbi.com.br/v1/tenant";
const auth = { Authorization: `Bearer ${process.env.TENANT_TOKEN}`, "Content-Type": "application/json" };
const mime = "application/vnd.apache.parquet";

const presign = await fetch(`${BASE}/files/presign`, {
  method: "POST",
  headers: auth,
  body: JSON.stringify({ file_name: "vendas-2026.parquet", mime }),
}).then((r) => r.json());
const { id, uploadUrl } = presign.data;

const put = await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": mime },
  body: await readFile("./vendas-2026.parquet"),
});
if (!put.ok) throw new Error(`PUT falhou: ${put.status}`);

const confirm = await fetch(`${BASE}/files/confirm`, {
  method: "POST",
  headers: auth,
  body: JSON.stringify({ id, mime }),
}).then((r) => r.json());
console.log(confirm.data.url);

Abrir o arquivo depois

O arquivo entra privado: a url só abre com um link assinado. Gere o link com POST /tenant/files/{id}/sign, com a validade em segundos (ttl, de 60 a 604800; sem ele, 1 hora). Para a url abrir sem token, torne o arquivo público com PATCH /tenant/files/{id} e {"public": true}.

Excluir (DELETE /tenant/files/{id}) tira o arquivo da lista na hora. O conteúdo é apagado do armazenamento 7 dias depois, sem como restaurar pela API.

Se der errado

Sintoma	Causa	Conserto
413 File size limit has been reached no multipart	Arquivo acima de 200 MiB	Use a URL pré-assinada
PUT responde 403	Content-Type diferente do mime do passo 1, ou URL vencida	Repita o passo 1 e use o mesmo valor nos dois
Confirmação responde Arquivo não encontrado no storage (upload não concluído)	O PUT não terminou ou falhou	Refaça o PUT e confirme de novo
Confirmação responde Arquivo excede o limite de ~2 GB por arquivo (FILE_TOO_LARGE)	Arquivo acima de 2 GB	Divida o arquivo

Relacionado

• API: tokens, erros e limite de pedidos.
• HorusETL: ler um arquivo guardado num Dataflow.