Referencia de API

HummingDeck expone una API REST para socios de integración y plataformas de automatización. Todos los endpoints usan autenticación OAuth 2.0 y devuelven respuestas JSON.

URL basehttps://app.hummingdeck.com/api/v1

OpenAPI Spec

Autenticación

Todas las solicitudes de API requieren un Bearer token OAuth 2.0 válido en el encabezado Authorization. Los tokens se emiten durante el flujo de autorización OAuth y expiran después de 30 días. Use el token de actualización (caducidad de 90 días) para obtener un nuevo token de acceso sin volver a autorizar.

Método

OAuth 2.0 (Bearer token)

Formato del encabezado

Authorization: Bearer {access_token}

Prueba tu conexión

Verifica que tu token es válido y consulta el perfil del usuario autenticado.

GET/meDevuelve el nombre, el correo electrónico y la información del equipo del usuario actual.

Documentos

Sube, busca y gestiona documentos (PDFs, presentaciones, propuestas y otros archivos).

POST/decksSube un nuevo documento. Envía como multipart/form-data con un campo file (PDF, PPTX, DOCX, HTML) y un campo title.

GET/decks?title={query}Busca documentos por título. No distingue mayúsculas de minúsculas; devuelve hasta 20 resultados.

Campos de respuesta

Field	Type	Description
id	string	ID del documento
title	string	Título del documento
fileType	string	Tipo de archivo (pdf, pptx, docx, html)
pageCount	number	Número de páginas
thumbnailUrl	string	URL de la imagen en miniatura
createdAt	string	Marca de tiempo ISO 8601

Enlaces de compartición

Crea enlaces rastreables para compartir documentos con prospectos. Cada enlace realiza un seguimiento del interés por separado.

POST/sharesCrea un enlace de compartición. Admite enlaces personales (con nombre y correo del destinatario) y enlaces anónimos.

Campos de la solicitud

Field	Type		Description
deckId	string	required	ID del documento a compartir
recipientName	string	optional	Nombre del destinatario (para enlaces personales)
recipientEmail	string	optional	Correo electrónico del destinatario (para enlaces personales)
type	string	optional	"personal" o "anonymous" (por defecto: anonymous)

Campos de respuesta

Field	Type	Description
id	string	ID del enlace de compartición
slug	string	Slug del enlace (usado en la URL)
shareUrl	string	URL rastreable completa
type	string	"personal" o "anonymous"
recipientName	string	Nombre del destinatario (si es personal)
recipientEmail	string	Correo del destinatario (si es personal)
createdAt	string	Marca de tiempo ISO 8601

Contactos

Busca contactos en la libreta de direcciones de tu equipo.

GET/contacts?email={query}Busca contactos por dirección de correo electrónico. Devuelve contactos coincidentes con su empresa asociada.

Campos de respuesta

Field	Type	Description
id	string	ID del contacto
firstName	string	Nombre
lastName	string	Apellido
email	string	Dirección de correo electrónico
title	string	Cargo
leadName	string	Nombre de la empresa
createdAt	string	Marca de tiempo ISO 8601

Webhooks

Suscríbete a eventos en tiempo real mediante REST Hooks. Cuando ocurre un evento, HummingDeck envía una solicitud POST a tu URL HTTPS registrada con el payload del evento. Las entregas fallidas se reintentan hasta 3 veces (a intervalos de 1 s, 5 s y 30 s).

POST/hooksSuscribirse a un evento. Requiere una URL HTTPS de destino y un tipo de evento. Devuelve un ID de suscripción.

DELETE/hooks/{id}Cancelar la suscripción a un evento por ID de suscripción.

Tipos de eventos

Event	Description
view.created	Una persona real vio un documento compartido. El tráfico de bots (escáneres de seguridad de correo electrónico, rastreadores) se filtra automáticamente.
decision.made	Un prospecto respondió a una propuesta — aceptada, rechazada o con cambios solicitados.
email_captured	Un visitante introdujo su dirección de correo electrónico para acceder a contenido protegido.

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

Vistas y eventos

Endpoints de sondeo para recuperar datos de interacción recientes. Devuelven los mismos datos que entregan los webhooks en tiempo real — úsalos para rellenar histórico, hacer pruebas o como alternativa.

GET/viewsListar las 100 visualizaciones de documentos más recientes. Las sesiones de bots están excluidas.

GET/decisionsListar las decisiones recientes sobre propuestas (aceptadas, rechazadas, cambios solicitados).

GET/emailsListar las capturas de correo electrónico recientes de contenido protegido.

Manejo de errores

Todos los errores devuelven un objeto JSON con un campo message. Los códigos de estado HTTP siguen las convenciones estándar.

Status	Meaning
400	Solicitud incorrecta — parámetros faltantes o inválidos
401	No autorizado — Bearer token inválido o expirado
404	No encontrado — el recurso no existe o no pertenece a tu equipo
500	Error del servidor — reintenta la solicitud

Límites de velocidad

Máximo 50 suscripciones de webhook activas por equipo. Las solicitudes de API no tienen límite de velocidad, pero un uso excesivo puede ser limitado.

Esta API es utilizada actualmente por nuestra integración con Zapier. Es posible que en el futuro se admitan plataformas de integración adicionales.