> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# API du CRM | Transactions
> Une transaction stocke des données sur une transaction en cours. Les points de terminaison des transactions vous permettent de gérer ces données et de les synchroniser entre HubSpot et d'autres systèmes.
export const postmanIcon = ;
export const ScopesList = ({scopes = [], description = "Cette API requiert l'une des portées suivantes :"}) => {
if (!scopes || scopes.length === 0) {
return null;
}
const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
return
{description}
{sortedScopes.map((scope, index) =>
{scope}
)}
;
};
Dans HubSpot, les transactions représentent des transactions avec des contacts ou des entreprises. Les transactions sont suivies tout au long de votre processus de vente via des [phases de pipeline](https://knowledge.hubspot.com/fr/object-settings/set-up-and-customize-pipelines) jusqu'à ce qu'elles soient gagnées ou perdues. Les points de terminaison des transactions vous permettent de créer et de gérer des fiches d'informations de transaction ainsi que de synchroniser des données de transaction entre HubSpot et d'autres systèmes.
Découvrez-en davantage sur les API d'objets, de fiches d'informations, de propriétés et d'associations dans le [guide Comprendre le CRM](/docs/guides/crm/understanding-the-crm). Pour plus d'informations générales sur les objets et les fiches d'informations dans HubSpot, [découvrez comment gérer votre base de données CRM](https://knowledge.hubspot.com/fr/get-started/manage-your-crm-database).
## Créer des transactions
Pour créer de nouvelles transactions, effectuez une requête `POST` à `/crm/v3/objects/deals`.
Dans le corps de la requête, incluez les données de votre transaction dans un objet `properties`. Vous pouvez également ajouter un objet `associations` pour associer votre nouvelle transaction à des fiches d'informations existantes (par exemple, des contacts ou des entreprises) ou à des activités (par exemple, des réunions ou des notes).
### Propriétés
Les détails de la transaction sont stockés dans des propriétés de transaction. HubSpot fournit un ensemble de [propriétés de transaction par défaut](https://knowledge.hubspot.com/fr/properties/hubspots-default-deal-properties), mais vous pouvez également [créer des propriétés personnalisées](https://knowledge.hubspot.com/fr/properties/create-and-edit-properties).
Lorsque vous créez une nouvelle transaction, vous devez inclure les propriétés suivantes dans la requête : `dealname`, `dealstage` et, si vous disposez de plusieurs pipelines, `pipeline`. Si aucun pipeline n'est spécifié, le pipeline par défaut sera utilisé.
Pour afficher toutes les propriétés disponibles, vous pouvez récupérer une liste des propriétés de transactions de votre compte en effectuant une requête `GET` à `/crm/v3/properties/deals`. Découvrez-en davantage sur l'[API des propriétés](/docs/api-reference/crm-properties-v3/guide).
### Remarque :
Vous devez utiliser l'ID interne d'une phase de transaction ou d'un pipeline lors de la création d'une transaction via l'API. L'ID interne sera également retourné lorsque vous récupérerez des transactions via l'API. Vous pouvez trouver l'ID interne d'une phase de transaction ou d'un pipeline dans les [paramètres de votre pipeline de transactions.](https://knowledge.hubspot.com/fr/object-settings/set-up-and-customize-pipelines#edit-or-delete-pipelines)
Par exemple, pour créer une nouvelle transaction, votre requête peut ressembler à ce qui suit :
```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"
}
}
```
### Associations
Lorsque vous créez une nouvelle transaction, vous pouvez également associer la transaction à des [fiches d'informations](https://knowledge.hubspot.com/fr/records/associate-records) ou [activités](https://knowledge.hubspot.com/fr/records/associate-activities-with-records) existantes dans un objet `associations`. Par exemple, pour associer une nouvelle transaction à un contact et une entreprise existants, votre requête ressemblerait à ce qui suit :
```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
}
]
}
]
}
```
Dans l'objet `associations`, vous devez ajouter les éléments suivants :
| Paramètre | Description |
| - | - |
| `to` | La fiche d'informations ou l'activité à laquelle vous souhaitez associer la transaction, en fonction de sa valeur unique `id`. |
| `types` | Le type d'association entre la transaction et la fiche d'informations/l'activité. Inclut `associationCategory` et `associationTypeId`. Les ID de types d'association par défaut sont répertoriés [ici](/docs/api-reference/crm-associations-v4/guide#association-type-id-values), ou vous pouvez récupérer la valeur des types d'associations personnalisés (c'est-à-dire les libellés) via l'[API des associations](/docs/api-reference/crm-associations-v4/guide#retrieve-association-types). |
## Récupérer des transactions
Vous pouvez récupérer des transactions individuellement ou par lots.
* Pour récupérer une transaction individuelle, effectuez une requête `GET` à `/crm/v3/objects/deals/{dealId}`.
* Pour demander une liste de toutes les transactions, effectuez une requête `GET` à `/crm/v3/objects/deals`.
Pour ces points de terminaison, vous pouvez inclure les paramètres suivants dans l'URL de la requête :
| Paramètre | Description |
| - | - |
| `properties` | Une liste séparée par des virgules des propriétés à renvoyer dans la réponse. Si la transaction demandée n'a pas de valeur pour une propriété, elle n'apparaîtra pas dans la réponse. |
| `propertiesWithHistory` | Une liste séparée par des virgules des propriétés actuelles et historiques à renvoyer dans la réponse. Si la transaction demandée n'a pas de valeur pour une propriété, elle n'apparaîtra pas dans la réponse. |
| `associations` | Une liste séparée par des virgules des objets pour lesquels récupérer les ID associés. Les associations spécifiées qui n'existent pas ne seront pas renvoyées dans la réponse. Découvrez-en davantage sur l'[API des associations.](/docs/api-reference/crm-associations-v4/guide) |
* Pour récupérer un lot de transactions spécifiques par ID de fiche d'informations ou selon une [propriété d'identifiant unique personnalisée](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties), effectuez une requête `POST` à `crm/v3/objects/deals/batch/read`.
* Le point de terminaison du lot ne peut pas récupérer les associations. Découvrez comment lire par lots les associations avec l'API [des associations](/docs/api-reference/crm-associations-v4/guide).
* Pour récupérer les transactions en fonction d'une [propriété d'identification unique](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties) personnalisée plutôt que de l'ID de la transaction, incluez le paramètre `idProperty` dans le corps de la requête afin de spécifier le nom de la propriété. Ensuite, dans le tableau `inputs`, incluez les valeurs de la propriété de l'identifiant unique plutôt que l'ID.
Par exemple, pour récupérer un lot de transactions, votre requête peut ressembler à ce qui suit :
```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"
}
]
}
```
Pour récupérer les transactions contenant les valeurs actuelles et historiques d'une propriété spécifique, vous pouvez inclure le paramètre `propertiesWithHistory` dans le corps de la requête, comme indiqué ci-dessous.
```json theme={null}
{
"propertiesWithHistory": ["dealstage"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
```
## Mettre à jour des transactions
Vous pouvez mettre à jour des transactions individuellement ou par lots. Pour les transactions existantes, l'ID de transaction est une valeur unique par défaut que vous pouvez utiliser pour mettre à jour la transaction via l'API, mais vous pouvez aussi identifier des transactions en utilisant des [propriétés d'identifiant unique personnalisées.](/docs/api-reference/crm-properties-v3/guide#create-unique-identifier-properties)
* Pour mettre à jour une transaction individuelle avec son ID de fiche d'informations, effectuez une requête `PATCH` à `/crm/v3/objects/deals/{dealId}` et incluez les données que vous souhaitez mettre à jour.
* Pour mettre à jour plusieurs transactions, effectuez une requête `POST` dans `/crm/v3/objects/deals/batch/update`. Dans le corps de la requête, incluez un tableau avec les identifiants des transactions et les propriétés que vous souhaitez mettre à jour.
### Associer des transactions existantes à des fiches d'informations ou activités
Pour associer une transaction à d'autres fiches d'informations de CRM ou à une activité, effectuez une requête `PUT` à `/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`.
Pour récupérer la valeur `associationTypeId`, reportez-vous à [cette liste](/docs/api-reference/crm-associations-v4/guide#association-type-id-values) de valeurs par défaut ou effectuez une requête `GET` à `/crm/v4/associations/{fromObjectType}/{toObjectType}/labels`.
Découvrez-en davantage sur l'association de fiches d'informations avec l'[API des associations](/docs/api-reference/crm-associations-v4/guide).
### Supprimer une association
Pour supprimer une association entre une transaction et une fiche d'informations ou une activité, effectuez une requête `DELETE` à l'URL suivante : `/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}`.
## Épingler une activité à une fiche d'informations de transaction
Vous pouvez épingler une activité à une fiche d'informations de transaction via l'API en incluant le paramètre `hs_pinned_engagement_id` dans la requête. Pour la valeur du paramètre, incluez l'ID de l'activité à épingler, qui peut être récupéré via les [API d'engagement](/docs/api-reference/overview). Vous pouvez épingler une activité par fiche d'informations, et l'activité doit déjà être associée à la transaction avant l'épinglage.
Pour définir ou mettre à jour l'activité épinglée d'une transaction, votre requête peut ressembler à :
```json theme={null}
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
```
Vous pouvez également créer une transaction, l'associer à une activité existante et épingler l'activité dans la même requête. Par exemple :
```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
}
]
}
]
}
```
## Supprimer des transactions
Vous pouvez supprimer des transactions individuellement ou par lots, ce qui placera la transaction dans la corbeille dans HubSpot. Vous pourrez ensuite [restaurer la transaction dans HubSpot](https://knowledge.hubspot.com/fr/records/restore-deleted-records).
* Pour [supprimer une transaction individuelle](/docs/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D) avec son ID, effectuez une requête `DELETE` à `/crm/v3/objects/deals/{dealId}`. Aucun corps de requête n'est nécessaire pour cette requête.
* Pour [supprimer des transactions par lots](/docs/api-reference/crm-deals-v3/guide#post-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2Fbatch%2Farchive), effectuez une requête `POST` à `/crm/v3/objects/deals/batch/archive`. Dans le corps de la requête, incluez l'ID de la transaction pour les valeurs `id`, comme indiqué dans l'exemple de corps de requête ci-dessous.
```json theme={null}
{
"inputs": [
{
"id": "123456"
},
{
"id": "7891011"
},
{
"id": "12123434"
}
]
}
```
Pour en savoir plus sur la suppression des transactions, consultez la [documentation de référence](/docs/api-reference/crm-deals-v3/guide#delete-%2Fcrm%2Fv3%2Fobjects%2Fdeals%2F%7Bdealid%7D).