Última modificación: 22 de agosto de 2025

Run in Postman

 En HubSpot, los negocios representan transacciones con contactos o empresas. A los negocios se les hace seguimiento en el proceso de venta mediante las etapas de la pipeline hasta que se ganan o se pierden. Los endpoints de los negocios te permiten crear y administrar negocios, así como sincronizar los datos de los negocios entre HubSpot y otros sistemas. Obtén más información sobre las API de los objetos, los registros, las propiedades y las asociaciones en la guía informativa sobre el CRM. Para obtener más información general sobre objetos y registros de HubSpot, consulta cómo Administrar la base de datos del CRM.

​
Crear negocios

Para crear nuevos negocios, haz una solicitud POST a /crm/v3/objects/deals. En el cuerpo de la solicitud, incluye los datos de tu negocio en un objeto properties. También puedes agregar un objeto associations para vincular el nuevo negocio con registros existentes (por ejemplo, contactos o empresas) o actividades (por ejemplo, reuniones o notas).

​
Propiedades

Los detalles del negocio se almacenan en las propiedades de negocios. HubSpot proporciona un conjunto de propiedades de negocio predeterminadas, pero también puedes crear propiedades personalizadas. Al crear un nuevo negocio, debes incluir las siguientes propiedades en la solicitud: dealname, dealstage y si tienes varias pipelines, pipeline. Si no se especifica una pipeline, se utilizará la pipeline predeterminada. Para ver todas las propiedades disponibles, puedes obtener una lista de las propiedades de negocios de tu cuenta haciendo una solicitud GET a /crm/v3/properties/deals. Encuentra más información sobre la API de propiedades.

​
Nota:

Debes usar el ID interno de una etapa del negocio o una pipeline al crear un negocio a través de la API. El ID interno también saldrá en los resultados cuando busques negocios a través de la API. Puedes encontrar el ID interno de una etapa del negocio o una pipeline en la configuración de tu pipeline de negocios.
Por ejemplo, para crear un nuevo negocio, la solicitud puede ser similar a la siguiente: 
{
  "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"
  }
}

​
Asociaciones

Al crear un nuevo negocio, también puedes asociar el negocio con registros o actividades existentes en un objeto associations. Por ejemplo, para asociar un nuevo negocio con un registro de contacto y de empresa existentes, la solicitud debería hacerse de la siguiente manera: 
{
  "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
        }
      ]
    }
  ]
}
Para el objeto associations, debes incluir lo siguiente:
ParámetroDescripción
toEl registro o actividad que quieres asociar con el negocio, especificado por su valor id único.
typesEl tipo de asociación entre el negocio y el registro o actividad. Incluye associationCategoryy associationTypeId. Los ID de los tipos de asociación predeterminados se enumeran en este recurso, y también puedes obtener el valor de los tipos de asociación personalizados (es decir, etiquetas) a través de la API de asociaciones.

​
Buscar negocios

Puedes buscar negocios individualmente o en bloques.
  • Para buscar un solo un negocio, haz una solicitud GET a /crm/v3/objects/deals/{dealId}.
  • Para obtener una lista de todos los negocios, envía una solicitud GET a /crm/v3/objects/deals.
En estos endpoints, puedes incluir los siguientes parámetros de consulta en la URL de la solicitud:
ParámetroDescripción
propertiesUna lista separada con comas de las propiedades que se devolverán en la respuesta. Si el negocio solicitado no tiene un valor para una propiedad, este no aparecerá en la respuesta.
propertiesWithHistoryUna lista separada con comas de las propiedades actuales y anteriores que se devolverán en la respuesta. Si el negocio solicitado no tiene un valor para una propiedad, este no aparecerá en la respuesta.
associationsUna lista separada con comas de los objetos para los que se deben obtener los ID asociados. No se devolverán en la respuesta las asociaciones especificadas que no existan. Encuentra más información sobre la API de asociaciones.
  • Para recuperar un bloque de negocios específicos por ID de registro o una propiedad de identificador único personalizado, haz una solicitud POST a crm/v3/objects/deals/batch/read.
    • El endpoint por lotes no puede obtener asociaciones. Encuentra más información sobre cómo leer asociaciones por lotes con la API de asociaciones.
    • Para obtener negocios por una propiedad de identificador único personalizada en lugar del ID del negocio, incluye el parámetro idProperty en el cuerpo de la solicitud para especificar el nombre de la propiedad. Luego, en la matriz inputs, incluye los valores de la propiedad del identificador único en lugar del ID del negocio.
