Devis

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.

example-quote-api

Exemple de cas d'utilisation : vous devez créer une proposition de contrat pour un client qui souhaite acheter l'un de vos forfaits annuels de services d'audit SEO.

Découvrez ci-dessous comment créer un devis via l'API et configurer ses différentes propriétés, associations, états, etc.

Remarque : l'API Devis ne prend pas en charge la création de devis avec signature électronique ou le traitement des paiements via Stripe ou HubSpot. Vous ne pouvez pas non plus configurer de remises, de frais ou de taxes récurrents au niveau des devis via l'API. Pour utiliser ces fonctionnalités, vous pouvez plutôt créer le devis dans HubSpot

Présentation

Le processus de création de devis peut être divisé en plusieurs étapes :

  1. Créer un devis : créez un devis avec quelques détails, tels que le nom et la date d'expiration.
  2. Configurer des associations : associez 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.
  3. Définir l'état du devis : définissez 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.
  4. 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ête POST à/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, une transaction et ses lignes de produits.

En fonction de votre workflow préféré, vous pouvez créer un devis avec des associations via une seule requête POST.

Dans le corps de l'article, ajoutez les propriétés requises suivantes pour configurer ses détails de base.

hs_title  string (required)

The name of the quote.

hs_expiration_date  string (required)

The date that the quote expires.

The above are just the minimum required properties to get a quote started. To see all available quote properties, make a GET request to crm/v3/properties/quotes. Learn more about the properties API.

// example POST request body { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-12-10" } }

La réponse comprendra un identifiant, 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}.

Ajout d'associations

Pour créer un devis complet, vous devez l'associer à d'autres fiches d'informations CRM, tels que des lignes de produits, à l'aide de l'API d'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 produits 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éss.
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ête GET 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.

GET request for line items /crm/v3/objects/line_items?properties=name GET request for quote templates /crm/v3/objects/quote_template?properties=hs_name GET request for deals /crm/v3/objects/deals?properties=dealname GET request for contacts /crm/v3/objects/contacts?properties=email GET request for companies /crm/v3/objects/companies?properties=name GET request for discounts crm/v3/objects/discounts?properties=hs_type,hs_value GET request for fees crm/v3/objects/fees?properties=hs_type,hs_value GET request for taxes crm/v3/objects/taxes?properties=hs_type,hs_value #GET request for line items curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/line_items?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for quote templates curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/quote_templates?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for deals curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/deals?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for contacts curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/contacts?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for companies curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/companies?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for discounts curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/discounts?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for fees curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/fees?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #GET request for taxes curl --request GET \ --url 'https://api.hubapi.com/crm/v3/properties/taxes?archived=false' \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

Chaque appel réussi renverra une réponse de 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.

// Example quote template GET response { "results": [ { "id": "235425923863", "properties": { "hs_createdate": "2023-06-12T16:27:32.794Z", "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z", "hs_name": "Default Basic", "hs_object_id": "235425923863" }, "createdAt": "2023-06-12T16:27:32.794Z", "updatedAt": "2023-06-12T16:27:32.794Z", "archived": false }, { "id": "235425923864", "properties": { "hs_createdate": "2023-06-12T16:27:32.794Z", "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z", "hs_name": "Default Modern", "hs_object_id": "235425923864" }, "createdAt": "2023-06-12T16:27:32.794Z", "updatedAt": "2023-06-12T16:27:32.794Z", "archived": false }, { "id": "235425923865", "properties": { "hs_createdate": "2023-06-12T16:27:32.794Z", "hs_lastmodifieddate": "2023-06-12T16:27:32.794Z", "hs_name": "Default Original", "hs_object_id": "235425923865" }, "createdAt": "2023-06-12T16:27:32.794Z", "updatedAt": "2023-06-12T16:27:32.794Z", "archived": false } ] }

Création d'associations

Une fois vos identifiants récupérés, vous pouvez appeler l'API d'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ête PUT à l'aide de la structure d'URL ci-dessous :

 /crm/v4/objects/quotes/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}

Use this table to describe parameters / fields
ParameterDescription
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. 

Vous trouverez ci-dessous des exemples de requêtes PUT pour chaque type d'objet.

