> ## Documentation Index
> Fetch the complete documentation index at: https://br.developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API do CRM | Associações v4
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requer um dos seguintes escopos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
# Associações v4
Para obter a versão anterior, consulte a documentação da [API de Associações v3](/api-reference/crm-associations-v3/guide).
As associações representam as relações entre objetos e atividades no CRM da HubSpot. Podem existir associações entre registros de diferentes objetos (por exemplo, contato para empresa), bem como dentro do mesmo objeto (por exemplo, empresa para empresa). Você pode usar os pontos de extremidade de associações para criar, recuperar, atualizar ou excluir associações entre registros ou entre registros e atividades.
Os pontos de extremidade do esquema de associação permitem que você exiba os tipos suportados de associações em sua conta, bem como crie seus próprios tipos de associação e atribua rótulos às suas relações de registros. Os rótulos de associação são aceitos entre contatos, empresas, negócios, tickets e objetos personalizados, e podem ser [usados nas ferramentas do HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#use-association-labels-in-hubspot-tools), como listas e fluxos de trabalho.
Saiba mais sobre objetos, registros, propriedades e APIs de associações no guia [Noções básicas do CRM](/guides/crm/understanding-the-crm).
**Observação**: a API de associações v4 é compatível com a versão 9.0.0 ou posterior do NodeJS HubSpot Client.
## Tipos de associação definidos pelo HubSpot
O HubSpot fornece um conjunto de tipos de associação predefinidos (por exemplo, contato sem rótulo com empresa), mas os administradores da conta podem [definir seus próprios rótulos de associação](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) para fornecer contexto adicional para relacionamentos de registros (por exemplo, gerente e funcionário). Há dois tipos de associação definidos pelo HubSpot:
* **Principal:** a empresa principal à qual o outro registro está associado. Associações principais podem ser usadas nas ferramentas da HubSpot, como [listas e fluxos de trabalho](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#use-associations-in-hubspot-tools). Para registros com várias empresas associadas, esta API aceita alterar qual empresa é considerada a principal.
* **Sem rótulo:** um tipo de associação adicionado quando um registro de contato, empresa, negociação, ticket ou objeto personalizado é associado. Este tipo indica que existe uma associação e sempre será retornado em respostas com um valor de **rótulo** `null`. Quando um registro tem uma associação principal ou um rótulo de associação personalizado, esses tipos serão listados ao lado do tipo de associação sem rótulo.
Você pode exibir todos os tipos de associação definidos pelo HubSpot [nesta seção](#association-type-id-values).
## Rótulos únicos versus pares de rótulos
Há dois tipos de [rótulos de associação](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) que você pode usar para descrever os relacionamentos entre os registros:
* **Único:** um rótulo que se aplica a ambos os registros no relacionamento. Por exemplo, *Amigo* ou *Colega*.
* **Emparelhados**: um par de rótulos para quando palavras diferentes são usadas para descrever cada lado do relacionamento dos registros associados. Por exemplo, *Principal* e *Secundário* ou *Empregador* e *Funcionário*. Para criar rótulos emparelhados, você deve incluir o campo `inverseLabel` na sua solicitação para nomear o segundo rótulo no par.
## Criar tipos de associação
Você pode criar tipos de associação personalizados [no HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels) ou por meio do ponto de extremidade da API do esquema de associação. Você pode criar até 10 tipos de associação entre cada par de objetos (por exemplo, contatos e empresas, contatos e contatos).
Para criar um tipo de associação por meio da API, faça uma solicitação `POST` para `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels` e inclua o seguinte em sua solicitação:
* **nome**: o nome interno do tipo de associação. Esse valor não pode incluir hifens ou começar com um caractere numérico.
* **rótulo**: o nome do [rótulo de associação conforme mostrado no HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels).
* **inverseLabel** (somente rótulos emparelhados): o nome do segundo rótulo no par de rótulos.
Por exemplo, sua solicitação pode ser semelhante a esta:
```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"
}
```
## Recuperar tipos de associação
Para exibir os tipos de associação entre objetos específicos, faça uma solicitação `GET` para `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`.
Você receberá uma matriz, sendo que cada item conterá:
* **categoria:** se o tipo de associação foi criado pelo HubSpot (`HUBSPOT_DEFINED`) ou por um usuário (`USER_DEFINED`).
* **typeId:** o ID numérico para esse tipo de associação. Isso é usado para [definir um rótulo ao associar registros](#associate-with-label). Consulte [esta lista](#association-type-id-values) para ver todos os valores `typeId` definidos pelo HubSpot.
* **rótulo:** o rótulo alfanumérico. Isso será `null` para o tipo de associação sem rótulo.
Você também pode encontrar esses valores no HubSpot [em suas configurações de associação](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#association-label-api-details).
## Associar registros
### Associar registros sem um rótulo
Você pode criar uma associação padrão sem rótulo entre dois registros ou configurar associações sem rótulo para registros em massa. Para configurar uma associação padrão individual entre dois registros, faça uma solicitação `PUT` para
`/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}`
No URL da solicitação, inclua:
* `fromObjectType`**:** o ID do objeto que você está associando. Para localizar os valores de ID, consulte esta [lista de IDs de tipo de objeto,](/guides/crm/understanding-the-crm#object-type-id) ou, para contatos, empresas, negócios, tickets e observações, você pode usar o nome do objeto (por exemplo, `contact`, `company`).
* `fromObjectId`**:** o ID do registro a associar.
* `toObjectType`**:** o ID do objeto ao qual você está associando o registro. Para localizar os valores de ID, consulte esta [lista de IDs de tipo de objeto,](/guides/crm/understanding-the-crm#object-type-id) ou, para contatos, empresas, negócios, tickets e observações, você pode usar o nome do objeto (por exemplo, `contact`, `company`).
* `toObjectId`**:** o ID do registro ao qual associar.
Por exemplo, para associar um registro de contato cuja ID é 12345 a um registro de empresa cuja ID é `67891`, o URL da solicitação seria: `/crm/v4/objects/contact/12345/associations/default/company/67891`.
Para configurar associações padrão em massa, faça uma solicitação `POST` para `crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default`. No corpo da solicitação, inclua valores de `objectId` para os registros que você deseja associar.
**Observação**: o número de associações que um registro pode ter depende do[ objeto e da sua assinatura do HubSpot](https://legal.hubspot.com/hubspot-product-and-services-catalog#TechnicalLimits:~:text=CRM%20Record%20Association%20Limits).
### Associar registros com um rótulo
Para associar dois registros e definir um rótulo para descrever a associação, faça uma solicitação `PUT` para `/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}`. No corpo da solicitação, inclua `associationCategory` e `associationTypeId` para indicar o tipo de associação que você deseja criar.
Se você estiver criando associações sem rótulo, poderá usar os pontos de extremidade padrão descritos na [seção acima](#associate-records-without-a-label) que não exijam `associationCategory` ou `associationTypeId`. Se você estiver criando associações com um rótulo, poderá consultar esta [lista de IDs de tipo padrão](#association-type-id-values), ou precisará recuperar os tipos de associação personalizados entre esses objetos.
**Observação**: para relações entre objetos e rótulos emparelhados, certifique-se de usar o `typeId` que se refere à direção correta (por exemplo, Contato para Empresa vs. Empresa para Contato, Funcionário para Gerente vs. Gerente para Funcionário).
Por exemplo, para associar um contato a um negócio usando um rótulo personalizado:
1\. Faça uma solicitação `GET` para `/crm/v4/associations/contact/deal/labels`.
2\. Na resposta, observe os valores `typeId` e `category` para o rótulo. O ID será um número (por exemplo, `36`) e a categoria será sempre `USER_DEFINED` para rótulos personalizados.
3\. Envie uma solicitação `PUT` para `/crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}` com o seguinte corpo de solicitação:
```json theme={null}
/// Example request body
[
{
"associationCategory": "USER_DEFINED",
"associationTypeId": 36
}
]
```
## Definir e gerenciar limites de associação
Você pode configurar [limites](https://knowledge.hubspot.com/object-settings/set-limits-for-record-associations) para o número de registros associados entre objetos ou a frequência com que um rótulo pode ser usado para descrever associações. Há também [limites técnicos e limites baseados na sua assinatura do HubSpot](https://legal.hubspot.com/hubspot-product-and-services-catalog).
### Criar ou atualizar limites de associação
Você pode criar limites de associação novos ou atualizar os limites de associação existentes entre objetos.
* Para criar limites, faça uma solicitação `POST` para `crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create`.
* Para atualizar os limites existentes, faça uma solicitação `POST` para `crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update`.
No corpo da solicitação, inclua `inputs` com o seguinte:
| Descrição | Parâmetro |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | A categoria da associação para a qual você está definindo um limite `HUBSPOT_DEFINED` ou `USER_DEFINED`. |
| `typeId` | O ID numérico do tipo de associação para o qual você deseja definir um limite. Consulte [esta lista](#association-type-id-values) de valores `typeId` padrão ou [recupere o valor](#retrieve-association-types) para rótulos personalizados. |
| `maxToObjectIds` | O número máximo de associações permitidas para o tipo de associação. |
Por exemplo, para definir limites em que um negócio pode ser associado a um máximo de cinco contatos com apenas um contato rotulado como *Ponto de contato*, sua solicitação se pareceria com a seguinte:
```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
}
]
}
```
### Recuperar limites de associação
* Para ler todos os limites de associação definidos, faça uma solicitação `GET` para `/crm/v4/associations/definitions/configurations/all`. Isso retornará limites de associação personalizados definidos em todos os objetos.
* Para ler os limites de associação entre dois objetos específicos, faça uma solicitação `GET` para `/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}`.
Para ambas as solicitações, a resposta retornará os valores das associações para `category`, `typeId`, `maxToObjectIds` e `label`. Por exemplo, ao recuperar limites entre negócios e contatos, a resposta seria semelhante à seguinte:
```json theme={null}
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
"results": [
{
"category": "HUBSPOT_DEFINED",
"typeId": 3,
"userEnforcedMaxToObjectIds": 5,
"label": null
}
]
}
```
### Excluir limites de associação
Para excluir limites de associação específicos, faça uma solicitação `POST` para `/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge`. No corpo da solicitação, inclua os valores de `category` e `typeId` dos tipos de associação para os quais você deseja remover os limites.
Por exemplo, para remover o limite de *Pontos de contato* entre negócios e contatos, a solicitação seria semelhante à seguinte:
```json theme={null}
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
"inputs": [
{
"category": "USER_DEFINED",
"typeId": 35
}
]
}
```
Se for bem-sucedido, você receberá uma resposta 204 e o limite incluído retornará ao padrão do sistema (ou seja, muitos contatos podem ter o rótulo *Ponto de contact*).
## Gerar relatório sobre alto uso de associações
Há [limites técnicos para o número de associações que um registro pode ter](https://legal.hubspot.com/hubspot-product-and-services-catalog). Você pode usar a API de associações para recuperar um relatório de registros que estão se aproximando ou atingiram o limite máximo de associações.
Para recuperar o relatório, faça uma solicitação `POST` para `crm/v4/associations/usage/high-usage-report/{userID}`. O arquivo inclui registros que usam 80% ou mais de seu limite de associação. Por exemplo, se uma empresa puder ser associada a até 50.000 contatos, ela será incluída no arquivo se tiver 40.000 contatos associados ou mais. O arquivo será enviado para o e-mail do usuário cujo ID foi incluído no URL da solicitação. Saiba como recuperar IDs de usuário com a [API de usuários](/api-reference/settings-user-provisioning-v3/guide).
## Valores de ID de tipo de associação
As tabelas a seguir incluem os valores `associationTypeId` definidos pelo HubSpot que especificam o tipo de associação. Os tipos de associação variam dependendo dos objetos incluídos e da direção da associação (por exemplo, Contato para Empresa é diferente de Empresa para Contato). Se você criar objetos personalizados ou rótulos de associação personalizados, os tipos de associação relacionados terão valores `typeId` que precisarão ser [recuperados](#retrieve-association-type) ou localizados nas [configurações de associação no HubSpot](https://knowledge.hubspot.com/object-settings/create-and-use-association-labels#association-label-api-details).
**Observação**: os tipos de associação de empresa padrão incluem um tipo de associação sem rótulo e um tipo de associação principal. Se um registro tiver mais de uma empresa associada, somente uma poderá ser a empresa principal. As outras associações podem não ter rótulo ou ter rótulos de associação personalizados.
#### Contato para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ---------------------------------------------------------------- |
| `449` | Contato para contato |
| `279` | Contato para empresa |
| `1` | Contato para empresa (Principal) |
| `4` | Contato para negócio |
| `15` | Contato para ticket |
| `193` | Contato para chamada |
| `197` | Contato para e-mail |
| `199` | Contato para reunião |
| `201` | Contato para observação |
| `203` | Contato para tarefa |
| `82` | Contato para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
| `454` | Contato para correio postal |
| `587` | Contato para carrinho |
| `508` | Contato para pedido |
| `178` | Contato para fatura |
| `388` | Contato para pagamento |
| `296` | Contato para assinatura |
#### Empresa para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ---------------------------------------------------------------- |
| `450` | Empresa para empresa |
| `14` | Empresa afiliada para empresa matriz |
| `13` | Empresa matriz para afiliada |
| `280` | Empresa para contato |
| `2` | Empresa para contato (Principal) |
| `342` | Empresa para negócio |
| `6` | Empresa para negócio (Principal) |
| `340` | Empresa para ticket |
| `25` | Empresa para ticket (Principal) |
| `181` | Empresa para chamada |
| `185` | Empresa para e-mail |
| `187` | Empresa para reunião |
| `189` | Empresa para observação |
| `191` | Empresa para tarefa |
| `88` | Empresa para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
| `460` | Empresa para correio postal |
| `180` | Empresa para fatura |
| `510` | Empresa para pedido |
| `390` | Empresa para pagamento |
| `298` | Empresa para assinatura |
#### Negócio para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ---------------------------------------------------------------- |
| `451` | Negócio para negócio |
| `3` | Negócio para contato |
| `341` | Negócio para empresa |
| `5` | Negócio para empresa (Principal) |
| `27` | Negócios para ticket |
| `205` | Negócio para chamada |
| `209` | Negócio para e-mail |
| `211` | Negócio para reunião |
| `213` | Negócio para observação |
| `215` | Negócio para tarefa |
| `86` | Negócio para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
| `458` | Negócio para correio postal |
| `313` | Negócio para divisão de negócio |
| `19` | Negócio para item de linha |
| `176` | Negócio para fatura |
| `511` | Negócio para pedido |
| `392` | Negócio para pagamento |
| `630` | Negócio para produto |
| `63` | Negócio para orçamento |
| `300` | Negócio para assinatura |
#### Ticket para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | --------------------------------------------------------------- |
| `452` | Ticket para ticket |
| `16` | Ticket para contato |
| `339` | Empresa para ticket |
| `26` | Ticket para empresa (Principal) |
| `28` | Ticket para negócio |
| `219` | Ticket para chamada |
| `223` | Ticket para e-mail |
| `225` | Ticket para reunião |
| `227` | Ticket para observação |
| `229` | Ticket para tarefa |
| `84` | Ticket para comunicação (SMS, WhatsApp ou mensagem do LinkedIn) |
| `456` | Ticket para correio postal |
| `32` | Ticket para thread |
| `278` | Ticket para conversa |
| `526` | Ticket para pedido |
### Lead para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | --------------------------- |
| `578` | Lead para contato principal |
| `596` | Lead para chamada |
| `598` | Lead para e-mail |
| `600` | Lead para reunião |
| `602` | Lead para comunicação |
| `608` | Lead para contato |
| `610` | Lead para empresa |
| `646` | Lead para tarefa |
#### Chamada para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | -------------------- |
| `194` | Chamada para contato |
| `182` | Chamada para empresa |
| `206` | Chamada para negócio |
| `220` | Chamada para ticket |
#### E-mail para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ------------------- |
| `198` | E-mail para contato |
| `186` | E-mail para empresa |
| `210` | E-mail para negócio |
| `224` | E-mail para ticket |
#### Reunião para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | -------------------- |
| `200` | Reunião para contato |
| `188` | Reunião para empresa |
| `212` | Reunião para negócio |
| `226` | Reunião para ticket |
#### Observação para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ----------------------- |
| `202` | Observação para contato |
| `190` | Observação para empresa |
| `214` | Observação para negócio |
| `228` | Observação para ticket |
#### Correio postal para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | --------------------------- |
| `453` | Correio postal para contato |
| `459` | Correio postal para empresa |
| `457` | Correio postal para negócio |
| `455` | Correio postal para ticket |
#### Orçamento para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ---------------------------------------------------- |
| `69` | Orçamento para contato |
| `71` | Orçamento para empresa |
| `64` | Orçamento para negócio |
| `67` | Orçamento para item de linha |
| `286` | Orçamento para modelo de orçamento |
| `362` | Orçamento para desconto |
| `364` | Orçamento para taxa |
| `366` | Orçamento para imposto |
| `702` | Signatário do contato (para assinaturas eletrônicas) |
| `733` | Orçamento para carrinho |
| `408` | Orçamento para fatura |
| `731` | Orçamento para pedido |
| `398` | Orçamento para pagamento |
| `304` | Orçamento para assinatura |
#### Tarefa para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ------------------- |
| `204` | Tarefa para contato |
| `192` | Tarefa para empresa |
| `216` | Tarefa para negócio |
| `230` | Tarefa para ticket |
#### Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ---------------------------------------------------------------- |
| `81` | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para contato |
| `87` | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para empresa |
| `85` | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para negócio |
| `83` | Comunicação (SMS, WhatsApp ou mensagem do LinkedIn) para ticket |
### Pedido para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | ------------------------------ |
| `593` | Pedido para carrinho |
| `507` | Pedido para contato |
| `509` | Pedido para empresa |
| `512` | Pedido para negócio |
| `519` | Pedido para desconto |
| `521` | Pedido para código de desconto |
| `518` | Pedido para fatura |
| `513` | Pedido para item de linha |
| `523` | Pedido para pagamento |
| `730` | Pedido para orçamento |
| `516` | Pedido para assinatura |
| `726` | Pedido para tarefa |
| `525` | Pedido para ticket |
### Carrinho para objeto
| ID DE TIPO | Tipo de associação |
| ---------- | --------------------------- |
| `586` | Carrinho para contato |
| `588` | Carrinho para desconto |
| `590` | Carrinho para item de linha |
| `592` | Carrinho para objeto |
| `732` | Carrinho para orçamento |
| `728` | Carrinho para tarefa |
| `594` | Carrinho para ticket |
## Associações v1 (antigas)
Se você estiver usando a API de associações v1, exiba a tabela abaixo para obter informações sobre IDs a serem usadas ao associar registros.
| Tipo de associação | ID |
| --------------------------------------- | --- |
| Contato para empresa | 1 |
| Empresa para contato (padrão) | 2 |
| Empresa para contato (todos os rótulos) | 280 |
| Negócio para contato | 3 |
| Contato para negócio | 4 |
| Negócio para empresa | 5 |
| Empresa para negócio | 6 |
| Empresa para engajamento | 7 |
| Engajamento para empresa | 8 |
| Contato para engajamento | 9 |
| Engajamento para contato | 10 |
| Negócio para engajamento | 11 |
| Engajamento para negócio | 12 |
| Empresa matriz para empresa afiliada | 13 |
| Empresa afiliada para empresa matriz | 14 |
| Contato para ticket | 15 |
| Ticket para contato | 16 |
| Ticket para engajamento | 17 |
| Engajamento para ticket | 18 |
| Negócio para item de linha | 19 |
| Item de linha para negócio | 20 |
| Empresa para ticket | 25 |
| Ticket para empresa | 26 |
| Negócio para ticket | 27 |
| Ticket para negócio | 28 |