Dokumentacja API

HummingDeck udostępnia REST API dla partnerów integracyjnych i platform automatyzacji. Wszystkie punkty końcowe używają uwierzytelniania OAuth 2.0 i zwracają odpowiedzi JSON.

Bazowy URLhttps://app.hummingdeck.com/api/v1

OpenAPI Spec

Uwierzytelnianie

Wszystkie żądania API wymagają prawidłowego Bearer tokenu OAuth 2.0 w nagłówku Authorization. Tokeny są wydawane podczas przepływu autoryzacji OAuth i wygasają po 30 dniach. Użyj tokenu odświeżania (ważność 90 dni), aby uzyskać nowy token dostępu bez ponownej autoryzacji.

Metoda

OAuth 2.0 (Bearer token)

Format nagłówka

Authorization: Bearer {access_token}

Przetestuj połączenie

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

GET/meZwraca imię i nazwisko, adres e-mail oraz informacje o zespole bieżącego użytkownika.

Dokumenty

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

POST/decksPrześlij nowy dokument. Wyślij jako multipart/form-data z polem file (PDF, PPTX, DOCX, HTML) i polem title.

GET/decks?title={query}Wyszukaj dokumenty według tytułu. Wyszukiwanie bez rozróżniania wielkości liter, zwraca do 20 wyników.

Pola odpowiedzi

Field	Type	Description
id	string	Identyfikator dokumentu
title	string	Tytuł dokumentu
fileType	string	Typ pliku (pdf, pptx, docx, html)
pageCount	number	Liczba stron
thumbnailUrl	string	URL miniatury
createdAt	string	Znacznik czasu ISO 8601

Linki do udostępniania

Twórz śledzalne linki do udostępniania dokumentów potencjalnym klientom. Każdy link śledzi zaangażowanie osobno.

POST/sharesUtwórz link do udostępniania. Obsługuje linki osobiste (z imieniem i e-mailem odbiorcy) oraz linki anonimowe.

Pola żądania

Field	Type		Description
deckId	string	required	Identyfikator dokumentu do udostępnienia
recipientName	string	optional	Imię i nazwisko odbiorcy (dla linków osobistych)
recipientEmail	string	optional	Adres e-mail odbiorcy (dla linków osobistych)
type	string	optional	"personal" lub "anonymous" (domyślnie: anonymous)

Pola odpowiedzi

Field	Type	Description
id	string	Identyfikator udostępnienia
slug	string	Slug udostępnienia (używany w URL)
shareUrl	string	Pełny śledzalny URL
type	string	"personal" lub "anonymous"
recipientName	string	Imię odbiorcy (jeśli osobisty)
recipientEmail	string	E-mail odbiorcy (jeśli osobisty)
createdAt	string	Znacznik czasu ISO 8601

Kontakty

Wyszukuj kontakty w książce adresowej swojego zespołu.

GET/contacts?email={query}Wyszukaj kontakty według adresu e-mail. Zwraca pasujące kontakty wraz z powiązaną firmą.

Pola odpowiedzi

Field	Type	Description
id	string	Identyfikator kontaktu
firstName	string	Imię
lastName	string	Nazwisko
email	string	Adres e-mail
title	string	Stanowisko
leadName	string	Nazwa firmy
createdAt	string	Znacznik czasu ISO 8601

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).

POST/hooksSubskrybuj zdarzenie. Wymaga docelowego adresu HTTPS i typu zdarzenia. Zwraca identyfikator subskrypcji.

DELETE/hooks/{id}Anuluj subskrypcję zdarzenia na podstawie identyfikatora subskrypcji.

Typy zdarzeń

Event	Description
view.created	Prawdziwa osoba obejrzała udostępniony dokument. Ruch botów (skanery bezpieczeństwa e-mail, crawlery) jest automatycznie filtrowany.
decision.made	Potencjalny klient odpowiedział na propozycję — zaakceptował, odrzucił lub poprosił o zmiany.
email_captured	Odwiedzający podał swój adres e-mail, aby uzyskać dostęp do treści z bramką.

Przykładowe ładunki

view.created

{
  "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"
  }
}

decision.made

{
  "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"
  }
}

email_captured

{
  "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ę.

GET/viewsWyświetl 100 ostatnich wyświetleń dokumentów. Sesje botów są wykluczone.

GET/decisionsWyświetl ostatnie decyzje dotyczące propozycji (zaakceptowane, odrzucone, poproszone o zmiany).

GET/emailsWyświetl ostatnie przechwycenia e-maili z treści z bramką.

Obsługa błędów

Wszystkie błędy zwracają obiekt JSON z polem message. Kody stanu HTTP są zgodne ze standardowymi konwencjami.

Status	Meaning
400	Nieprawidłowe żądanie — brakujące lub nieprawidłowe parametry
401	Brak autoryzacji — nieprawidłowy lub wygasły Bearer token
404	Nie znaleziono — zasób nie istnieje lub nie należy do Twojego zespołu
500	Błąd serwera — ponów żądanie

Limity liczby żądań

Maksymalnie 50 aktywnych subskrypcji webhooków na zespół. Żądania API nie są ograniczone, ale nadmierne użycie może być ograniczane.

To API jest obecnie używane przez naszą integrację Zapier. W przyszłości mogą być obsługiwane dodatkowe platformy integracyjne.