Poradniki

Pierwsze kroki z API Nubbo

Od zera do pierwszego zapytania w kilka minut. Utwórz klucz i zacznij zarządzać swoją pamięcią masową z własnego kodu.

API Nubbo to API REST do pracy z Twoimi bucketami z własnego kodu: pliki, foldery, linki, prośby o pliki, galerie, etykiety, projekty i automatyzacje. W tym poradniku tworzysz klucz i wysyłasz pierwsze żądania za pomocą curl.

Co zyskujesz

  • Zarządzasz swoją przestrzenią Nubbo z własnych programów, kluczami, które widzą tylko to, co wybierzesz.
  • Przesyłasz i pobierasz pliki bezpośrednio między swoim kodem a dostawcą pamięci masowej.
  • Reagujesz na nowe pliki, przesłania do próśb o pliki i aktywność dzięki wyzwalaczom.

Zanim zaczniesz

Potrzebujesz konta Nubbo z planem Pro lub Zespoły i terminala z curl. W zespole klucze API tworzy właściciel lub administrator.

Krok 1: utwórz klucz

  1. W Nubbo otwórz Ustawienia › API (lub Zespół › API w zespole) i naciśnij Utwórz klucz API.

  2. Nadaj mu nazwę i wybierz:

    • Dostęp: Tylko odczyt lub Odczyt i zapis.
    • Zakres: Cała przestrzeń lub Wybrane buckety i projekty. Klucz widzi tylko to, co tu wybierzesz.
    • Wygaśnięcie: 30 dni, 90 dni, 1 rok lub Bez wygaśnięcia. Nubbo przypomni Ci 7 dni wcześniej.

    Naciśnij Utwórz klucz. Nubbo poprosi o hasło, aby potwierdzić, że to Ty. Jeśli masz włączoną weryfikację dwuetapową, poprosi też o kod.

    Okno Utwórz klucz API z dostępem, zakresem i wygaśnięciem Okno Utwórz klucz API z dostępem, zakresem i wygaśnięciem
  3. Skopiuj klucz i naciśnij Klucz zapisany. Zaczyna się od nbk_ i tylko teraz widzisz go w całości. Przechowuj go na serwerze lub w narzędziu, które będzie go używać, nigdy na stronie internetowej.

    Okno twój klucz API z kluczem gotowym do skopiowania Okno twój klucz API z kluczem gotowym do skopiowania

Krok 2: pierwsze żądanie

Wysyłaj klucz w nagłówku Authorization każdego żądania. Zacznij od GET /v1/me, które nie zużywa żądań:

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

Odpowiedź zawiera twoją przestrzeń, twój plan, limit na ten miesiąc oraz klucz z jego dostępem i zakresem. Oto fragment:

{
  "workspace": { "id": "…", "name": "Studio Północ", "kind": "PERSONAL" },
  "plan": "PRO",
  "key": {
    "name": "Mój pierwszy klucz",
    "prefix": "nbk_3jKF3m",
    "access": "READ",
    "allResources": true
  },
  "quota": {
    "requests": { "used": 0, "limit": 50000, "remaining": 50000 },
    "events": { "used": 0, "limit": 20000, "remaining": 20000 },
    "ratePerMinute": 60
  }
}

Następnie wyświetl swoje buckety i pliki z folderu:

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

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

Listy zwracają data i nextCursor. Aby pobrać następną stronę, wyślij tę wartość w cursor. Gdy nextCursor ma wartość null, nie ma nic więcej.

Terminal z żądaniem GET /v1/me i jego odpowiedzią Terminal z żądaniem GET /v1/me i jego odpowiedzią

Krok 3: dokumentacja

W Ustawienia › API naciśnij Zobacz dokumentację albo otwórz api.nubbo.app/v1/docs. Znajdziesz tam każdy zasób z polami i przykładami. Dokument OpenAPI jest pod adresem api.nubbo.app/v1/openapi.json.

Dokumentacja API Nubbo z przykładem w curl Dokumentacja API Nubbo z przykładem w curl

Przesyłanie i pobieranie

Pliki nie przechodzą przez Nubbo. Aby przesłać plik, poproś o przesłanie przez POST /v1/buckets/{bucketId}/uploads, wyślij plik na otrzymany podpisany adres i zakończ przez POST /v1/uploads/{uploadId}/complete. Aby pobrać plik, poproś o link przez POST /v1/files/{fileId}/download-link i pobierz go od swojego dostawcy.

Limity

ProZespoły
Żądania na minutę na klucz60120
Żądania na miesiąc50 000100 000 + 10 000 za stanowisko
Zdarzenia wyzwalaczy na miesiąc20 00050 000 + 5 000 za stanowisko

Limit należy do przestrzeni i odnawia się z każdym okresem rozliczeniowym. GET /v1/me, odpytywanie wyzwalaczy oraz odpowiedzi 401, 429 i 5xx nie liczą się jako żądania. Każde zdarzenie dostarczone przez wyzwalacz liczy się jako zdarzenie. Każda odpowiedź zawiera nagłówki X-RateLimit-Remaining i X-Nubbo-Quota-Requests-Remaining, a w Ustawienia › API widzisz zużycie w danym okresie.

Zużycie API w danym okresie w ustawieniach Nubbo Zużycie API w danym okresie w ustawieniach Nubbo

Jeśli coś pójdzie nie tak

  • API_KEY_INVALID, API_KEY_REVOKED lub API_KEY_EXPIRED: klucz jest nieprawidłowy, unieważniony albo wygasł. Sprawdź nagłówek lub utwórz nowy klucz.
  • API_PLAN_REQUIRED: przestrzeń klucza nie ma dostępu do API. Jest ono dostępne w planach Pro i Zespoły.
  • API_KEY_READ_ONLY: klucz ma tylko odczyt. Utwórz klucz z dostępem Odczyt i zapis.
  • API_RATE_LIMITED: za dużo żądań z tym kluczem. Odczekaj liczbę sekund z Retry-After i spróbuj ponownie.
  • API_QUOTA_EXCEEDED: przestrzeń wykorzystała miesięczny limit. details.resetsAt mówi, kiedy się odnowi.

Każdy błąd zawiera requestId. Podaj go, jeśli do nas piszesz.

Więcej o API Nubbo. Aby korzystać z niego bez pisania kodu, skorzystaj z poradnika dla Zapiera, n8n lub Make. Aby korzystać z niego w asystencie AI, zobacz, jak połączyć Nubbo z Claude, ChatGPT lub Cursorem.

Najczęściej zadawane pytania

Które plany obejmują API?

Pro i Zespoły. W planie Bezpłatny lub Personal żądania zwracają API_PLAN_REQUIRED.

Czy mogę odczytywać zaszyfrowane pliki przez API?

Nie. Zaszyfrowana zawartość pojawia się bez nazwy, ścieżki, rozmiaru i typu, a każda jej zmiana jest odrzucana z kodem API_ENCRYPTED_CONTENT.

Co się stanie, jeśli powtórzę żądanie po błędzie sieci?

Wysyłaj nagłówek Idempotency-Key w żądaniach POST i PATCH. Przez 24 godziny powtórzenie tego samego żądania zwraca pierwszą odpowiedź i nic nie powstaje dwa razy.

Czy API zmieni się bez ostrzeżenia?

Nie. Zmiana, która coś psuje, trafia do /v2, a /v1 działa jeszcze co najmniej 12 miesięcy, z nagłówkami Deprecation i Sunset.

Źródła

Kroki sprawdzone na tych stronach.