# Cómo desarrollar integraciones con la API de HubSpot: guía completa para desarrolladores en 2026
## Tabla de Contenidos
- [Introducción](#introducción)
- [Tipos de APIs de HubSpot](#tipos-de-apis-de-hubspot)
- [Autenticación: OAuth 2.0 y Private Apps](#autenticación-oauth-20-y-private-apps)
- [API de CRM Objects: contactos, empresas y deals](#api-de-crm-objects-contactos-empresas-y-deals)
- [API de Marketing: emails, formularios y landing pages](#api-de-marketing-emails-formularios-y-landing-pages)
- [Webhooks de HubSpot](#webhooks-de-hubspot)
- [API de CMS: páginas, blogs y archivos](#api-de-cms-páginas-blogs-y-archivos)
- [Límites de la API y gestión de rate limiting](#límites-de-la-api-y-gestión-de-rate-limiting)
- [Mejores prácticas de desarrollo de integraciones](#mejores-prácticas-de-desarrollo-de-integraciones)
- [Publicar una integración en el HubSpot Marketplace](#publicar-una-integración-en-el-hubspot-marketplace)
- [Preguntas Frecuentes](#preguntas-frecuentes)
- [Conclusión](#conclusión)
- [Referencias](#referencias)
---
## Introducción
La API de HubSpot es una de las APIs de CRM más completas y bien documentadas del mercado. En 2026, HubSpot ofrece más de 100 endpoints organizados en APIs específicas para cada hub (CRM, Marketing, Sales, Service, CMS, Operations).
Esta guía está dirigida a desarrolladores que necesitan integrar sistemas externos con HubSpot, ya sea para sincronizar datos, automatizar procesos o crear aplicaciones que se publiquen en el HubSpot Marketplace.
---
## Tipos de APIs de HubSpot
HubSpot ofrece varios tipos de APIs según el caso de uso:
| API | Descripción | Casos de uso |
|---|---|---|
| CRM API | Gestión de contactos, empresas, deals, tickets, custom objects | Sincronización de datos, integraciones de CRM |
| Marketing API | Emails, formularios, landing pages, listas, campañas | Automatización de marketing, reporting |
| Sales API | Deals, pipelines, meetings, quotes | Integraciones de ventas, automatización de ventas |
| Service API | Tickets, feedback surveys | Integraciones de soporte al cliente |
| CMS API | Páginas, blog posts, archivos, dominios | Gestión de contenido programática |
| Operations API | Data sync, automation, datasets | Integraciones de operaciones |
| Analytics API | Tráfico web, eventos, conversiones | Reporting y análisis de datos |
---
## Autenticación: OAuth 2.0 y Private Apps
HubSpot soporta dos métodos de autenticación principales:
### Private Apps (recomendado para integraciones internas)
Las Private Apps son la forma más sencilla de autenticarse con la API de HubSpot para integraciones internas que solo necesitan acceder a una cuenta de HubSpot.
```javascript
// Autenticación con Private App Token
const client = new Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN });
```
Para crear una Private App:
1. Ve a **Configuración > Integraciones > Private Apps**.
2. Haz clic en **Crear una Private App**.
3. Asigna un nombre y selecciona los scopes necesarios.
4. Copia el token de acceso generado.
### OAuth 2.0 (recomendado para aplicaciones del Marketplace)
OAuth 2.0 es el método de autenticación estándar para aplicaciones que necesitan acceder a múltiples cuentas de HubSpot (aplicaciones del Marketplace).
```javascript
// Flujo de autorización OAuth 2.0
const authUrl = `https://app.hubspot.com/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&scope=${SCOPES}`;
// Intercambiar el código de autorización por un access token
const tokenResponse = await fetch('https://api.hubapi.com/oauth/v1/token', {
method: 'POST',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
body: new URLSearchParams({
grant_type: 'authorization_code',
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
redirect_uri: REDIRECT_URI,
code: authorizationCode
})
});
const { access_token, refresh_token, expires_in } = await tokenResponse.json();
```
---
## API de CRM Objects: contactos, empresas y deals
La API de CRM Objects es la más utilizada de HubSpot. Permite crear, leer, actualizar y eliminar contactos, empresas, deals, tickets y custom objects.
### Crear un contacto
```javascript
const hubspot = require('@hubspot/api-client');
const client = new hubspot.Client({ accessToken: process.env.HUBSPOT_ACCESS_TOKEN });
// Crear un contacto
const contactResponse = await client.crm.contacts.basicApi.create({
properties: {
email: 'john.doe@example.com',
firstname: 'John',
lastname: 'Doe',
phone: '+34 600 000 000',
company: 'Acme Corp',
jobtitle: 'Marketing Director'
}
});
console.log('Contact created:', contactResponse.id);
```
### Buscar contactos
```javascript
// Buscar contactos por email
const searchResponse = await client.crm.contacts.searchApi.doSearch({
filterGroups: [{
filters: [{
propertyName: 'email',
operator: 'EQ',
value: 'john.doe@example.com'
}]
}],
properties: ['email', 'firstname', 'lastname', 'phone'],
limit: 10
});
const contacts = searchResponse.results;
```
### Actualizar un contacto
```javascript
// Actualizar propiedades de un contacto
await client.crm.contacts.basicApi.update(contactId, {
properties: {
lifecyclestage: 'customer',
hs_lead_status: 'IN_PROGRESS'
}
});
```
### Crear una asociación entre objetos
```javascript
// Asociar un contacto con una empresa
await client.crm.associations.v4.basicApi.create(
'contacts',
contactId,
'companies',
companyId,
[{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 279 }]
);
```
---
## API de Marketing: emails, formularios y landing pages
### Enviar un email de marketing
```javascript
// Enviar un email transaccional
const emailResponse = await client.marketing.transactional.singleSendApi.sendEmail({
emailId: 12345,
message: {
to: 'john.doe@example.com',
from: 'noreply@tuempresa.com',
replyTo: 'hola@tuempresa.com'
},
customProperties: {
first_name: 'John',
company_name: 'Acme Corp'
}
});
```
### Obtener envíos de formularios
```javascript
// Obtener los envíos de un formulario específico
const submissionsResponse = await client.marketing.forms.formsApi.getPage();
const forms = submissionsResponse.results;
// Obtener los envíos de un formulario específico
const formSubmissions = await fetch(
`https://api.hubapi.com/form-integrations/v1/submissions/forms/${formId}`,
{ headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } }
);
```
---
## Webhooks de HubSpot
Los webhooks de HubSpot permiten recibir notificaciones en tiempo real cuando ocurren eventos en HubSpot (creación de contactos, cambios de propiedades, envíos de formularios, etc.).
### Configurar un webhook
```javascript
// Crear una suscripción a webhooks
const webhookResponse = await client.webhooks.subscriptionsApi.create({
eventType: 'contact.creation',
propertyName: 'email',
active: true
});
```
### Procesar eventos de webhook
```javascript
// Express.js endpoint para recibir webhooks de HubSpot
app.post('/webhooks/hubspot', express.json(), (req, res) => {
const events = req.body;
for (const event of events) {
console.log('Event type:', event.subscriptionType);
console.log('Object ID:', event.objectId);
console.log('Property:', event.propertyName);
console.log('New value:', event.propertyValue);
// Procesar el evento según su tipo
switch (event.subscriptionType) {
case 'contact.creation':
handleNewContact(event.objectId);
break;
case 'deal.propertyChange':
handleDealChange(event.objectId, event.propertyName, event.propertyValue);
break;
}
}
res.status(200).send('OK');
});
```
---
## API de CMS: páginas, blogs y archivos
### Crear un blog post
```javascript
// Crear un blog post en HubSpot CMS
const blogPostResponse = await client.cms.blogPosts.blogPostsApi.create({
contentGroupId: BLOG_ID,
name: 'Título del artículo',
slug: 'titulo-del-articulo',
htmlTitle: 'Título del artículo - Blog de Emovere',
metaDescription: 'Descripción del artículo para SEO',
postBody: 'Contenido del artículo en HTML
',
featuredImage: 'https://cdn.example.com/imagen.jpg',
state: 'PUBLISHED',
publishDate: new Date().toISOString()
});
```
### Subir un archivo
```javascript
// Subir un archivo al File Manager de HubSpot
const formData = new FormData();
formData.append('file', fileBuffer, { filename: 'imagen.jpg', contentType: 'image/jpeg' });
formData.append('folderPath', '/blog-images');
formData.append('options', JSON.stringify({ access: 'PUBLIC_INDEXABLE' }));
const fileResponse = await fetch('https://api.hubapi.com/files/v3/files', {
method: 'POST',
headers: { Authorization: `Bearer ${ACCESS_TOKEN}` },
body: formData
});
```
---
## Límites de la API y gestión de rate limiting
HubSpot impone límites de uso de la API según el plan:
| Plan | Límite diario | Límite por 10 segundos |
|---|---|---|
| Free | 250.000 llamadas/día | 100 llamadas/10s |
| Starter | 500.000 llamadas/día | 150 llamadas/10s |
| Professional | 1.000.000 llamadas/día | 200 llamadas/10s |
| Enterprise | 2.000.000 llamadas/día | 300 llamadas/10s |
### Gestión del rate limiting
```javascript
// Implementar retry con exponential backoff
async function apiCallWithRetry(apiCall, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
return await apiCall();
} catch (error) {
if (error.code === 429) {
// Rate limit exceeded - esperar y reintentar
const retryAfter = error.response?.headers?.['retry-after'] || Math.pow(2, attempt);
console.log(`Rate limited. Retrying in ${retryAfter} seconds...`);
await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
} else {
throw error;
}
}
}
throw new Error('Max retries exceeded');
}
```
---
## Mejores prácticas de desarrollo de integraciones
**1. Usa el SDK oficial de HubSpot.** El SDK oficial de HubSpot para Node.js (`@hubspot/api-client`) simplifica la autenticación, el manejo de errores y el rate limiting.
**2. Implementa idempotencia.** Las integraciones deben ser idempotentes: procesar el mismo evento múltiples veces no debe crear duplicados ni efectos secundarios.
**3. Gestiona los errores correctamente.** Implementa retry con exponential backoff para los errores 429 (rate limit) y 5xx (errores del servidor).
**4. Usa webhooks en lugar de polling.** Los webhooks son más eficientes que el polling para recibir actualizaciones en tiempo real.
**5. Almacena los tokens de forma segura.** Nunca almacenes los tokens de acceso en el código fuente. Usa variables de entorno o un gestor de secretos.
**6. Implementa logging y monitorización.** Registra todas las llamadas a la API y los errores para facilitar la depuración.
---
## Publicar una integración en el HubSpot Marketplace
El HubSpot Marketplace tiene más de 1.500 integraciones y es una excelente fuente de leads para desarrolladores y agencias. Para publicar una integración:
1. **Crea una cuenta de desarrollador** en developers.hubspot.com.
2. **Crea una aplicación** y configura el flujo de OAuth 2.0.
3. **Desarrolla y prueba** la integración en una cuenta de sandbox.
4. **Envía la integración** para revisión por parte del equipo de HubSpot.
5. **Publica la integración** en el Marketplace.
---
## Preguntas Frecuentes
**¿Cuál es la diferencia entre la API v1 y la API v3 de HubSpot?**
HubSpot ha migrado gradualmente de la API v1 (basada en endpoints específicos por tipo de objeto) a la API v3 (basada en CRM Objects con endpoints genéricos). En 2026, la API v3 es la recomendada para nuevas integraciones.
**¿Puedo usar la API de HubSpot de forma gratuita?**
Sí, la API de HubSpot está disponible para todos los planes, incluyendo el gratuito. Los límites de uso varían según el plan.
**¿HubSpot tiene una API GraphQL?**
No, HubSpot no ofrece una API GraphQL. Todas las APIs de HubSpot son REST.
**¿Puedo crear custom objects con la API de HubSpot?**
Sí, la API de Custom Objects de HubSpot permite crear, leer, actualizar y eliminar custom objects programáticamente. Los custom objects requieren HubSpot Enterprise.
**¿Cómo puedo probar la API de HubSpot sin afectar datos reales?**
HubSpot ofrece cuentas de sandbox (disponibles en Enterprise) y cuentas de desarrollador gratuitas para probar integraciones sin afectar datos reales.
---
## Conclusión
La API de HubSpot es una herramienta poderosa para integrar sistemas externos, automatizar procesos y crear aplicaciones que se publiquen en el HubSpot Marketplace. Con más de 100 endpoints bien documentados y un SDK oficial para Node.js, desarrollar integraciones con HubSpot es más accesible que nunca en 2026.
En Emovere somos especialistas en el desarrollo de integraciones con la API de HubSpot. Si necesitas integrar HubSpot con tus sistemas, contacta con nuestro equipo.
---
## Referencias
[1] HubSpot — API Documentation. https://developers.hubspot.com/docs/api/overview — Documentación oficial de la API de HubSpot.
[2] HubSpot — Node.js SDK. https://github.com/HubSpot/hubspot-api-nodejs — SDK oficial de HubSpot para Node.js.
[3] HubSpot — OAuth 2.0 Documentation. https://developers.hubspot.com/docs/api/working-with-oauth — Documentación de OAuth 2.0 de HubSpot.
[4] HubSpot — Webhooks Documentation. https://developers.hubspot.com/docs/api/webhooks — Documentación de webhooks de HubSpot.
[5] HubSpot — Marketplace Developer Documentation. https://developers.hubspot.com/docs/marketplace — Documentación para publicar en el HubSpot Marketplace.
