Referência da API
O HummingDeck expõe uma API REST para parceiros de integração e plataformas de automação. Os endpoints autenticam-se com um Bearer token e devolvem respostas JSON.
https://app.hummingdeck.com/api/v1Autenticação
Cada pedido à API leva um Bearer token no cabeçalho Authorization. São aceites dois tipos de credencial, e comportam-se de forma diferente.
Método
Bearer token
Formato do cabeçalho
Authorization: Bearer {access_token}
Tipos de credencial
Token de API do espaço de trabalho
Authorization: Bearer hd_api_...
Emitido pelo proprietário do espaço de trabalho em Definições do espaço, Integrações, HummingDeck API. Disponível para espaços selecionados durante um piloto privado. O token é mostrado uma única vez ao ser criado e não pode ser recuperado depois. Expira um ano após a criação e fica ligado de forma permanente ao espaço para o qual foi emitido, pelo que um pedido não pode escolher nem alterar o seu espaço de trabalho.
Criar um token quando já existe um substitui-o, e o anterior deixa de funcionar de imediato. O proprietário pode desativar um token a qualquer momento. Para esse token é definitivo: crie um novo em vez de contar com a reposição.
Os endpoints de subscrição de webhooks não estão disponíveis para tokens de API do espaço de trabalho.
Zapier OAuth
Authorization: Bearer {access_token}
Emitido através do fluxo de autorização OAuth quando um espaço de trabalho liga a integração Zapier. Os tokens de acesso expiram ao fim de 30 dias. Use o token de atualização, válido 90 dias, para obter um novo sem voltar a autorizar.
É a única credencial que pode criar ou eliminar subscrições de webhooks.
Quando um pedido devolve 401
Um pedido é rejeitado com 401 quando o token é desconhecido ou inválido, expirou, foi desativado, pertence a um espaço de trabalho cujo acesso à API foi desligado, ou foi emitido por alguém que já não é proprietário desse espaço.
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, XLSX, HTML) e um campo title. O limite de upload pela API é de 30 MB./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 |
Salas
Consulte a estrutura de uma sala e crie links de público rastreáveis. Disponível apenas com tokens de API do espaço de trabalho; as credenciais OAuth do Zapier são rejeitadas.
/rooms/{roomId}Retorna metadados, abas, itens e a quantidade de links ativos e totais da sala./rooms/{roomId}/linksCria um link aberto com atribuição para uma sala ativa.Criar um link aberto para a sala
Informe pelo menos um destes campos: recipientName, recipientEmail, contactId, companyId ou companyName. Nome e e-mail localizam ou criam um contato; os campos de empresa localizam ou criam uma empresa. Qualquer pessoa com a URL pode acessar um link aberto.
{
"accessMode": "open",
"recipientName": "Ada Lovelace",
"recipientEmail": "ada@analytical.example",
"companyName": "Analytical Engines"
}Empresas e contatos
Localize registros de conta existentes ou crie novos com correspondência determinística. Nomes de empresas e e-mails de contatos são comparados sem diferenciar maiúsculas de minúsculas.
/companies?name={name}&domain={domain}Pesquisa empresas pelo nome exato e por um domínio opcional./companiesLocaliza uma empresa pelo nome sem diferenciar maiúsculas de minúsculas ou a cria. Um domínio explícito apenas enriquece o registro./contacts?email={query}Pesquisa contatos por endereço de e-mail e retorna as correspondências com a empresa associada./contactsLocaliza ou cria um contato pelo e-mail e o associa opcionalmente a uma empresa.Requisição POST /companies
| Field | Type | Description | |
|---|---|---|---|
| name | string | obrigatório | Nome da empresa |
| domain | string | opcional | Domínio usado para enriquecer a empresa. Nunca é usado para localizar uma empresa existente |
Requisição POST /contacts
| Field | Type | Description | |
|---|---|---|---|
| name | string | condicional | Nome completo. Obrigatório se firstName não for informado |
| firstName | string | condicional | Nome. Obrigatório se name não for informado |
| lastName | string | opcional | Sobrenome |
| string | obrigatório | Endereço de e-mail usado para correspondência única | |
| title | string | opcional | Cargo |
| companyId | UUID | opcional | Empresa existente no espaço de trabalho autenticado |
| companyName | string | opcional | Nome da empresa a localizar ou criar |
| companyDomain | string | opcional | Domínio opcional de enriquecimento usado com companyName. Não é uma chave de correspondência |
Resposta da empresa
| Field | Type | Description |
|---|---|---|
| company.id | UUID | ID da empresa |
| company.name | string | Nome da empresa |
| company.domain | string | null | Domínio normalizado da empresa |
| created | boolean | true se a requisição POST criou a empresa |
Resposta do contato
| Field | Type | Description |
|---|---|---|
| contact.id | UUID | ID do contato |
| contact.firstName | string | Nome |
| contact.lastName | string | Sobrenome |
| contact.email | string | Endereço de e-mail normalizado |
| contact.title | string | null | Cargo |
| contact.companyId | UUID | null | ID da empresa associada |
| contact.companyName | string | null | Nome da empresa associada |
| created | boolean | true se a requisição POST criou o contato |
| company | object | null | Empresa resolvida, quando disponível |
| companyCreated | boolean | true se esta requisição criou a empresa |
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). As subscrições de webhooks são geridas pela integração Zapier e não estão disponíveis para tokens de API do espaço de trabalho.
/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
Cada erro devolve um objeto JSON com um campo error que descreve o que correu mal. Algumas respostas incluem ainda um campo code para tratamento programático, como PLAN_LIMIT_REACHED, INVALID_FORMAT ou FILE_TOO_LARGE. Os códigos de estado HTTP seguem as convenções habituais.
| Status | Meaning |
|---|---|
| 400 | Requisição inválida: parâmetros ausentes ou inválidos |
| 401 | Não autorizado: Bearer token inválido ou expirado |
| 403 | Proibido: limite do plano atingido, ou este tipo de credencial não é permitido neste endpoint |
| 404 | Não encontrado: o recurso não existe ou não pertence à sua equipe |
| 409 | Conflito: os identificadores de contato, e-mail e empresa informados não correspondem |
| 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.