PUT request to associate a line item /crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{lineItemId} PUT request to associate a quote template /crm/v4/objects/quotes/{quoteId}/associations/default/quote_template/{quoteTemplateId} PUT request to associate a deal /crm/v4/objects/quotes/{quoteId}/associations/default/deals/{dealId} PUT request to associate contacts /crm/v4/objects/quotes/{quoteId}/associations/default/contacts/{contactId} PUT request to associate companies /crm/v4/objects/quotes/{quoteId}/associations/default/companies/{companyId} PUT request to associate discounts /crm/v4/objects/quotes/{quoteId}/associations/default/discounts/{discountId} PUT request to associate fees /crm/v4/objects/quotes/{quoteId}/associations/default/fees/{feeId} PUT request to associate taxes /crm/v4/objects/quotes/{quoteId}/associations/default/taxes/{taxId} #PUT request to associate line items curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{lineItemId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate a quote template curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quote_ID}/associations/default/quote_template/{quoteTemplateId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate a deal curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/deals/{dealId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate contacts curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/contacts/{contactId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate a company curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/companies/{companyId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate discounts curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/discounts/{discountId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate fees curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/fees/{feeId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN' #PUT request to associate taxes curl --request PUT \ --url https://api.hubapi.com/crm/v4/objects/quotes/{quoteId}/associations/default/line_items/{taxId} \ --header 'authorization: Bearer YOUR_ACCESS_TOKEN'

As an example, if your quote has an ID of 123456, the requests to associate the quote might include the following:

  • Line items (IDs: 55555, 66666): 
    • /crm/v4/objects/quotes/123456/associations/default/line_items/55555
    • /crm/v4/objects/quotes/123456/associations/default/line_items/66666
  • Quote template (ID: 987654):  /crm/v4/objects/quotes/123456/associations/default/quote_template/987654
  • Deal (ID: 345345): /crm/v4/objects/quotes/123456/associations/default/deals/345345

Chaque association réussie renverra une réponse de 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.

// Example response { "status": "COMPLETE", "results": [ { "from": { "id": "115045534742" }, "to": { "id": "102848290" }, "associationSpec": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 285 } }, { "from": { "id": "102848290" }, "to": { "id": "115045534742" }, "associationSpec": { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 286 } } ], "startedAt": "2023-10-12T16:48:40.624Z", "completedAt": "2023-10-12T16:48:40.712Z" }

Remarque : 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é.

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.

POST /crm/v3/objects/quote 

properties  object 

Quote details, which can be retrieved through the properties API. Required properties are: hs_title and hs_expiration_date.

⮑ hs_title  string (required)

The name of the quote.

⮑ hs_expiration_date  string (required)

The date that the quote expires.

⮑ hs_status  string

The quote status. Omitting this property on create will prevent users from being able to edit the quote in HubSpot.

associations  array

The quote's associated records. For a quote to be publishable, it must have an associated deal and quote template. 

// POST request to https://api.hubapi.com/crm/v3/objects/quote { "properties": { "hs_title": "CustomerName - annual SEO audit", "hs_expiration_date": "2023-09-30" }, "associations": [ { "to": { "id": 115045534742 }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 286 }] }, { "to": { "id": 14795354663 }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 64 }] }, { "to": { "id": 75895447 }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 67 }] }, { "to": { "id": 256143985 }, "types": [{ "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 67 }] } ] }

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ête PATCH à /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 à l'état Minimal 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.

Par exemple, la requête suivante permet de publier le devis à une URL publiquement accessible.

// PATCH request to https://api.hubapi.com/crm/v3/objects/quote/{QUOTE_ID} { "properties": { "hs_status": "APPROVAL_NOT_NEEDED" } }

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ées.
  • 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.

En outre, les propriétés ci-dessous seront calculées lorsque le devis passera à l'état Publié :

  • hs_pdf_download_link : rempli avec une URL d'un PDF pour le devis.
  • hs_locked : défini sur true. Pour modifier des propriétés après avoir publié un devis, vous devez tout d'abord mettre à jour le statut hs_status du devis pour le ramener sur BROUILLON, EN ATTENTE D'APPROBATION ou REJETÉ.
  • 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.

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

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.