Dernière modification : 22 août 2025
Utilisez l’API Devis pour créer, gérer et récupérer des devis afin de partager des informations sur les prix avec des acheteurs potentiels. Une fois configuré, un devis peut être partagé avec un acheteur via une URL spécifiée ou un PDF. Les utilisateurs peuvent également gérer les devis dans HubSpot pour ajouter des détails, mettre à jour les associations, etc.
Si vous avez configuré les paiements HubSpot ou le traitement des paiements Stripe, vous pouvez configurer un devis à payer via cette API. En savoir plus sur les devis payables.

Présentation
Le processus de création de devis peut être divisé en plusieurs étapes :- Créer un devis : permet de créer un devis avec quelques détails, tels que le nom et la date d’expiration. Vous pouvez également configurer le devis pour activer les signatures électroniques et les paiements.
- Configurer des associations : permet d’associer le devis à d’autres types d’objets CRM, tels que des lignes de produits, un modèle de devis, une transaction, etc. Au cours de l’étape suivante, le devis héritera des valeurs de propriété de certaines de ces fiches d’informations associées ainsi que des paramètres du compte.
- Définir l’état du devis : permet de définir l’état du devis pour refléter sa prédisposition à être partagé avec les acheteurs. Lorsque vous définissez l’état du devis, par exemple en le transformant en brouillon modifiable ou en devis publié accessible au public, il héritera de certaines propriétés de ses fiches d’informations CRM et paramètres de compte associés.
- Partager le devis : une fois un devis publié, vous pouvez le partager avec vos acheteurs.
Créer un devis
Pour créer un devis, vous devez d’abord configurer ses détails de base en effectuant une requêtePOST
à /crm/v3/objects/quotes
. Vous devez ensuite effectuer un appel distinct pour associer le devis à d’autres objets, tels que le modèle de devis, les lignes de produit ou une transaction.
En fonction de votre workflow préféré, vous pouvez créer un devis avec des associations via une seule requête POST.
Paramètre | Type | Description |
---|---|---|
hs_title | Chaîne | Le nom du devis. |
hs_expiration_date | Chaîne | La date d’expiration du devis. |
GET
à crm/v3/properties/quotes
. Découvrez-en davantage sur l’API des propriétés.
La réponse comprendra un id
, que vous utiliserez pour continuer à configurer le devis. Vous pouvez mettre à jour les propriétés du devis à tout moment en effectuant une requête PATCH
à /crm/v3/objects/quotes/{quoteId}
.
Propriétaire du devis
La définition manuelle de la propriétéhubspot_owner_id
n’est pas possible car il s’agit d’une propriété calculée et toutes les valeurs seront remplacées. Lors de l’utilisation des devis, la propriété fonctionne comme suit :
- Si une transaction est associée au devis, la propriété
hubspot_owner_id
reflétera la propriétéhs_associated_deal_owner_id
(hs_associated_deal_owner_id
est une propriété calculée). - Si une transaction n’est pas associée au devis, la propriété
hubspot_owner_id
reflétera la propriétéhs_quote_owner_id
.
Activer les signatures électroniques
Pour activer les signatures électroniques sur le devis, incluez la propriété booléennehs_esign_enabled
dans votre corps de requête avec la valeur true
. Notez que vous ne pourrez pas ajouter de contresignataires via l’API. Ceux-ci devront donc être ajoutés dans HubSpot avant de publier le devis. Vous ne pouvez pas non plus publier de devis avec la signature électronique activée si vous avez dépassé votre limite mensuelle de signatures électroniques.
Activer les paiements
Pour activer les paiements sur un devis, incluez la propriété booléennehs_payment_enabled
dans votre corps de la requête avec la valeur true
. En fonction de votre prestataire de services de paiement et des modes de paiement acceptés, vous devrez également définir hs_payment_type
et hs_allowed_payment_methods
.
Remarque :
Le compte HubSpot doit avoir configuré les paiements HubSpot ou le traitement des paiements Stripe avant d’utiliser cette fonctionnalité.Paramètre | Type | Description |
---|---|---|
hs_payment_enabled | Booléen | : lorsque la valeur est défini sur true , l’option permet au devis de collecter le paiement en utilisant les paiements ou le traitement des paiements Stripe. La valeur par défaut est false . |
hs_payment_type | Énumération | : permet de déterminer le prestataire de services de paiement à utiliser. La valeur peut être soit HUBSPOT ou BYO_STRIPE . |
hs_allowed_payment_methods | Énumération | : les modes de paiement à utiliser (par exemple, carte de crédit). |
hs_collect_billing_address | Booléen | : lorsque la valeur est définie sur true , permet à l’acheteur de saisir son adresse de facturation lors du paiement. |
hs_collect_shipping_address | Booléen | : lorsque la valeur est définie sur true , permet à l’acheteur de saisir son adresse de livraison lors du paiement. |
hs_payment_status
et hs_payment_date
:
- Lorsque vous publiez un devis avec les paiements activés, HubSpot définit automatiquement la propriété
hs_payment_status
surPENDING
. - Si vous utilisez ACH, lorsque le paiement est traité, HubSpot définira automatiquement la propriété
hs_payment_status
surPROCESSING
. - Une fois le paiement confirmé, HubSpot définira automatiquement la propriété
hs_payment_status
surPAID
. - Une fois le devis payé, HubSpot définira automatiquement
hs_payment_date
à la date et à l’heure de confirmation du paiement. - Une fois le paiement confirmé, le paiement est automatiquement associé au devis. Si vous souhaitez obtenir plus d’informations sur le paiement, reportez-vous à l’API outils de paiement.
Ajout d’associations
Pour créer un devis complet, vous devez l’associer à d’autres fiches d’informations CRM, telles que des lignes de produit, à l’aide de l’API des associations. Le tableau ci-dessous indique quelles associations de fiches d’informations CRM sont requises pour un devis complet et lesquelles sont facultatives. Poursuivez votre lecture pour en savoir plus sur la récupération des identifiants et leur utilisation pour créer les associations requises.Type d’objet | Obligatoire | Description |
---|---|---|
Lignes de produit | Oui | : les biens et/ou services vendus via le devis. Vous pouvez créer des lignes de produits à partir de produits de votre bibliothèque de produits ou créer des lignes de produits autonomes personnalisées. |
Modèle de devis | Oui | : le modèle qui crée le devis et fournit certains de ses paramètres de configuration, tels que la langue. Chaque devis peut être associé à un modèle. |
Transaction | Oui | : la fiche d’informations de transaction pour le suivi des revenus et du cycle de vie des ventes. Un devis hérite des valeurs de la transaction associée, y compris le propriétaire et la devise. Chaque devis peut être associé à une transaction. |
Contact | Non | : les acheteurs spécifiques auxquels vous vous adressez dans le devis. |
Entreprise | Non | : une entreprise spécifique à laquelle vous vous adressez dans le devis. Chaque devis peut être associé à une entreprise. |
Remises, frais et taxes | Non | : l’ensemble des remises, frais et taxes à appliquer au moment du paiement. Pour déterminer le montant total du devis, HubSpot applique d’abord des remises, puis des frais, puis des taxes. Vous pouvez utiliser le champ hs_sort_order pour réorganiser des objets du même type. Peut être défini sur des valeurs fixes ou des pourcentages en définissant hs_type sur FIXED ou PERCENT . |
Récupération des identifiants pour les associations
Pour effectuer chaque association, vous devez d’abord récupérer l’identifiant de chaque objet que vous souhaitez associer. Pour récupérer chaque identifiant, vous devez effectuer une requêteGET
au point de terminaison de l’objet concerné, qui suivra le même schéma pour chaque objet CRM. Dans chaque requête, vous pouvez également inclure un paramètre de requête properties
pour renvoyer des propriétés spécifiques, si nécessaire. Vous trouverez ci-dessous des exemples de requêtes GET
pour chaque type d’objet.
200
avec des détails pour chaque type d’objet récupéré. Vous utiliserez cette valeur dans le champ id
pour définir des associations à l’étape suivante.
Création d’associations
Une fois vos identifiants récupérés, vous pouvez appeler l’API des associations pour créer des associations. Pour chaque type d’objet que vous souhaitez associer à un devis, vous devrez procéder à un appel distinct en effectuant une requêtePUT
à l’aide de la structure d’URL ci-dessous :
/crm/v4/objects/quotes/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}
Paramètre | Description |
---|---|
fromObjectId | L’ID du devis. |
toObjectType | Le type d’objet associé. Par exemple : line_items , deals et quote_template . |
toObjectId | L’ID de l’objet auquel vous associez le devis. |
PUT
pour chaque type d’objet.
123456
, les requêtes d’association du devis peuvent inclure les éléments suivants :
- Lignes de produit (ID :
55555
,66666
) :/crm/v4/objects/quotes/123456/associations/default/line_items/55555
/crm/v4/objects/quotes/123456/associations/default/line_items/66666
- Modèle de devis (ID :
987654
) :/crm/v4/objects/quotes/123456/associations/default/quote_template/987654
- Transaction (ID :
345345
) :/crm/v4/objects/quotes/123456/associations/default/deals/345345
200
ainsi que des détails sur l’association. Les appels ci-dessus associeront les objets dans les deux directions, chaque direction ayant son propre ID. Par exemple, si vous associez le devis à un modèle de devis, la réponse décrira l’association des deux côtés. Dans l’exemple de réponse ci-dessous, 286
est l’ID du type d’association de devis à modèle de devis, et 285
est l’ID du type d’association de modèle de devis à devis.
Lorsque vous associez un devis à un modèle de devis, tenez compte des limites suivantes :
- Les modèles de devis doivent être créés avant de pouvoir être associés à un devis.
- Un devis ne peut être associé qu’à un seul modèle de devis.
- Cette API ne prend pas en charge les devis hérités ou d’offre. Seul le type de modèle
CUSTOMIZABLE_QUOTE_TEMPLATE
peut être utilisé.
Association des signataires de devis
Si vous activez le devis pour les signatures électroniques, vous devrez également créer une association entre le devis et les contacts qui signent en utilisant un libellé d’association spécifique de devis à contact. Plutôt que d’utiliser les points de terminaison d’association par défaut indiqués ci-dessus, vous devrez effectuer une requêtePUT
à l’URL suivante :
/crm/v4/objects/quote/{quoteId}/associations/contact/{contactId}
Dans le corps de la requête, vous devrez spécifier associationCategory
et associationTypeId
, comme indiqué ci-dessous :
Créer un devis avec les associations (requête unique)
Le corps de requête suivant créera un nouveau devis avec des associations à un modèle de devis, à une transaction, à deux lignes de produits et à un contact.Pour que le corps de la requête ci-dessous crée correctement un devis dans votre compte, vous devrez mettre à jour les ID d’objets dans le champ
associations
afin qu’ils correspondent aux données existantes dans votre CRM. Consultez la section Récupération des identifiants pour les associations pour plus d’informations.POST
/crm/v3/objects/quote
Paramètre | Type | Description |
---|---|---|
properties | Objet | Valeurs des propriétés pour définir les détails du devis. Les propriétés requises sont hs_title et hs_expiration_date :
|
associations | Tableau | Les autres fiches d’informations du CRM et les autres objets associés au devis. Pour qu’un devis puisse être publié, une transaction et un modèle de devis doivent lui être associés. Les lignes de produits associées à un devis doivent être distinctes des lignes de produits associées à la transaction du devis (vous devez créer des copies des lignes de produits). Pour définir chaque association, incluez un objet distinct dans ce tableau avec les champs suivants :
|
Remarque :
Ces lignes de produit doivent être différentes des lignes de produit d’autres objets, même si elles sont associées (par exemple, associer un devis à une transaction). Voir la documentation de l’API des lignes de produit pour plus d’informations.Mettre à jour l’état du devis
L’état d’un devis décrit sa progression dans le processus de création, de sa configuration initiale à sa publication et son accès public. L’état du devis peut également refléter son processus d’approbation, si les approbations de devis sont activées pour le compte. Lorsque vous définissez l’état d’un devis, HubSpot renseigne automatiquement certaines propriétés. Vous pouvez mettre à jour l’état d’un devis en effectuant une requêtePATCH
à /crm/v3/objects/quote/{quoteId}
.
L’état d’un devis est basé sur le champ hs_status
. Certains états de devis permettent aux utilisateurs de modifier, de publier et d’utiliser le devis dans les workflows d’approbation des devis. Vous trouverez ci-dessous les états de devis disponibles.
- Aucun état : si aucune valeur n’est fournie pour le champ
hs_status
, le devis aura le statut Minimal. Le devis apparaîtra sur la page index de l’outil Devis, mais ne pourra pas être modifié directement. Les devis à cet état peuvent toujours être utilisés dans l’automatisation, tels que l’outil Séquences, et sont également disponibles pour l’analyse dans l’outil Rapports. DRAFT
: permet de modifier le devis dans HubSpot. Cet état peut être utile lorsque le devis n’est pas entièrement configuré ou si vous préférez autoriser les commerciaux à terminer le processus de configuration du devis dans HubSpot.APPROVAL_NOT_NEEDED
: publie le devis à une URL publiquement accessible (hs_quote_link
) sans nécessiter d’être approuvé.PENDING_APPROVAL
: indique que le devis est en attente d’approbation avant de pouvoir être publié.APPROVED
: le devis a été approuvé et est maintenant publié à une URL publiquement accessible (hs_quote_link
).REJECTED
: indique que le devis a été configuré, mais qu’il n’a pas été approuvé pour publication et qu’il doit être modifié avant de pouvoir être soumis à nouveau pour approbation.
Remarque :
Si vous activez les signatures électroniques sur le devis, vous ne pourrez pas publier le devis si vous avez dépassé votre limite mensuelle de signatures électroniques.Remarque :
Par défaut, HubSpot définira la propriétéhs_template_type
du devis sur CUSTOMIZABLE_QUOTE_TEMPLATE
après avoir mis à jour l’état du devis. Ce type de modèle est pris en charge par l’API v3, tandis que les types de modèles suivants sont des modèles hérités qui ne sont plus pris en charge :QUOTE
PROPOSAL
Propriétés définies par l’état du devis
La mise à jour de l’état du devis mettra à jour les propriétés suivantes :hs_quote_amount
: calculé sur la base des lignes de produits, taxes, remises et frais associés.hs_domain
: défini à partir du modèle de devis associé.hs_slug
: généré aléatoirement si pas fourni explicitement.hs_quote_total_preference
: défini en fonction des paramètres de votre compte. Si vous n’avez pas configuré ce paramètre, la valeur du champ total_first_payment s’affiche par défaut.hs_timezone
: par défaut, le fuseau horaire de votre compte HubSpot.hs_locale
: défini à partir du modèle de devis associé.hs_quote_number
: défini en fonction de la date et de l’heure actuelles, à moins qu’une date ne soit fournie.hs_language
: défini à partir du modèle de devis associé.hs_currency
: défini en fonction de la transaction associée. Si vous n’avez pas associé une transaction à la proposition, celle-ci sera réglée par défaut sur la devise par défaut de votre compte HubSpot.
hs_pdf_download_link
: rempli avec une URL d’un PDF pour le devis.hs_locked
: permet de définir sur la valeurtrue
. Pour modifier des propriétés après avoir publié un devis, vous devez tout d’abord mettre à jour lehs_status
du devis pour le ramener surDRAFT
,PENDING_APPROVAL
ouREJECTED
.hs_quote_link
: l’URL du devis accessible au public. Il s’agit d’une propriété en lecture seule qui ne peut pas être définie via l’API après publication.hs_esign_num_signers_required
: si vous avez activé les signatures électroniques, affiche le nombre de signatures requises.hs_payment_status
: statut de la collecte des paiements, si vous avez activé les paiements. Lors de la publication avec les paiements activés, cette propriété sera définie sur EN ATTENTE. Une fois que l’acheteur a effectué le paiement via le devis, le statut sera automatiquement mis à jour en conséquence. En savoir plus sur l’activation des paiements.
Récupérer des devis
Vous pouvez récupérer des devis individuellement ou par lots.- Pour récupérer un devis individuel, effectuez une requête
GET
à/crm/v3/objects/quotes/{quoteID}
. - Pour demander une liste de tous les devis, effectuez une requête
GET
à/crm/v3/objects/quotes
.
Paramètre | Description |
---|---|
properties | Une liste séparée par des virgules des propriétés à renvoyer dans la réponse. Si le contact du devis demandé n’a pas de valeur pour une propriété, il 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 le devis demandé n’a pas de valeur pour une propriété, il 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. |
POST
à crm/v3/objects/quotes/batch/read
et incluez les ID dans le corps de la requête. Vous pouvez également inclure un tableau de properties
pour indiquer les propriétés à renvoyer. 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.
Périmètres d’accès
Les périmètres suivants sont requis pour une application afin de créer un devis publiable valide :crm.objects.quotes.write
,crm.objects.quotes.read
,crm.objects.line_items.write
,crm.objects.line_items.read
,crm.objects.owners.read
,crm.objects.contacts.write
,crm.objects.contacts.read
,crm.objects.deals.write
,crm.objects.deals.read
,crm.objects.companies.write
,crm.objects.companies.read
crm.schemas.quote.read
,crm.schemas.line_items.read
,crm.schemas.contacts.read
,crm.schemas.deals.read
,crm.schemas.companies.read