Integra a API da NUBEN para guardar e servir ficheiros (fotos, vídeos, documentos) a partir do meu código. A NUBEN guarda cada ficheiro sem compressão e devolve-o exactamente igual ao que recebeu.

Base: https://nuben.ferreirakorp.com/api
Autenticação: header  Authorization: Bearer nbn_...
A chave cria-se (e revoga-se) no painel: https://nuben.ferreirakorp.com/painel
Nunca ponhas a chave no cliente/browser — usa-a no servidor.

Espaço: 10 GB grátis por conta, partilhados entre a aplicação e a API. Depois escolhe-se um plano (100 GB ou 1 TB) que vale para os dois.

Endpoints:
- POST /v1/ficheiros            enviar um ficheiro
    Header: Authorization: Bearer nbn_...
    Header: x-nuben-nome:  nome-do-ficheiro.ext   (opcional)
    Header: x-nuben-pasta: NomeDaPasta            (opcional, default "API")
    Corpo:  os BYTES do ficheiro (application/octet-stream). Máximo 512 MB por ficheiro.
    Resposta: { ok, ficheiro:{ id, nome, tipo, pasta, bytes, url }, usado_bytes, limite_bytes }

- GET  /v1/ficheiros            listar os ficheiros da conta   (?pasta=NomeDaPasta opcional)
    Resposta: { ok, total, usado_bytes, limite_bytes, ficheiros:[ { id, nome, tipo, pasta, bytes, criado_em, url } ] }

- GET  /v1/ficheiros/:id        descarregar um ficheiro        (?t=original  ou  ?t=melhor)

- DELETE /v1/ficheiros/:id      apagar um ficheiro

- GET  /v1/uso                  espaço usado, limite e chamadas da chave
    Resposta: { ok, usado_bytes, limite_bytes, resta_bytes, ficheiros, plano, chave:{ id, nome, chamadas } }

Erros (JSON com "ok":false e "erro"):
- 401  chave em falta ou inválida/revogada
- 402  sem espaço  (o corpo traz usado_bytes, limite_bytes e o link para escolher um plano)
- 413  ficheiro maior do que 512 MB

Regra de ouro: trata sempre o campo "ok" da resposta; nunca confies só no código HTTP.

Exemplo (cURL) — enviar um ficheiro:
  curl -X POST https://nuben.ferreirakorp.com/api/v1/ficheiros \
    -H "Authorization: Bearer nbn_A_TUA_CHAVE" \
    -H "x-nuben-nome: recibo.pdf" \
    --data-binary @recibo.pdf

Exemplo (JavaScript no servidor) — enviar bytes:
  const bytes = await fs.promises.readFile("recibo.pdf");
  const r = await fetch("https://nuben.ferreirakorp.com/api/v1/ficheiros", {
    method: "POST",
    headers: { "Authorization": "Bearer nbn_A_TUA_CHAVE", "x-nuben-nome": "recibo.pdf" },
    body: bytes,
  });
  const j = await r.json();
  if (j.ok) console.log("guardado:", j.ficheiro.url);