Referência da API
O HummingDeck expõe uma API REST para parceiros de integração e plataformas de automação. Todos os endpoints usam autenticação OAuth 2.0 e retornam respostas JSON.
https://app.hummingdeck.com/api/v1Autenticação
Todas as requisições de API exigem um Bearer token OAuth 2.0 válido no cabeçalho Authorization. Os tokens são emitidos durante o fluxo de autorização OAuth e expiram após 30 dias. Use o token de atualização (validade de 90 dias) para obter um novo token de acesso sem precisar reautorizar.
Método
OAuth 2.0 (Bearer token)
Formato do cabeçalho
Authorization: Bearer {access_token}
Teste sua conexão
Verifique se seu token é válido e consulte o perfil do usuário autenticado.
/meRetorna o nome, o e-mail e as informações de equipe do usuário atual.Documentos
Envie, pesquise e gerencie documentos (PDFs, apresentações, propostas e outros arquivos).
/decksEnviar um novo documento. Envie como multipart/form-data com um campo file (PDF, PPTX, DOCX, HTML) e um campo title./decks?title={query}Pesquisar documentos por título. Não diferencia maiúsculas de minúsculas; retorna até 20 resultados.Campos da resposta
| Field | Type | Description |
|---|---|---|
| id | string | ID do documento |
| title | string | Título do documento |
| fileType | string | Tipo de arquivo (pdf, pptx, docx, html) |
| pageCount | number | Número de páginas |
| thumbnailUrl | string | URL da imagem em miniatura |
| createdAt | string | Carimbo de data/hora ISO 8601 |
Contatos
Pesquise contatos no catálogo de endereços da sua equipe.
/contacts?email={query}Pesquisar contatos por endereço de e-mail. Retorna contatos correspondentes com sua empresa associada.Campos da resposta
| Field | Type | Description |
|---|---|---|
| id | string | ID do contato |
| firstName | string | Nome |
| lastName | string | Sobrenome |
| string | Endereço de e-mail | |
| title | string | Cargo |
| leadName | string | Nome da empresa |
| createdAt | string | Carimbo de data/hora ISO 8601 |
Webhooks
Assine eventos em tempo real por meio de REST Hooks. Quando um evento ocorre, o HummingDeck envia uma requisição POST para sua URL HTTPS registrada com o payload do evento. As entregas com falha são repetidas até 3 vezes (com intervalos de 1 s, 5 s e 30 s).
/hooksAssinar um evento. Requer uma URL HTTPS de destino e um tipo de evento. Retorna um ID de assinatura./hooks/{id}Cancelar a assinatura de um evento pelo ID de assinatura.Tipos de eventos
| Event | Description |
|---|---|
| view.created | Uma pessoa real visualizou um documento compartilhado. O tráfego de bots (scanners de segurança de e-mail, crawlers) é filtrado automaticamente. |
| decision.made | Um prospect respondeu a uma proposta — aceita, recusada ou com alterações solicitadas. |
| email_captured | Um visitante inseriu seu endereço de e-mail para acessar conteúdo restrito. |
Exemplos de payloads
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"
}
}Visualizações e eventos
Endpoints de polling para recuperar dados de engajamento recentes. Eles retornam os mesmos dados que os webhooks entregam em tempo real — use-os para preenchimento retroativo, testes ou como alternativa.
/viewsListar as 100 visualizações de documentos mais recentes. Sessões de bots são excluídas./decisionsListar decisões recentes sobre propostas (aceitas, recusadas, alterações solicitadas)./emailsListar capturas de e-mail recentes de conteúdo restrito.Tratamento de erros
Todos os erros retornam um objeto JSON com um campo message. Os códigos de status HTTP seguem as convenções padrão.
| Status | Meaning |
|---|---|
| 400 | Requisição inválida — parâmetros ausentes ou inválidos |
| 401 | Não autorizado — Bearer token inválido ou expirado |
| 404 | Não encontrado — o recurso não existe ou não pertence à sua equipe |
| 500 | Erro do servidor — repita a requisição |
Limites de taxa
Máximo de 50 assinaturas de webhook ativas por equipe. As requisições de API não têm limite de taxa, mas o uso excessivo pode ser limitado.
Esta API é atualmente utilizada pela nossa integração com o Zapier. Plataformas de integração adicionais poderão ser suportadas no futuro.