Última modificação: 22 de agosto de 2025

Run in Postman

 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 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. Para obter informações mais gerais sobre objetos e registros no HubSpot, saiba como gerenciar seu banco de dados do CRM.

​
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, mas você também pode criar propriedades personalizadas. Ao criar um novo negócio, você deve incluir as seguintes propriedades na solicitação: dealname, dealstagee 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.

​
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.
Por exemplo, para criar um novo negócio, a solicitação pode ser semelhante à seguinte: 
{
  "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 ou atividades 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: 
{
  "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âmetroDescrição
toO registro ou a atividade que você deseja associar ao negócio especificado por seu valor de id exclusivo.
typesO 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, ou você pode recuperar o valor de tipos de associação personalizados (ou seja, rótulos) por meio da API de associações.

​
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âmetroDescrição
propertiesUma 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.
propertiesWithHistoryUma 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.
associationsUma 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.
  • Para recuperar um lote de negócios específicos por ID de registro ou uma propriedade de identificador exclusivo personalizada, 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.
    • Para recuperar negócios por uma propriedade de identificador exclusivo 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: 
{
"properties": ["dealname", "dealstage", "pipeline"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
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. 
{
  "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.
  • 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 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.

​
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. 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: 
{
  "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: 
{
  "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.
  • Para excluir um negócio individual 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, 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.
{
  "inputs": [
    {
      "id": "123456"
    },
    {
      "id": "7891011"
    },
    {
      "id": "12123434"
    }
  ]
}
Saiba mais sobre a exclusão de negócios na documentação de referência.