> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API del CRM | Asociaciones v4
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requiere uno de los siguientes ámbitos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
# Asociaciones v4
Para la versión anterior, consulta la documentación de la [API de asociaciones v3](/api-reference/crm-associations-v3/guide).
Las asociaciones representan las relaciones entre objetos y actividades en el CRM. Pueden existir asociaciones de registros entre registros de diferentes objetos (por ejemplo, contacto con empresa), así como de un mismo objeto (por ejemplo, empresa con empresa). Puedes usar los puntos de terminación de asociaciones para crear, obtener, actualizar o eliminar asociaciones entre registros o entre registros y actividades.
Los puntos de terminación del esquema de asociaciones te permiten ver los tipos de asociaciones admitidos en tu cuenta, así como crear tus propios tipos de asociaciones y asignar etiquetas a las relaciones de los registros. Se admiten etiquetas de asociación entre contactos, empresas, negocios, tickets y objetos personalizados, y se pueden [usar en herramientas de HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#use-association-labels-in-hubspot-tools), como listas y workflows.
Obtén más información sobre las API de objetos, registros, propiedades y asociaciones en la guía [Comprender el CRM](/guides/crm/understanding-the-crm).
**Nota**: La API de asociaciones v4 es compatible con la versión 9.0.0 o posterior del cliente NodeJS HubSpot.
## Tipos de asociaciones definidos por HubSpot
HubSpot proporciona un conjunto de tipos de asociaciones predefinidos (por ejemplo, contacto con empresa sin etiqueta), pero los administradores de cuentas pueden [definir sus propias etiquetas de asociación](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) para proporcionar información adicional de las relaciones entre los registros (por ejemplo, mánager y empleado). Existen dos tipos de asociaciones definidas por HubSpot:
* **Principal:** la empresa principal con la que está asociado el otro registro. Las asociaciones principales se pueden utilizar en herramientas de HubSpot, como [listas y workflows](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#use-associations-in-hubspot-tools). En los registros con varias empresas asociadas, esta API permite cambiar cuál empresa se considera la principal.
* **Sin etiqueta:** un tipo de asociación agregado cuando se asocia cualquier contacto, empresa, negocio, ticket o registro de objeto personalizado. Este tipo indica que existe una asociación y siempre se devolverá en las respuestas con un valor de **etiqueta** de `null`. Cuando un registro tiene una asociación principal o una etiqueta de asociación personalizada, esos tipos se enumerarán junto con el tipo de asociación sin etiqueta.
Puedes ver todos los tipos de asociaciones definidos por HubSpot en [esta sección](#association-type-id-values).
## Etiquetas individuales vs. emparejadas
Hay dos tipos de [etiquetas de asociación](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) que puedes usar para describir las relaciones entre registros:
* **Individual:** una etiqueta que se aplica a ambos registros en la relación. Por ejemplo, *Amigo* o *Colega*.
* **Emparejadas**: un par de etiquetas para cuando se utilizan diferentes palabras para describir cada lado de la relación de los registros asociados. Por ejemplo, *Padre* e *Hijo* o *Empleador* y *Empleado*. Para crear etiquetas emparejadas, debes incluir el campo `inverseLabel` en la solicitud para darle un nombre a la segunda etiqueta en el par.
## Crear tipos de asociaciones
Puedes crear tipos de asociaciones personalizadas [en HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) o a través del punto de terminación de la API del esquema de asociaciones. Puedes crear hasta 10 tipos de asociaciones entre cada par de objetos (por ejemplo, contactos y empresas, contactos y contactos).
Para crear un tipo de asociación a través de la API, haz una solicitud `POST` a `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels` e incluye lo siguiente:
* **nombre**: el nombre interno del tipo de asociación. Este valor no puede incluir guiones ni comenzar con un carácter numérico.
* **etiqueta**: el nombre de la [etiqueta de asociación tal como se muestra en HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels).
* **inverseLabel** (solo etiquetas emparejadas): el nombre de la segunda etiqueta del par de etiquetas.
Por ejemplo, tu solicitud podría tener un aspecto similar al siguiente:
```json theme={null}
///Example request body - Single label
{
"label": "Partner",
"name": "partner"
}
```
```json theme={null}
///Example request body - Paired labels
{
"label": "Manager",
"inverseLabel": "Employee",
"name": "manager_employee"
}
```
## Obtener tipos de asociaciones
Para ver los tipos de asociaciones entre objetos específicos, haz una solicitud `GET` a `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`.
Recibirás una matriz en la que cada elemento contiene:
* **categoría:** si el tipo de asociación fue creado por HubSpot (`HUBSPOT_DEFINED`) o por un usuario (`USER_DEFINED`).
* **typeId:** el ID numérico de ese tipo de asociación. Se utiliza para [definir una etiqueta al asociar registros](#associate-with-label). Consulta [esta lista](#association-type-id-values) para ver todos los valores `typeId` definidos por HubSpot.
* **etiqueta:** la etiqueta alfanumérica. Será `null` para el tipo de asociación sin etiqueta.
También puedes encontrar estos valores en HubSpot en la [configuración de asociaciones](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#association-label-api-details).
## Asociar registros
### Asociar registros sin etiquetas
Puedes crear una asociación sin etiqueta predeterminada entre dos registros o configurar asociaciones sin etiqueta para registros en bloque. Para configurar una asociación individual predeterminada entre dos registros, haz una solicitud `PUT` a
`/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}`
En la URL de la solicitud, incluye:
* `fromObjectType`**:** el ID del objeto que estás asociando. Para encontrar los valores de ID, consulta esta [lista de ID de tipos de objetos,](/guides/crm/understanding-the-crm#object-type-id) o, para contactos, empresas, negocios, tickets y notas, puedes usar el nombre del objeto (por ejemplo, `contact`, `company`).
* `fromObjectId`**:** el ID del registro que se asociará.
* `toObjectType`**:** el ID del objeto con el que estás asociando el registro. Para encontrar los valores de ID, consulta esta [lista de ID de tipos de objetos,](/guides/crm/understanding-the-crm#object-type-id) o, para contactos, empresas, negocios, tickets y notas, puedes usar el nombre del objeto (por ejemplo, `contact`, `company`).
* `toObjectId`**:** el ID del registro con el que se va a hacer la asociación
Por ejemplo, para asociar un registro de contacto cuyo ID es 12345 con un registro de empresa cuyo ID es `67891`, la URL de tu solicitud sería: `/crm/v4/objects/contact/12345/associations/default/company/67891`.
Para configurar asociaciones predeterminadas en bloque, haz una solicitud `POST` a `crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default`. En el cuerpo de la solicitud, incluye valores `objectId` para los registros que quieres asociar.
**Nota**: El número de asociaciones que puede tener un registro depende [del objeto y de tu suscripción a HubSpot.](https://legal.hubspot.com/hubspot-product-and-services-catalog#TechnicalLimits:~:text=CRM%20Record%20Association%20Limits)
### Asociar registros con etiquetas
Para asociar dos registros y definir una etiqueta para describir la asociación, haz una solicitud `PUT` a `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}`. En el cuerpo de la solicitud, incluye `associationCategory` y `associationTypeId` para indicar el tipo de asociación que quieres crear.
Si estás creando asociaciones sin etiqueta, puedes usar los puntos de terminación predeterminados descritos en la [sección anterior](#associate-records-without-a-label) que no requieren `associationCategory` ni `associationTypeId`. Si estás creando asociaciones con una etiqueta, puedes consultar esta [lista de ID de tipos predeterminados](#association-type-id-values) o tendrás que obtener los tipos de asociaciones personalizados entre esos objetos.
**Nota**: En cuanto a las relaciones de etiquetas multiobjeto y emparejadas, asegúrate de usar el `typeId` que se refiere a la dirección correcta (por ejemplo, contacto a empresa vs. empresa a contacto, empleado a mánager vs. mánager a empleado).
Por ejemplo, para asociar un contacto con un negocio usando una etiqueta personalizada:
1\. Haz una solicitud `GET` a `/crm/v4/associations/contact/deal/labels`.
2\. En la respuesta, fíjate en los valores `typeId` y `category` de la etiqueta. El ID será un número (por ejemplo, `36`), y la categoría siempre será `USER_DEFINED` para las etiquetas personalizadas.
3\. Haz una solicitud `PUT` a `/crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}`con el siguiente cuerpo:
```json theme={null}
/// Example request body
[
{
"associationCategory": "USER_DEFINED",
"associationTypeId": 36
}
]
```
## Definir y gestionar límites de asociaciones
Puedes definir [límites](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations) para el número de registros asociados entre objetos o la frecuencia con la que se puede utilizar una etiqueta para describir asociaciones. También hay [límites técnicos y límites basados en tu suscripción de HubSpot](https://legal.hubspot.com/hubspot-product-and-services-catalog).
### Crear o actualizar límites de asociaciones
Puedes crear límites de asociaciones nuevos o actualizar los existentes entre los objetos.
* Para crear límites, haz una solicitud `POST` a `crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create`.
* Para actualizar los límites existentes, haz una solicitud `POST` a `crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update`.
En el cuerpo de la solicitud, incluye `inputs` con lo siguiente:
| Parámetro | Descripción |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | La categoría de la asociación para la que estás fijando un límite, ya sea `HUBSPOT_DEFINED` o `USER_DEFINED`. |
| `typeId` | El ID numérico del tipo de asociación para la que quieres fijar un límite. Consulta [esta lista](#association-type-id-values) de valores `typeId` predeterminados u [obtén el valor](#retrieve-association-types) de las etiquetas personalizadas. |
| `maxToObjectIds` | El número máximo de asociaciones permitido para el tipo de asociación. |
Por ejemplo, para fijar límites para que un negocio se pueda asociar con un máximo de cinco contactos con un solo contacto con la etiqueta *punto de contacto* en un negocio, tu solicitud debería lucir así:
```json theme={null}
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/create
{
"inputs": [
{
"category": "HUBSPOT_DEFINED",
"typeId": 3,
"maxToObjectIds": 5
},
{
"category": "USER_DEFINED",
"typeId": 35,
"maxToObjectIds": 1
}
]
}
```
### Obtener límites de asociaciones
* Para leer todos los límites de asociaciones definidos, haz una solicitud `GET` a `/crm/v4/associations/definitions/configurations/all`. Se devolverán los límites de asociaciones definidos en todos los objetos.
* Para leer límites de asociaciones entre dos objetos específicos, haz una solicitud `GET` a `/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}`.
En ambas solicitudes, la respuesta devolverá los valores de las asociaciones para `category`, `typeId`, `maxToObjectIds` y `label`. Por ejemplo, si se obtienen los límites entre negocios y contactos, la respuesta sería similar a:
```json theme={null}
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
"results": [
{
"category": "HUBSPOT_DEFINED",
"typeId": 3,
"userEnforcedMaxToObjectIds": 5,
"label": null
}
]
}
```
### Eliminar límites de asociaciones
Para eliminar límites de asociaciones específicos, haz una solicitud `POST` a `/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge`. En el cuerpo de la solicitud, incluye los valores `category` y `typeId` de los tipos de asociaciones para los cuáles quieres eliminar los límites.
Por ejemplo, para eliminar el límite *Punto de contacto* entre negocios y contactos, la solicitud luciría de esta forma:
```json theme={null}
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
"inputs": [
{
"category": "USER_DEFINED",
"typeId": 35
}
]
}
```
Si se hace correctamente, recibirás una respuesta 204 y el límite incluido volverá al valor predeterminado del sistema (es decir, Muchos contactos pueden tener la etiqueta *Punto de contact*).
## Informes sobre alto uso de asociaciones
Existen límites técnicos [en cuanto al número de asociaciones que puede tener un registro](https://legal.hubspot.com/hubspot-product-and-services-catalog). Puedes usar la API de asociaciones para obtener un informe de los registros que se están aproximando al máximo límite de asociaciones o que ya lo alcanzaron.
Para obtener el informe, haz una solicitud `POST` a `crm/v4/associations/usage/high-usage-report/{userID}`. El archivo incluye registros que usan el 80% o más de su límite de asociaciones. Por ejemplo, si se puede asociar una empresa con hasta 50.000 contactos, la empresa se incluirá en el archivo si tiene 40.000 o más registros asociados. El archivo se enviará al correo del usuario cuyo ID se incluyó en la URL de la solicitud. Descubre cómo obtener ID de usuario con la [API de usuarios](/api-reference/settings-user-provisioning-v3/guide).
## Valores de ID de tipos de asociaciones
Las siguientes tablas incluyen los valores `associationTypeId` definidos por HubSpot que especifican el tipo de asociación. Los tipos de asociaciones varían dependiendo de los objetos incluidos y de la dirección de la asociación (por ejemplo, contacto a empresa es diferente de empresa a contacto). Si creas objetos personalizados o etiquetas de asociaciones personalizadas, los tipos de asociaciones relacionados tendrán valores `typeId` únicos que deberás [obtener](#retrieve-association-type) o localizar en la [configuración de asociaciones de HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#association-label-api-details).
**Nota**: Los tipos de asociaciones de empresas predeterminadas incluyen un tipo de asociación sin etiqueta y un tipo de asociación principal. Si un registro tiene más de una empresa asociada, solo una puede ser la empresa principal. Las otras asociaciones pueden ser sin etiqueta o tener etiquetas de asociación personalizadas.
#### Contacto a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ---------------------------------------------------------------- |
| `449` | Contacta a contacto |
| `279` | Contacto a empresa |
| `1` | Contacto a empresa (principal) |
| `4` | Contacto a negocio |
| `15` | Contacto a ticket |
| `193` | Contacto a llamada |
| `197` | Contacto a correo |
| `199` | Contacto a reunión |
| `201` | Contacto a nota |
| `203` | Contacto a tarea |
| `82` | Contacto a comunicación (mensaje SMS, de WhatsApp o de LinkedIn) |
| `454` | Contacto a correo postal |
| `587` | Contacto a carrito |
| `508` | Contacto a pedido |
| `178` | Contacto a factura |
| `388` | Contacto a pago |
| `296` | Contacto a suscripción |
#### Empresa a objeto
| ID de tipo | Tipo de asociación |
| ---------- | --------------------------------------------------------------- |
| `450` | Empresa a empresa |
| `14` | Empresa secundaria a empresa principal |
| `13` | Empresa principal a empresa secundaria |
| `280` | Empresa a contacto |
| `2` | Empresa a contacto (principal) |
| `342` | Empresa a negocio |
| `6` | Empresa a negocio (principal) |
| `340` | Empresa a ticket |
| `25` | Empresa a ticket (principal) |
| `181` | Empresa a llamada |
| `185` | Empresa a correo |
| `187` | Empresa a reunión |
| `189` | Empresa a nota |
| `191` | Empresa a tarea |
| `88` | Empresa a comunicación (mensaje SMS, de WhatsApp o de LinkedIn) |
| `460` | Empresa a correo postal |
| `180` | Empresa a factura |
| `510` | Empresa a pedido |
| `390` | Empresa a pago |
| `298` | Empresa a suscripción |
#### Negocio a objeto
| ID de tipo | Tipo de asociación |
| ---------- | --------------------------------------------------------------- |
| `451` | Negocio a negocio |
| `3` | Negocio a contacto |
| `341` | Negocio a empresa |
| `5` | Negocio a empresa (principal) |
| `27` | Negocio a ticket |
| `205` | Negocio a llamada |
| `209` | Negocio a correo |
| `211` | Negocio a reunión |
| `213` | Negocio a nota |
| `215` | Negocio a tarea |
| `86` | Negocio a comunicación (mensaje SMS, de WhatsApp o de LinkedIn) |
| `458` | Negocio a correo postal |
| `313` | Negocio a división del negocio |
| `19` | Negocio a elemento de pedido |
| `176` | Negocio a factura |
| `511` | Negocio a pedido |
| `392` | Negocio a pago |
| `630` | Negocio a producto |
| `63` | Negocio a cotización |
| `300` | Negocio a suscripción |
#### Ticket a objeto
| ID de tipo | Tipo de asociación |
| ---------- | -------------------------------------------------------------- |
| `452` | Ticket a ticket |
| `16` | Ticket a contacto |
| `339` | Ticket a empresa |
| `26` | Ticket a empresa (principal) |
| `28` | Ticket a negocio |
| `219` | Ticket a llamada |
| `223` | Ticket a correo |
| `225` | Ticket a reunión |
| `227` | Ticket a nota |
| `229` | Ticket a tarea |
| `84` | Ticket a comunicación (mensaje SMS, de WhatsApp o de LinkedIn) |
| `456` | Ticket a correo postal |
| `32` | Ticket a cadena |
| `278` | Ticket a conversación |
| `526` | Ticket a pedido |
### Lead a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------------- |
| `578` | Lead a contacto principal |
| `596` | Lead a llamada |
| `598` | Lead a correo |
| `600` | Lead a reunión |
| `602` | Lead a comunicación |
| `608` | Lead a contacto |
| `610` | Lead a empresa |
| `646` | Lead a tarea |
#### Llamada a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------ |
| `194` | Llamada a contacto |
| `182` | Llamada a empresa |
| `206` | Llamada a negocio |
| `220` | Llamada a ticket |
#### Correo a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------ |
| `198` | Correo a contacto |
| `186` | Correo a empresa |
| `210` | Correo a negocio |
| `224` | Correo a ticket |
#### Reunión a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------ |
| `200` | Reunión a contacto |
| `188` | Reunión a empresa |
| `212` | Reunión a negocio |
| `226` | Reunión a ticket |
#### Nota a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------ |
| `202` | Nota a contacto |
| `190` | Nota a empresa |
| `214` | Nota a negocio |
| `228` | Nota a ticket |
#### Correo postal a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------------ |
| `453` | Correo postal a contacto |
| `459` | Correo postal a empresa |
| `457` | Correo postal a negocio |
| `455` | Correo postal a ticket |
#### Cotización a objeto
| ID de tipo | Tipo de asociación |
| ---------- | -------------------------------------------- |
| `69` | Cotización a contacto |
| `71` | Cotización a empresa |
| `64` | Cotización a negocio |
| `67` | Cotización a elemento de pedido |
| `286` | Cotización a plantilla de cotización |
| `362` | Cotización a descuento |
| `364` | Cotización a tarifa |
| `366` | Cotización a impuestos |
| `702` | Contacto firmante (para firmas electrónicas) |
| `733` | Cotización a carrito |
| `408` | Cotización a factura |
| `731` | Cotización a pedido |
| `398` | Cotización a pago |
| `304` | Cotización a suscripción |
#### Tarea a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ------------------ |
| `204` | Tarea a contacto |
| `192` | Tarea a empresa |
| `216` | Tarea a negocio |
| `230` | Tarea a ticket |
#### Comunicación (mensaje SMS, de WhatsApp o de LinkedIn) a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ---------------------------------------------------------------- |
| `81` | Comunicación (mensaje SMS, de WhatsApp o de LinkedIn) a contacto |
| `87` | Comunicación (mensaje SMS, de WhatsApp o de LinkedIn) a empresa |
| `85` | Comunicación (mensaje SMS, de WhatsApp o de LinkedIn) a negocio |
| `83` | Comunicación (mensaje SMS, de WhatsApp o de LinkedIn) a ticket |
### Pedido a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ---------------------------- |
| `593` | Pedido a carrito |
| `507` | Pedido a contacto |
| `509` | Pedido a empresa |
| `512` | Pedido a negocio |
| `519` | Pedido a descuento |
| `521` | Pedido a código de descuento |
| `518` | Pedido a factura |
| `513` | Pedido a elemento de pedido |
| `523` | Pedido a pago |
| `730` | Pedido a cotización |
| `516` | Pedido a suscripción |
| `726` | Pedido a tarea |
| `525` | Pedido a ticket |
### Carrito a objeto
| ID de tipo | Tipo de asociación |
| ---------- | ---------------------------- |
| `586` | Carrito a contacto |
| `588` | Carrito a descuento |
| `590` | Carrito a elemento de pedido |
| `592` | Carrito a pedido |
| `732` | Carrito a cotización |
| `728` | Carrito a tarea |
| `594` | Carrito a ticket |
## Asociaciones v1 (anterior)
Si estás usando la API de asociaciones v1, consulta la tabla que aparece abajo para obtener más información sobre qué ID usar al asociar registros.
| Tipo de asociación | ID |
| ---------------------------------------- | --- |
| Contacto a empresa | 1 |
| Empresa a contacto (predeterminado) | 2 |
| Empresa a contacto (todas las etiquetas) | 280 |
| Negocio a contacto | 3 |
| Contacto a negocio | 4 |
| Negocio a empresa | 5 |
| Empresa a negocio | 6 |
| Empresa a interacción | 7 |
| Interacción a empresa | 8 |
| Contacto a interacción | 9 |
| Interacción a contacto | 10 |
| Negocio a interacción | 11 |
| Interacción a negocio | 12 |
| Empresa principal a empresa secundaria | 13 |
| Empresa secundaria a empresa principal | 14 |
| Contacto a ticket | 15 |
| Ticket a contacto | 16 |
| Ticket a interacción | 17 |
| Interacción a ticket | 18 |
| Negocio a elemento de pedido | 19 |
| Elemento de pedido a negocio | 20 |
| Empresa a ticket | 25 |
| Ticket a empresa | 26 |
| Negocio a ticket | 27 |
| Ticket a negocio | 28 |