Guias

Comece a usar a API do Nubbo

Do zero ao seu primeiro pedido em poucos minutos. Crie uma chave e comece a gerir o seu armazenamento a partir do seu próprio código.

A API do Nubbo é uma API REST para trabalhar com os seus buckets a partir do seu próprio código: ficheiros, pastas, links, pedidos de ficheiros, galerias, etiquetas, projetos e automatizações. Neste guia cria uma chave e faz os seus primeiros pedidos com curl.

O que consegue

  • Gerir o seu espaço do Nubbo a partir dos seus programas, com chaves que só veem o que escolher.
  • Carregar e transferir ficheiros diretamente entre o seu código e o seu fornecedor de armazenamento.
  • Reagir a ficheiros novos, carregamentos em pedidos de ficheiros e atividade com os acionadores.

Antes de começar

Precisa de uma conta do Nubbo com o plano Pro ou Equipas e de um terminal com curl. Numa equipa, as chaves de API são criadas pelo proprietário ou por um administrador.

Passo 1: crie uma chave

  1. No Nubbo, abra Definições › API (ou Equipa › API numa equipa) e prima Criar chave de API.

  2. Dê-lhe um nome e escolha:

    • Acesso: Só de leitura ou Leitura e escrita.
    • Alcance: Todo o espaço ou Buckets e projetos escolhidos. A chave só vê o que escolher aqui.
    • Expiração: 30 dias, 90 dias, 1 ano ou Sem expiração. O Nubbo avisa-o 7 dias antes.

    Prima Criar chave. O Nubbo pede a sua palavra-passe para confirmar que é você. Se tiver a verificação em dois passos ativada, também pede o código.

    Janela Criar chave de API com o acesso, o alcance e a expiração Janela Criar chave de API com o acesso, o alcance e a expiração
  3. Copie a chave e prima Já a guardei. Começa por nbk_ e é a única vez que a verá completa. Guarde-a no servidor ou na ferramenta que a vai usar, nunca numa página web.

    Janela A sua chave de API com a chave pronta a copiar Janela A sua chave de API com a chave pronta a copiar

Passo 2: o seu primeiro pedido

Envie a chave no cabeçalho Authorization de cada pedido. Comece por GET /v1/me, que não gasta pedidos:

curl https://api.nubbo.app/v1/me \
  -H "Authorization: Bearer nbk_a_sua_chave"

A resposta traz o seu espaço, o seu plano, a quota do mês e a chave com o respetivo acesso e alcance. Este é um excerto:

{
  "workspace": { "id": "…", "name": "Estúdio Norte", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "A minha primeira chave",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Depois, liste os seus buckets e os ficheiros de uma pasta:

curl https://api.nubbo.app/v1/buckets \
  -H "Authorization: Bearer nbk_a_sua_chave"

curl "https://api.nubbo.app/v1/buckets/<bucketId>/files?prefix=faturas/" \
  -H "Authorization: Bearer nbk_a_sua_chave"

As listas devolvem data e nextCursor. Para a página seguinte, envie esse valor em cursor. Quando nextCursor é null, não há mais.

Terminal com o pedido GET /v1/me e a respetiva resposta Terminal com o pedido GET /v1/me e a respetiva resposta

Passo 3: a referência

Em Definições › API, prima Ver documentação, ou abra api.nubbo.app/v1/docs. Aí está cada recurso com os seus campos e exemplos. O documento OpenAPI está em api.nubbo.app/v1/openapi.json.

Referência da API do Nubbo com o exemplo em curl Referência da API do Nubbo com o exemplo em curl

Carregamentos e transferências

Os ficheiros não passam pelo Nubbo. Para carregar um, peça o carregamento com POST /v1/buckets/{bucketId}/uploads, envie o ficheiro para o endereço pré-assinado que recebe e termine com POST /v1/uploads/{uploadId}/complete. Para transferir, peça um link com POST /v1/files/{fileId}/download-link e transfira o ficheiro a partir do seu fornecedor.

Limites

ProEquipas
Pedidos por minuto por chave60120
Pedidos por mês50.000100.000 + 10.000 por lugar
Eventos de acionadores por mês20.00050.000 + 5.000 por lugar

A quota é do espaço e renova-se a cada período de faturação. GET /v1/me, as consultas dos acionadores e as respostas 401, 429 e 5xx não contam como pedidos. Cada evento entregue por um acionador conta como evento. Cada resposta traz os cabeçalhos X-RateLimit-Remaining e X-Nubbo-Quota-Requests-Remaining, e em Definições › API vê a utilização do período.

Utilização da API no período nas definições do Nubbo Utilização da API no período nas definições do Nubbo

Se algo falhar

  • API_KEY_INVALID, API_KEY_REVOKED ou API_KEY_EXPIRED: a chave não é válida, foi revogada ou expirou. Verifique o cabeçalho ou crie outra chave.
  • API_PLAN_REQUIRED: o espaço da chave não tem a API. Está nos planos Pro e Equipas.
  • API_KEY_READ_ONLY: a chave é só de leitura. Crie uma com Leitura e escrita.
  • API_RATE_LIMITED: demasiados pedidos com esta chave. Aguarde os segundos de Retry-After e volte a tentar.
  • API_QUOTA_EXCEEDED: o espaço usou o limite do mês. details.resetsAt indica quando se renova.

Cada erro traz um requestId. Inclua-o se nos escrever.

Saiba mais sobre a API do Nubbo. Para a usar sem escrever código, siga o guia do Zapier, o do n8n ou o do Make. Para a usar a partir do seu assistente de IA, veja como ligar o Nubbo ao Claude, ChatGPT ou Cursor.

Perguntas frequentes

Que planos incluem a API?

Pro e Equipas. Com Grátis ou Personal, os pedidos respondem API_PLAN_REQUIRED.

Posso ler ficheiros encriptados com a API?

Não. O conteúdo encriptado aparece sem nome, caminho, tamanho nem tipo e qualquer alteração sobre ele é rejeitada com API_ENCRYPTED_CONTENT.

O que acontece se repetir um pedido por uma falha de rede?

Envie o cabeçalho Idempotency-Key nos seus POST e PATCH. Durante 24 horas, repetir o mesmo pedido devolve a primeira resposta e não cria nada duas vezes.

A API vai mudar sem aviso?

Não. Uma alteração que quebre algo chega como /v2 e a /v1 mantém-se pelo menos 12 meses, com os cabeçalhos Deprecation e Sunset.

Fontes

Passos verificados com estas páginas.