Dokumentacja API

Uwierzytelnianie

Każde żądanie do API przesyła token Bearer w nagłówku Authorization. Akceptowane są dwa rodzaje poświadczeń i działają one inaczej.

Rodzaje poświadczeń

Uprawnienia

Wybierz co najmniej jedno uprawnienie. Uprawnienia do zapisu obejmują również odpowiedni dostęp do odczytu. Możesz zmienić uprawnienia podczas zastępowania klucza.

Etykiety uprawnień przy punktach końcowych dotyczą kluczy API obszaru roboczego. Uprawnienia wymagane obowiązują zawsze, dodatkowe są potrzebne razem z nimi, a warunkowe tylko wtedy, gdy żądanie używa powiązanych filtrów lub pól. GET /me nie wymaga uprawnień. Zapier OAuth korzysta ze stałego dostępu integracji.

Kiedy żądanie zwraca 401

Żądanie zwraca 401, gdy klucz jest nieznany lub nieprawidłowy, wygasł, został wyłączony, należy do obszaru roboczego z wyłączonym dostępem do API albo został wydany przez osobę, która nie jest już właścicielem ani administratorem tego obszaru.

Przetestuj połączenie

Sprawdź, czy Twój token jest ważny, i wyświetl profil uwierzytelnionego użytkownika.

Dokumenty

Przesyłaj, wyszukuj i zarządzaj dokumentami (plikami PDF, prezentacjami, propozycjami i innymi plikami).

GET /decks Pola odpowiedzi

POST /decks Pola odpowiedzi

Linki do udostępniania

Twórz śledzalne linki do dokumentów. Link osobisty może znaleźć lub utworzyć kontakt i firmę w tym samym żądaniu.

Pola żądania

Utwórz link i rekordy konta w jednym kroku

Prześlij dane odbiorcy i firmy bezpośrednio do /shares. HummingDeck znajduje pasujące rekordy, tworzy brakujące, łączy je z linkiem i informuje, które zostały utworzone. Ustaw type jawnie na anonymous, aby pominąć tworzenie rekordów konta.

{
  "deckId": "8f3d41de-2bb8-4d8e-80de-6cd2072ffab1",
  "recipientName": "Ada Lovelace",
  "recipientEmail": "ada@analytical.example",
  "companyName": "Analytical Engines",
  "companyDomain": "analytical.example"
}

Pola odpowiedzi

Pokoje

Twórz pokoje transakcyjne z dokumentami i linkiem dla odbiorców w jednym wywołaniu, wyszukuj pokoje, zmieniaj ich ustawienia, archiwizuj je i przywracaj oraz porządkuj ich karty i elementy. Funkcja jest dostępna tylko z tokenami API obszaru roboczego; dane uwierzytelniające OAuth Zapier są odrzucane.

Utwórz pokój jednym wywołaniem

Prześlij każdy plik za pomocą POST /decks, a następnie utwórz pokój dla firmy odbiorcy z ograniczonym linkiem dla osób, które mają go zobaczyć. Firma, kontakty, pokój, dokumenty i link powstają razem: jeśli wywołanie zostanie odrzucone, nic nie zostanie utworzone. Dokumenty mogą trafić do pokoju jeszcze w trakcie przetwarzania. Elementy pokoju podają processingStatus, więc wyślij link, gdy każdy dokument będzie miał status completed.

{
  "name": "Acme renewal",
  "companyName": "Acme Inc",
  "recipientName": "Pat Buyer",
  "recipientEmail": "pat@acme.example",
  "documentIds": [
    "{documentId}",
    "{documentId}"
  ],
  "primaryLink": {
    "accessMode": "verified-allowlist",
    "allowedEmails": [
      "pat@acme.example",
      {
        "email": "cfo@acme.example",
        "name": "Sam Rivera"
      }
    ],
    "allowedDomains": [
      "acme.example"
    ]
  }
}

accessMode to open (każdy, kto ma URL), verify-any (odwiedzający potwierdzają adres e-mail jednorazowym linkiem) lub verified-allowlist (tylko adresy z allowedEmails i każdy z adresem w domenach z allowedDomains). API samo nikogo nie dodaje do ograniczonego linku, więc dodaj własny adres, jeśli chcesz obejrzeć pokój wcześniej. Opcja, której nie obejmuje Twój plan, zwraca 403 FEATURE_NOT_AVAILABLE, a nieznane pole zwraca 400, dzięki czemu pokój nigdy nie otworzy się dla innych odbiorców niż ci, o których prosisz.

