> ## 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 | Empresas
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}
)}
;
};
# Empresas
No HubSpot, as empresas armazenam informações sobre as organizações que interagem com os seus negócios. Os pontos de extremidade de empresas permitem controlar a criação e o gerenciamento de registros de empresas, bem como sincronizar os dados de empresas entre o HubSpot e outros sistemas.
Saiba mais sobre objetos, registros, propriedades e APIs de associações no guia [Noções básicas do CRM](/docs/guides/crm/understanding-the-crm). Para obter informações mais gerais sobre objetos e registros no HubSpot,[ saiba como gerenciar seu banco de dados do CRM](https://knowledge.hubspot.com/get-started/manage-your-crm-database).
## Criar empresas
Para criar novas empresas, faça uma solicitação `POST` para `/crm/v3/objects/companies`.
Na solicitação, inclua os dados da empresa em um objeto de propriedades. Você também pode adicionar um objeto de associações para associar sua nova empresa a registros (por exemplo, contatos, negócios) ou atividades (por exemplo, reuniões, observações) existentes.
### Propriedades
Os detalhes da empresa são armazenados nas propriedades da empresa. Existem [propriedades de empresa padrão do HubSpot](https://knowledge.hubspot.com/properties/hubspot-crm-default-company-properties), mas você também pode [criar propriedades personalizadas](https://knowledge.hubspot.com/properties/create-and-edit-properties).
Ao criar uma nova empresa, você deve incluir pelo menos uma das seguintes propriedades na solicitação: `name` ou `domain`. É recomendável incluir sempre o `domain`, pois os nomes de domínio são o [principal identificador exclusivo](https://knowledge.hubspot.com/records/deduplication-of-records#automatic-deduplication-in-hubspot) para evitar empresas duplicadas no HubSpot. Se uma empresa tiver [vários domínios](https://knowledge.hubspot.com/records/add-multiple-domain-names-to-a-company-record), você pode adicioná-los por meio da API usando o campo `hs_additional_domains`, separando cada domínio com ponto e vírgula. Por exemplo, `"hs_additional_domains" : "domain.com; domain2.com; domain3.com"`.
Para exibir todas as propriedades disponíveis, você pode recuperar uma lista das propriedades da empresa da sua conta, fazendo uma solicitação `GET` para `/crm/v3/properties/companies`. Saiba mais sobre a [API de propriedades](/docs/api-reference/crm-properties-v3/guide).
**Observação**: se você incluiu `lifecyclestage` em sua solicitação, os valores devem se referir ao nome interno da fase do ciclo de vida. Os nomes internos das fases padrão são valores de texto e não mudam, mesmo se você editar o [rótulo](https://knowledge.hubspot.com/properties/create-and-edit-properties#:~:text=the%20properties%20settings.-,Label/Name%3A,-enter%20a%20unique) da fase (por exemplo, `subscriber` ou `marketingqualifiedlead`). Os nomes internos das [fases personalizadas](https://knowledge.hubspot.com/object-settings/create-and-customize-lifecycle-stages) são valores numéricos. Você pode encontrar o ID interno de uma fase nas [configurações de fase do ciclo de vida](https://knowledge.hubspot.com/object-settings/create-and-customize-lifecycle-stages#:~:text=To%20edit%20a%20lifecycle%20stage%2C%20hover%20over%20the%20stage%20and%20click%20Edit.%20In%20the%20right%20panel%2C%20edit%20the%20Stage%20name%2C%20then%20click%20Edit%20lifecycle%20stage%20to%20confirm.%20Click%20the%20code%20codcode%20icon%20to%20view%20the%20stage%27s%20internal%20ID%2C%20which%20is%20used%20by%20integrations%20and%20APIs.) ou recuperando a propriedade de fase do ciclo de vida por meio da API.
Por exemplo, para criar uma nova empresa, a solicitação pode ser semelhante à seguinte:
```json theme={null}
///Example request body
{
"properties": {
"name": "HubSpot",
"domain": "hubspot.com",
"city": "Cambridge",
"industry": "Technology",
"phone": "555-555-555",
"state": "Massachusetts",
"lifecyclestage": "51439524"
}
}
```
### Associações
Ao criar uma nova empresa, você também pode associá-la a [registros](https://knowledge.hubspot.com/records/associate-records) ou [atividades](https://knowledge.hubspot.com/records/associate-activities-with-records) existentes em um objeto de associações. Por exemplo, para associar uma nova empresa a um contato e um e-mail existentes, a solicitação seria parecida com a seguinte:
```json theme={null}
///Example request body
{
"properties": {
"name": "HubSpot",
"domain": "hubspot.com",
"city": "Cambridge",
"industry": "Technology",
"phone": "555-555-555",
"state": "Massachusetts",
"lifecyclestage": "51439524"
},
"associations": [
{
"to": {
"id": 101
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 280
}
]
},
{
"to": {
"id": 556677
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 185
}
]
}
]
}
```
No objeto de associações, você deve incluir o seguinte:
| Descrição | Parâmetro |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | O registro ou a atividade que você deseja associar à empresa especificado por seu valor de `id` exclusivo. |
| `types` | O tipo de associação entre a empresa e o registro/atividade. Inclua `associationCategory` e `associationTypeId`. Os IDs de tipo de associação padrão são listados [aqui](/docs/api-reference/crm-associations-v4/guide#association-type-id-values), ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da [API de associações](/docs/api-reference/crm-associations-v4/guide#retrieve-association-types). |
## Recuperar empresas
Você pode recuperar empresas individualmente ou em lotes.
* Para recuperar uma empresa individual, faça uma solicitação `GET` para `/crm/v3/objects/companies/{companyId}`.
* Para solicitar uma lista de todas as empresas, faça uma solicitação `GET` para `/crm/v3/objects/companies`.
Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
| Descrição | Parâmetro |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se a empresa solicitada não tiver um valor para uma propriedade, ela não será exibida na resposta. |
| `propertiesWithHistory` | Uma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se a empresa solicitada não tiver um valor para uma propriedade, ela não será exibida na resposta. |
| `associations` | Uma lista separada por vírgulas de objetos para recuperar IDs associados. Todas as associações especificadas que não existem não serão retornadas na resposta. Saiba mais sobre a [API de associações.](/docs/api-reference/crm-associations-v4/guide) |
* Para recuperar um lote de empresas específicas por ID de registro ou uma [propriedade de identificador exclusivo personalizada](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties), faça uma solicitação `POST` para `crm/v3/objects/companies/batch/read`. O ponto de extremidade em lote não pode recuperar associações. Saiba como fazer associações de leitura em lote com a [API de associações](/docs/api-reference/crm-associations-v4/guide).
Para o ponto de extremidade de leitura em lote, você também pode usar o parâmetro `idProperty` opcional para recuperar empresas por uma [propriedade de identificador exclusivo personalizada](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties). Por padrão, os valores de `id` na solicitação referem-se ao ID do registro (`hs_object_id`); portanto, o parâmetro `idProperty` não é necessário ao recuperar pelo ID do registro. Para usar uma propriedade de valor exclusivo personalizada para recuperar empresas, você deve incluir o parâmetro `idProperty`.
Por exemplo, para recuperar um lote de empresas, sua solicitação pode ser parecida com o seguinte:
```json theme={null}
///Example request body with record ID
{
"properties": ["name", "domain"],
"inputs": [
{
"id": "56789"
},
{
"id": "23456"
}
]
}
```
```json theme={null}
///Example request body with a unique value property
{
"properties": ["name", "domain"],
"idProperty": "uniquepropertyexample",
"inputs": [
{
"id": "abc"
},
{
"id": "def"
}
]
}
```
Para recuperar empresas com valores atuais e do histórico de uma propriedade, sua solicitação pode ser parecida com o seguinte:
```json theme={null}
///Example request body with record ID (current and historical values)
{
"propertiesWithHistory": ["name"],
"inputs": [
{
"id": "56789"
},
{
"id": "23456"
}
]
}
```
## Atualizar empresas
Você pode atualizar empresas individualmente ou em massa. Para empresas existentes, o ID de registro da empresa é um valor exclusivo que você pode usar para atualizar a empresa por meio da API.
Para atualizar uma empresa individual por seu ID da empresa, faça uma solicitação `PATCH` para `/crm/v3/objects/companies/{companyId}` e inclua os dados que deseja atualizar.
**Observe**: se atualizar a propriedade `lifecyclestage`, você só pode definir o valor avançar na ordem do estágio. Para definir o estágio do ciclo de vida para trás, primeiro você precisa limpar o valor do estágio do ciclo de vida existente do registro. O valor pode ser [apagado manualmente](https://knowledge.hubspot.com/records/update-a-property-value-for-a-record) ou automaticamente por meio de um[ fluxo de trabalho](https://knowledge.hubspot.com/records/change-record-lifecycle-stages-in-bulk) ou de uma integração que sincroniza os dados do contato.
### Associar empresas existentes a registros e atividades
Para associar uma empresa a outros registros do CRM ou a uma atividade, faça uma solicitação `PUT` para `/crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`.
Para recuperar o valor `associationTypeId`, consulte [esta lista](/docs/api-reference/crm-associations-v4/guide#association-type-id-values) de valores padrão ou envie uma solicitação `GET` para `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`.
Saiba mais sobre como associar registros com a [API de associações](/docs/api-reference/crm-associations-v4/guide).
### Remover uma associação
Para remover uma associação entre uma empresa e um registro ou uma atividade, faça uma solicitação `DELETE` para o seguinte URL: `/crm/v3/objects/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`
## Fixar uma atividade em um registro de empresa
Você pode fixar uma atividade em um registro de empresa por meio da API, incluindo o campo `hs_pinned_engagement_id` na sua solicitação. No campo, inclua o `id` da atividade a ser fixada, que pode ser recuperado por meio das [APIs de engajamentos](/docs/api-reference/overview). Você pode fixar uma atividade por registro. No entanto, a atividade já deve estar associada à empresa antes da fixação.
Para definir ou atualizar a atividade fixada de uma empresa, sua solicitação pode ser parecida com o seguinte:
```json theme={null}
///Example request body PATCH /crm/v3/objects/companies/{companyId}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
```
Você também pode criar uma empresa, associá-la a uma atividade existente e fixar a atividade na mesma solicitação. Por exemplo:
```json theme={null}
///Example request body POST /crm/v3/objects/companies
{
"properties": {
"domain": "example.com",
"name": "Example Company",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 189
}
]
}
]
}
```
## Excluir empresas
Você pode excluir empresas individualmente ou em massa, o que adicionará a empresa à lixeira no HubSpot. Posteriormente, você pode[ restaurar a empresa no HubSpot](https://knowledge.hubspot.com/records/restore-deleted-records).
Para excluir uma empresa individual pelo seu ID, faça uma solicitação`DELETE` para `/crm/v3/objects/companies/{companyId}`.
Saiba mais sobre empresas de exclusão em lote na [documentação de referência](/docs/api-reference/crm-companies-v3/guide).