> ## 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 | Negócios
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}
)}
;
};
No HubSpot, os negócios representam transações com contatos ou empresas. Os negócios são rastreados durante o processo de vendas nas [fases do pipeline](https://knowledge.hubspot.com/pt/object-settings/set-up-and-customize-pipelines) até serem conquistados ou perdidos. Os pontos de extremidade de negócios permitem controlar a criação e o gerenciamento de registros de negócios, bem como sincronizar dados de negócios 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/pt/get-started/manage-your-crm-database).
## Criar negócios
Para criar novos negócios, faça uma solicitação `POST` para `/crm/v3/objects/deals`.
No corpo da solicitação, inclua os dados de negócio em um objeto `properties`. Você também pode adicionar um objeto `associations` para associar seu novo negócio a registros existentes (por exemplo, contatos, empresas) ou atividades (por exemplo, reuniões, notas).
### Propriedades
Os detalhes do negócio são armazenados nas propriedades do negócio. A HubSpot fornece um conjunto de [propriedades de negócio padrão](https://knowledge.hubspot.com/pt/properties/hubspots-default-deal-properties), mas você também pode [criar propriedades personalizadas](https://knowledge.hubspot.com/pt/properties/create-and-edit-properties).
Ao criar um novo negócio, você deve incluir as seguintes propriedades na solicitação: `dealname`, `dealstage`e se você tiver vários pipelines, `pipeline`. Se um pipeline não for especificado, o pipeline padrão será usado.
Para exibir todas as propriedades disponíveis, você pode recuperar uma lista das propriedades de negócios da sua conta, fazendo uma solicitação `GET` para `/crm/v3/properties/deals`. Saiba mais sobre a [API de propriedades](/docs/api-reference/crm-properties-v3/guide).
### Observação:
Você deve usar o ID interno de um estágio ou pipeline de negócio ao criar um negócio por meio da API. O ID interno também será retornado quando você recuperar negócios por meio da API. Você pode encontrar o ID interno de uma fase ou pipeline de negócios em nas [configurações do pipeline de negócios.](https://knowledge.hubspot.com/pt/object-settings/set-up-and-customize-pipelines#edit-or-delete-pipelines)
Por exemplo, para criar um novo negócio, a solicitação pode ser semelhante à seguinte:
```json theme={null}
{
"properties": {
"amount": "1500.00",
"closedate": "2019-12-07T16:50:06.678Z",
"dealname": "New deal",
"pipeline": "default",
"dealstage": "contractsent",
"hubspot_owner_id": "910901",
"hs_all_collaborator_owner_ids": ";12345678;9101112"
}
}
```
### Associações
Ao criar um novo negócio, você também pode associar o negócio a [registros existentes](https://knowledge.hubspot.com/pt/records/associate-records) ou [atividades](https://knowledge.hubspot.com/pt/records/associate-activities-with-records) num `associations` objeto. Por exemplo, para associar um novo negócio a um contato e uma empresa existentes, a solicitação seria parecida com a seguinte:
```json theme={null}
{
"properties": {
"amount": "1500.00",
"closedate": "2019-12-07T16:50:06.678Z",
"dealname": "New deal",
"pipeline": "default",
"dealstage": "contractsent",
"hubspot_owner_id": "910901"
},
"associations": [
{
"to": {
"id": 201
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 5
}
]
},
{
"to": {
"id": 301
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 3
}
]
}
]
}
```
No objeto `associations`, você deve incluir o seguinte:
| Parâmetro | Descrição |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | O registro ou a atividade que você deseja associar ao negócio especificado por seu valor de `id` exclusivo. |
| `types` | O tipo de associação entre o negócio 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 negócios
Você pode recuperar negócios individualmente ou em lotes.
* Para recuperar um negócio individual, faça uma solicitação `GET` para `/crm/v3/objects/deals/{dealId}`.
* Para solicitar uma lista de todos os negócios, faça uma solicitação `GET` para `/crm/v3/objects/deals`.
Para ambos os pontos de extremidade, você pode incluir os seguintes parâmetros de consulta no URL da solicitação:
| Parâmetro | Descrição |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Uma lista separada por vírgulas das propriedades a serem retornadas em resposta. Se o negócio solicitado não tiver um valor para uma propriedade, ele não será exibido na resposta. |
| `propertiesWithHistory` | Uma lista separada por vírgulas das propriedades atuais e do histórico a serem retornadas em resposta. Se o negócio solicitado não tiver um valor para uma propriedade, ele não será exibido 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 negócios específicos 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/deals/batch/read`.
* O ponto final do 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 recuperar negócios por uma [propriedade de identificador exclusivo](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties) padrão em vez do ID do negócio, inclua o parâmetro `idProperty` no corpo da solicitação para especificar o nome da propriedade. Em seguida, na caixa `inputs` inclua os valores da propriedade de identificação exclusiva em vez da ID do negócio.
Por exemplo, para recuperar um lote de negócios, sua solicitação pode ser parecida com o seguinte:
```text get by id.txt theme={null}
{
"properties": ["dealname", "dealstage", "pipeline"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
```
```text get by unique property.txt theme={null}
{
"properties": ["dealname", "dealstage", "pipeline"],
"idProperty": "uniqueordernumber",
"inputs": [
{
"id": "0001111"
},
{
"id": "0001112"
}
]
}
```
Para recuperar negócios com valores atuais e históricos de uma propriedade específica, você pode incluir o parâmetro `propertiesWithHistory` no corpo da solicitação, conforme mostrado abaixo.
```json theme={null}
{
"propertiesWithHistory": ["dealstage"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
```
## Atualizar negócios
Você pode atualizar negócios individualmente ou em massa. Para negócios existentes, o ID do negócio é um valor exclusivo que você pode usar para atualizar o negócio por meio da API, mas você também identificar negócios usando [propriedades de identificador exclusivo personalizadas.](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties)
* Para atualizar um negócio individual por seu ID de registro, faça uma solicitação `PATCH` para `/crm/v3/objects/deals/{dealId}` e inclua os dados que deseja atualizar.
* Para atualizar vários negócios, faça uma solicitação `POST` para `/crm/v3/objects/deals/batch/update`. No corpo da solicitação, inclua uma matriz com os identificadores dos negócios e as propriedades que deseja atualizar.
### Associar negócios existentes a registros ou atividades
Para associar um negócio a outros registros do CRM ou uma atividade, faça uma solicitação `PUT` para `/crm/v3/objects/deals/{dealId}/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 um negócio e um registro ou uma atividade, faça uma solicitação `DELETE` para o seguinte URL: `/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`.
## Fixar uma atividade em um registro de negócio
Você pode fixar uma atividade em um registro de negócio via API incluindo o parâmetro `hs_pinned_engagement_id` na solicitação. Para o valor do parâmetro, especifique a ID da atividade a ser fixada, que pode ser recuperada por meio das [APIs de engajamento](/docs/api-reference/overview). Você pode fixar uma atividade por registro. No entanto, a atividade já deve estar associada ao negócio antes da fixação.
Para definir ou atualizar a atividade fixada de um negócio, sua solicitação pode ser parecida com o seguinte:
```json theme={null}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
```
Você também pode criar um negócio, associá-lo a uma atividade existente e fixar a atividade na mesma solicitação. Por exemplo:
```json theme={null}
{
"properties": {
"dealname": "New deal",
"pipelines": "default",
"dealstage": "contractsent",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 213
}
]
}
]
}
```
## Excluir negócios
Você pode excluir negócios individualmente ou em massa, o que adicionará o negócio à lixeira no HubSpot. Posteriormente, você pode[ restaurar o negócio no HubSpot](https://knowledge.hubspot.com/pt/records/restore-deleted-records).
* Para [excluir um negócio individual](/docs/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D) pelo seu ID, faça uma solicitação `DELETE` para `/crm/v3/objects/deals/{dealId}`. Nenhum corpo de solicitação é necessário para esta solicitação.
* Para [excluir negócios em massa](/docs/api-reference/crm-deals-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2Fbatch%2Farchive), faça uma solicitação `POST` para `/crm/v3/objects/deals/batch/archive`. No corpo da solicitação, inclua os valores de ID do negócio como `id` entradas, conforme mostrado no exemplo de corpo de solicitação abaixo.
```json theme={null}
{
"inputs": [
{
"id": "123456"
},
{
"id": "7891011"
},
{
"id": "12123434"
}
]
}
```
Saiba mais sobre a exclusão de negócios na [documentação de referência](/docs/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D).