Porządkuj karty i elementy

Zacznij od aktualnego stanu pokoju: odczyt pokoju zwraca jego karty i elementy w kolejności wyświetlania, a każdy element podaje swoją kartę i pozycję na niej, licząc od 0. Dodawaj karty i elementy w wybranej pozycji, przenoś elementy między kartami i wysyłaj pełną nową kolejność karty. Kolejność musi zawierać każdy element karty dokładnie raz, więc odczytaj pokój ponownie, jeśli w międzyczasie nastąpiła inna zmiana. Kartę można usunąć, gdy nie pokazuje już żadnych elementów.

{
  "type": "section",
  "label": "Commercials",
  "tabId": "{tabId}",
  "position": 0
}

Obsługiwani dostawcy osadzeń

Osadzenia przyjmują link udostępniania lub link osadzenia i normalizują go do formy osadzenia dostawcy. Wszystko spoza tej listy zwraca 400 EMBED_PROVIDER_NOT_SUPPORTED.

Dodaj kolejny link dla odbiorców

Każdy pokój ma już link utworzony przez POST /rooms; dodaj kolejne dla odbiorców, którzy potrzebują innego przypisania lub dostępu. Podaj co najmniej jedno z pól recipientName, recipientEmail, contactId, companyId lub companyName. accessMode przyjmuje te same wartości open, verify-any i verified-allowlist co primaryLink, wraz z tymi samymi polami (requireEmail, allowedEmails, allowedDomains, label, expiresAt, allowDownloads). Odrzucone wywołanie, także z powodu limitu planu, nie zostawia żadnego linku, firmy ani kontaktu.

{
  "companyName": "Analytical Engines",
  "accessMode": "verified-allowlist",
  "allowedEmails": [
    {
      "email": "cfo@analytical.example",
      "name": "Sam Rivera"
    }
  ]
}

Zaktualizuj link

Cztery pola: isActive, expiresAt, allowedEmails, allowedDomains (dwa ostatnie tylko w linkach verified-allowlist). accessMode i slug nigdy się nie zmieniają; zamiast tego utwórz nowy link. Ponowne włączenie linku sprawdza limit aktywnych linków w planie.

{
  "isActive": false
}

Zbuduj plan działania

Każdy pokój ma dokładnie jeden plan, więc plan podpina się pod pokój bez własnego identyfikatora. Większość zadań należy do firmy, a nie do osoby: wyślij samo pole side, a plan odczyta je jako firmę. O to właśnie chodzi, gdy nie wiesz, kto po drugiej stronie wykona pracę. Adres email dodaj tylko wtedy, gdy znasz konkretną osobę. Zadanie wewnętrzne nigdy nie pojawia się w pokoju, więc nie może należeć do odbiorcy.

{
  "title": "Sign the NDA",
  "assignee": {
    "side": "buyer"
  },
  "dueDate": "2026-10-02"
}

Pole recipientCompletionEnabled w planie decyduje, czy osoby otwierające pokój mogą odhaczać zadania swojej strony. Domyślnie ma wartość true i jest to jedyne ograniczenie: API nigdy nie prosi o adres odbiorcy, żeby ukończyć zadanie. To, kto odhaczył każde z nich, jest zapisywane z pewnością wynikającą z trybu dostępu pokoju.

Oznaczaj pokoje etykietami

Etykiety obowiązują w całym obszarze roboczym: utwórz je raz i używaj wielokrotnie. Przekaż labelIds w POST /rooms, aby oznaczyć pokój już przy tworzeniu, albo w PATCH /rooms/{roomId}, aby zastąpić cały zestaw; pusta tablica usuwa wszystkie etykiety, a pominięcie pola zostawia je bez zmian. Pokój ma najwyżej pięć, co wynika ze struktury, a nie z ustawienia. Odczyt pokoju zwraca jego etykiety.

{
  "labelIds": [
    "{labelId}"
  ]
}

Sprawdź, co się wydarzyło

