API Referansı

HummingDeck, entegrasyon ortakları ve otomasyon platformları için bir REST API sunar. Tüm uç noktalar OAuth 2.0 kimlik doğrulaması kullanır ve JSON yanıtları döndürür.

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

OpenAPI Spec

Kimlik Doğrulama

Tüm API istekleri, Authorization başlığında geçerli bir OAuth 2.0 Bearer token gerektirir. Token'lar OAuth yetkilendirme akışı sırasında verilir ve 30 gün sonra sona erer. Yeniden yetkilendirme yapmadan yeni bir erişim token'ı almak için yenileme token'ını (90 günlük süre) kullanın.

Yöntem

OAuth 2.0 (Bearer token)

Başlık biçimi

Authorization: Bearer {access_token}

Bağlantınızı test edin

Token'ınızın geçerli olduğunu doğrulayın ve kimliği doğrulanmış kullanıcının profilini görüntüleyin.

GET/meGeçerli kullanıcının adını, e-postasını ve ekip bilgilerini döndürür.

Belgeler

Belgeleri (PDF'ler, slayt destesi, teklifler ve diğer dosyalar) yükleyin, arayın ve yönetin.

POST/decksYeni bir belge yükleyin. file alanı (PDF, PPTX, DOCX, HTML) ve title alanıyla birlikte multipart/form-data olarak gönderin.

GET/decks?title={query}Belgeleri başlığa göre arayın. Büyük/küçük harf duyarsız, en fazla 20 sonuç döndürür.

Yanıt alanları

Field	Type	Description
id	string	Belge kimliği
title	string	Belge başlığı
fileType	string	Dosya türü (pdf, pptx, docx, html)
pageCount	number	Sayfa sayısı
thumbnailUrl	string	Küçük resim URL'si
createdAt	string	ISO 8601 zaman damgası

Paylaşım Bağlantıları

Belgeleri potansiyel müşterilerle paylaşmak için izlenebilir bağlantılar oluşturun. Her bağlantı etkileşimi ayrı ayrı takip eder.

POST/sharesPaylaşım bağlantısı oluşturun. Kişisel bağlantıları (alıcı adı ve e-postası ile) ve anonim bağlantıları destekler.

İstek alanları

Field	Type		Description
deckId	string	required	Paylaşılacak belgenin kimliği
recipientName	string	optional	Alıcının adı (kişisel bağlantılar için)
recipientEmail	string	optional	Alıcının e-postası (kişisel bağlantılar için)
type	string	optional	"personal" veya "anonymous" (varsayılan: anonymous)

Yanıt alanları

Field	Type	Description
id	string	Paylaşım kimliği
slug	string	Paylaşım slug'ı (URL'de kullanılır)
shareUrl	string	Tam izlenebilir URL
type	string	"personal" veya "anonymous"
recipientName	string	Alıcı adı (kişisel ise)
recipientEmail	string	Alıcı e-postası (kişisel ise)
createdAt	string	ISO 8601 zaman damgası

Kişiler

Ekibinizin adres defterinde kişileri arayın.

GET/contacts?email={query}Kişileri e-posta adresine göre arayın. İlgili şirketiyle birlikte eşleşen kişileri döndürür.

Yanıt alanları

Field	Type	Description
id	string	Kişi kimliği
firstName	string	Ad
lastName	string	Soyad
email	string	E-posta adresi
title	string	Unvan
leadName	string	Şirket adı
createdAt	string	ISO 8601 zaman damgası

Webhook'lar

REST Hooks aracılığıyla gerçek zamanlı olaylara abone olun. Bir olay gerçekleştiğinde, HummingDeck kayıtlı HTTPS URL'nize olay yüküyle birlikte bir POST isteği gönderir. Başarısız teslimler 3 defaya kadar yeniden denenir (1 s, 5 s ve 30 s aralıklarla).

POST/hooksBir olaya abone olun. Hedef HTTPS URL'si ve olay türü gerektirir. Abonelik kimliği döndürür.

DELETE/hooks/{id}Abonelik kimliğiyle bir olaydan çıkın.

Olay türleri

Event	Description
view.created	Gerçek bir kişi paylaşılan bir belgeyi görüntüledi. Bot trafiği (e-posta güvenlik tarayıcıları, gezginler) otomatik olarak filtrelenir.
decision.made	Potansiyel müşteri bir teklife yanıt verdi — kabul etti, reddetti veya değişiklik talep etti.
email_captured	Bir ziyaretçi, korumalı içeriğe erişmek için e-posta adresini girdi.

Örnek yükler

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

Görüntülemeler ve Olaylar

Son etkileşim verilerini almak için yoklama uç noktaları. Bunlar, webhook'ların gerçek zamanlı olarak ilettiği aynı verileri döndürür — geri doldurma, test veya yedek olarak kullanın.

GET/viewsEn son 100 belge görüntülemesini listeleyin. Bot oturumları hariç tutulur.

GET/decisionsSon teklif kararlarını listeleyin (kabul edildi, reddedildi, değişiklik talep edildi).

GET/emailsKorumalı içerikten son e-posta yakalamalarını listeleyin.

Hata işleme

Tüm hatalar, message alanı olan bir JSON nesnesi döndürür. HTTP durum kodları standart kurallara uyar.

Status	Meaning
400	Hatalı istek — eksik veya geçersiz parametreler
401	Yetkisiz — geçersiz veya süresi dolmuş Bearer token
404	Bulunamadı — kaynak mevcut değil veya ekibinize ait değil
500	Sunucu hatası — isteği yeniden deneyin

Hız sınırları

Ekip başına maksimum 50 aktif webhook aboneliği. API isteklerine hız sınırı uygulanmaz, ancak aşırı kullanım kısıtlanabilir.

Bu API şu anda Zapier entegrasyonumuz tarafından kullanılmaktadır. Gelecekte ek entegrasyon platformları desteklenebilir.