Por ejemplo, para buscar negocios en bloques, la solicitud podría verse de una de estas dos maneras: 
{
"properties": ["dealname", "dealstage", "pipeline"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
Para obtener negocios con valores actuales e históricos con respecto a una propiedad, puedes incluir el parámetro propertiesWithHistory en el cuerpo de la solicitud, como se muestra a continuación. 
{
  "propertiesWithHistory": ["dealstage"],
  "inputs": [
    {
      "id": "7891023"
    },
    {
      "id": "987654"
    }
  ]
}

​
Actualizar negocios

Puedes actualizar los negocios individualmente o en bloques. Para los negocios existentes, el ID del negocio es un valor único predeterminado que puedes usar para actualizar el negocio a través de la API, pero también puedes identificar los negocios utilizando propiedades personalizadas de identificadores únicos.
  • Para actualizar un solo negocio por su ID de registro, haz una solicitud PATCH a /crm/v3/objects/deals/{dealId} e incluye los datos que quieres actualizar.
  • Para actualizar varios negocios, haz una solicitud POST a /crm/v3/objects/deals/batch/update. En el cuerpo de la solicitud, incluye una matriz con los identificadores de los negocios y las propiedades que quieres actualizar.

​
Asociar negocios existentes con registros o actividades

Para asociar un negocio con otros registros del CRM o una actividad, haz una solicitud PUT a /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.
Para obtener el valor associationTypeId, consulta esta lista de valores predeterminados o haz una solicitud GET a /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.
Encuentra más información sobre cómo asociar registros a través de la API de asociaciones.

​
Eliminar una asociación

Para quitar una asociación entre un negocio y un registro o actividad, haz una solicitud DELETE a la siguiente URL: /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}.

​
Anclar una actividad en el registro de un negocio

Puedes anclar una actividad en un registro de negocio a través de la API incluyendo el parámetro hs_pinned_engagement_id en tu solicitud. En el valor del parámetro, incluye el id de la actividad a anclar, que se puede obtener a través de las API de interacciones. Puedes anclar una actividad por registro, y la actividad ya debe estar asociada con el negocio antes de anclarla. Para establecer o cambiar la actividad anclada de un negocio, la solicitud podría hacerse de la siguiente manera: 
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
También puedes crear un negocio, asociarlo a una actividad existente y anclar la actividad en la misma solicitud. Por ejemplo: 
{
  "properties": {
    "dealname": "New deal",
    "pipelines": "default",
    "dealstage": "contractsent",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 213
        }
      ]
    }
  ]
}

​
Eliminar negocios

Puedes eliminar negocios individualmente o en bloques, lo que agregará el negocio a la papelera de reciclaje en HubSpot. Más adelante puedes restaurar el negocio en HubSpot.
  • Para eliminar un negocio individual usando el ID, haz una solicitud DELETE a /crm/v3/objects/deals/{dealId}. No se necesita un cuerpo de solicitud para esta petición.
  • Para eliminar negocios por lotes, envía una solicitud POST a /crm/v3/objects/deals/batch/archive. En el cuerpo de la solicitud, incluye los valores del ID del negocio como entradas de id, como se muestra en el ejemplo a continuación.
{
  "inputs": [
    {
      "id": "123456"
    },
    {
      "id": "7891011"
    },
    {
      "id": "12123434"
    }
  ]
}
Más información sobre la eliminación de negocios en la documentación de referencia.