Odpytuj /room-views o wejścia w całym obszarze roboczym, a następnie czytaj analitykę, aktywność i zebrane adresy jednego pokoju. Aby przejść dalej, przekaż nextCursor strony jako cursor; kursor, którego to API nie wydało, zwraca 400 zamiast zaczynać od początku, więc odpytywanie nie powtarza pracy. Zawęź okno aktywności parametrem since i przeglądaj strony za pomocą cursor. /room-views to okno czasowe, a nie archiwum: bez since otrzymasz ostatnie 30 dni, a żądania sięgające dalej niż 90 dni wstecz zostaną odrzucone. Zastosowane okno wraca jako since; wyślij je razem z cursor, aby dalej przeglądać ten sam zestaw.

Firmy i kontakty

Znajdź istniejące rekordy konta lub utwórz nowe z jednoznacznym dopasowaniem. Nazwy firm i adresy e-mail kontaktów są porównywane bez rozróżniania wielkości liter.

Żądanie POST /companies

Żądanie POST /contacts

Odpowiedź firmy

Odpowiedź kontaktu

Webhooki

Subskrybuj zdarzenia w czasie rzeczywistym za pomocą REST Hooks. Gdy wystąpi zdarzenie, HummingDeck wysyła żądanie POST na zarejestrowany adres HTTPS z ładunkiem zdarzenia. Nieudane dostarczenia są ponawiane do 3 razy (po 1 s, 5 s i 30 s). Subskrypcje webhooków są zarządzane przez integrację Zapier i nie są dostępne dla tokenów API przestrzeni roboczej.

Typy zdarzeń

Przykładowe ładunki

{
  "event": "view.created",
  "data": {
    "id": "view_abc123",
    "deck_id": "deck_xyz789",
    "deck_title": "Q4 Enterprise Proposal",
    "viewer_email": "sarah@acme.com",
    "viewer_name": "Sarah Wood",
    "viewer_company": "Acme Corp",
    "location": "San Francisco, CA",
    "device": "Desktop",
    "browser": "Chrome",
    "pages_viewed": 8,
    "total_pages": 12,
    "duration_seconds": 272,
    "completion_percent": 67,
    "created_at": "2026-03-29T14:32:00Z"
  }
}

{
  "event": "decision.made",
  "data": {
    "share_slug": "proposal-2024",
    "decision": "accepted",
    "deck_title": "Q4 Enterprise Proposal",
    "viewer_email": "sarah@acme.com",
    "viewer_name": "Sarah Wood",
    "decision_note": "Approved pending final review",
    "decided_at": "2026-03-29T15:30:00Z"
  }
}

{
  "event": "email_captured",
  "data": {
    "email": "prospect@company.com",
    "share_slug": "proposal-2024",
    "deck_title": "Q4 Enterprise Proposal",
    "view_id": "view_xyz789",
    "captured_at": "2026-03-29T14:35:00Z"
  }
}

Wyświetlenia i zdarzenia

Punkty końcowe pollingu do pobierania ostatnich danych zaangażowania. Zwracają te same dane, które webhooki dostarczają w czasie rzeczywistym. Używaj ich do uzupełniania danych, testowania lub jako rezerwę.

Obsługa błędów

Każdy błąd zwraca obiekt JSON z polem error opisującym, co poszło nie tak. Większość odpowiedzi zawiera też pole code do obsługi programistycznej, na przykład PLAN_LIMIT_REACHED, FEATURE_NOT_AVAILABLE, ROOM_NOT_ACTIVE, TAB_NOT_EMPTY, INVALID_FORMAT lub FILE_TOO_LARGE. Kody stanu HTTP są zgodne z przyjętymi konwencjami.

Limity liczby żądań

Ręczne klucze obszaru roboczego i połączenia OAuth Zapier mają limity na dane uwierzytelniające: 600 odczytów na 5 minut, 120 zapisów na minutę, 60 żądań /room-views na minutę i 20 przesłań na godzinę. Łącznie dla wszystkich danych uwierzytelniających obszar roboczy ma limit 1 200 odczytów na 5 minut, 240 zapisów na minutę, 120 żądań /room-views na minutę i 40 przesłań na godzinę. Nieudane uwierzytelnienia Bearer i nieprawidłowe uwierzytelnienia klienta OAuth są osobno ograniczone do 60 prób na 5 minut dla każdego adresu IP klienta. Maksymalnie 50 aktywnych subskrypcji webhooków na zespół.