> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API del CRM | Negocios
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Esta API requiere uno de los siguientes ámbitos:"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
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](https://knowledge.hubspot.com/es/object-settings/set-up-and-customize-pipelines) 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](/docs/guides/crm/understanding-the-crm). Para obtener más información general sobre objetos y registros de HubSpot, consulta cómo [Administrar la base de datos del CRM](https://knowledge.hubspot.com/es/get-started/manage-your-crm-database).
## 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](https://knowledge.hubspot.com/es/properties/hubspots-default-deal-properties), pero también puedes [crear propiedades personalizadas](https://knowledge.hubspot.com/es/properties/create-and-edit-properties).
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](/docs/api-reference/crm-properties-v3/guide).
### 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](https://knowledge.hubspot.com/es/object-settings/set-up-and-customize-pipelines#edit-or-delete-pipelines).
Por ejemplo, para crear un nuevo negocio, la solicitud puede ser similar a la siguiente:
```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"
}
}
```
### Asociaciones
Al crear un nuevo negocio, también puedes asociar el negocio con [registros](https://knowledge.hubspot.com/es/records/associate-records) o [actividades](https://knowledge.hubspot.com/es/records/associate-activities-with-records) 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:
```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
}
]
}
]
}
```
Para el objeto `associations`, debes incluir lo siguiente:
| Parámetro | Descripción |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to` | El registro o actividad que quieres asociar con el negocio, especificado por su valor `id` único. |
| `types` | El tipo de asociación entre el negocio y el registro o actividad. Incluye `associationCategory`y `associationTypeId`. Los ID de los tipos de asociación predeterminados se enumeran en [este recurso](/docs/api-reference/crm-associations-v4/guide#association-type-id-values), 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](/docs/api-reference/crm-associations-v4/guide#retrieve-association-types). |
## 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ámetro | Descripción |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | Una 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. |
| `propertiesWithHistory` | Una 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. |
| `associations` | Una 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.](/docs/api-reference/crm-associations-v4/guide) |
* Para recuperar un bloque de negocios específicos por ID de registro o una [propiedad de identificador único personalizado](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties), 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](/docs/api-reference/crm-associations-v4/guide).
* Para obtener negocios por una [propiedad de identificador único](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties) 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:
```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 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.
```json theme={null}
{
"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](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties).
* 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](/docs/api-reference/crm-associations-v4/guide#association-type-id-values) 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](/docs/api-reference/crm-associations-v4/guide).
### 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](/docs/api-reference/overview). 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:
```json theme={null}
{
"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:
```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
}
]
}
]
}
```
## 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](https://knowledge.hubspot.com/es/records/restore-deleted-records).
* Para [eliminar un negocio individual](/docs/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D) 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](/docs/api-reference/crm-deals-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2Fbatch%2Farchive), 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.
```json theme={null}
{
"inputs": [
{
"id": "123456"
},
{
"id": "7891011"
},
{
"id": "12123434"
}
]
}
```
Más información sobre la eliminación de negocios en la [documentación de referencia](/docs/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D).