Guías

Comeza coa API de Nubbo

De cero á túa primeira petición nuns minutos. Crea unha clave e empeza a xestionar o teu almacenamento desde o teu propio código.

A API de Nubbo é unha API REST para traballar cos teus buckets desde o teu propio código: ficheiros, cartafoles, ligazóns, buzóns, galerías, etiquetas, proxectos e automatizacións. Nesta guía creas unha clave e fas as túas primeiras peticións con curl.

Que consegues

  • Xestionar o teu espazo de Nubbo desde os teus programas, con claves que só ven o que ti escolles.
  • Subir e descargar directamente entre o teu código e o teu provedor de almacenamento.
  • Reaccionar a ficheiros novos, subidas a buzóns e actividade cos disparadores.

Antes de comezar

Necesitas unha conta de Nubbo co plan Pro ou Equipos e un terminal con curl. Nun equipo, as claves de API créanas o propietario ou un administrador.

Paso 1: crea unha clave

  1. En Nubbo, abre Configuración › API (ou Equipo › API nun equipo) e preme Crear clave de API.

  2. Ponlle un nome e escolle:

    • Acceso: Só lectura ou Lectura e escritura.
    • Alcance: Todo o espazo ou Buckets e proxectos escollidos. A clave só ve o que escollas aquí.
    • Caducidade: 30 días, 90 días, 1 ano ou Sen caducidade. Nubbo avísache 7 días antes.

    Preme Crear clave. Nubbo pídeche o teu contrasinal para confirmar que es ti. Se tes a verificación en dous pasos, tamén che pide o código.

    Xanela Crear clave de API co acceso, o alcance e a caducidade Xanela Crear clave de API co acceso, o alcance e a caducidade
  3. Copia a clave e preme Xa a gardei. Comeza por nbk_ e é a única vez que a verás enteira. Gárdaa no servidor ou na ferramenta que a vaia usar, nunca nunha páxina web.

    Xanela A túa clave de API coa clave lista para copiar Xanela A túa clave de API coa clave lista para copiar

Paso 2: a túa primeira petición

Envía a clave na cabeceira Authorization de cada petición. Comeza por GET /v1/me, que non gasta peticións:

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

A resposta trae o teu espazo, o teu plan, a cota do mes e a clave co seu acceso e o seu alcance. Este é un extracto:

{
  "workspace": { "id": "…", "name": "Estudo Norte", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "A miña primeira clave",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Despois, lista os teus buckets e os ficheiros dun cartafol:

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

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

As listas devolven data e nextCursor. Para a páxina seguinte, envía ese valor en cursor. Cando nextCursor é null, non hai máis.

Terminal coa petición GET /v1/me e a súa resposta Terminal coa petición GET /v1/me e a súa resposta

Paso 3: a referencia

En Configuración › API, preme Ver documentación, ou abre api.nubbo.app/v1/docs. Aí está cada recurso cos seus campos e exemplos. O documento OpenAPI está en api.nubbo.app/v1/openapi.json.

Referencia da API de Nubbo co exemplo en curl Referencia da API de Nubbo co exemplo en curl

Subidas e descargas

Os ficheiros non pasan por Nubbo. Para subir un, pide a subida con POST /v1/buckets/{bucketId}/uploads, envía o ficheiro ao enderezo preasinado que che devolve e remata con POST /v1/uploads/{uploadId}/complete. Para descargar, pide unha ligazón con POST /v1/files/{fileId}/download-link e descárgao desde o teu provedor.

Límites

ProEquipos
Peticións por minuto por clave60120
Peticións ao mes50.000100.000 + 10.000 por praza
Eventos de disparadores ao mes20.00050.000 + 5.000 por praza

A cota é do espazo e renóvase con cada período de facturación. GET /v1/me, as consultas dos disparadores e as respostas 401, 429 e 5xx non contan como peticións. Cada evento que entrega un disparador conta como evento. Cada resposta trae as cabeceiras X-RateLimit-Remaining e X-Nubbo-Quota-Requests-Remaining, e en Configuración › API ves o uso do período.

Uso da API do período na configuración de Nubbo Uso da API do período na configuración de Nubbo

Se algo falla

  • API_KEY_INVALID, API_KEY_REVOKED ou API_KEY_EXPIRED: a clave non vale, está revogada ou caducou. Revisa a cabeceira ou crea outra clave.
  • API_PLAN_REQUIRED: o espazo da clave non ten a API. Está nos plans Pro e Equipos.
  • API_KEY_READ_ONLY: a clave é de só lectura. Crea unha con Lectura e escritura.
  • API_RATE_LIMITED: demasiadas peticións con esta clave. Agarda os segundos de Retry-After e volve probar.
  • API_QUOTA_EXCEEDED: o espazo usou o seu límite do mes. details.resetsAt indica cando se renova.

Cada erro trae un requestId. Inclúeo se nos escribes.

Máis sobre a API de Nubbo. Para usala sen escribir código, segue a guía de Zapier, a de n8n ou a de Make. Para usala desde o teu asistente de IA, mira como conectar Nubbo con Claude, ChatGPT ou Cursor.

Preguntas frecuentes

Que plans inclúen a API?

Pro e Equipos. Con Gratuíto ou Personal, as peticións responden API_PLAN_REQUIRED.

Podo ler ficheiros cifrados coa API?

Non. O contido cifrado aparece sen nome, ruta, tamaño nin tipo e calquera cambio sobre el rexéitase con API_ENCRYPTED_CONTENT.

Que pasa se repito unha petición por un fallo de rede?

Envía a cabeceira Idempotency-Key nos teus POST e PATCH. Durante 24 horas, repetir a mesma petición devolve a primeira resposta e non crea nada dúas veces.

Cambiará a API sen avisar?

Non. Un cambio que rompa algo chega como /v2 e /v1 mantense polo menos 12 meses, coas cabeceiras Deprecation e Sunset.

Fontes

Pasos comprobados con estas páxinas.