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.

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.

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. Vous pouvez également configurer le devis pour activer les signatures électroniques. 
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.

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.

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

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}.

Pour activer les signatures électroniques sur le devis, incluez la propriété booléenne hs_esign_enabled dans votre corps de demande 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. 

Vous devrez associer le devis aux signataires du devis ultérieurement. Bien que les contacts signant le devis existent en tant que contacts dans HubSpot, ils sont stockés en tant que types d'association distincts des contacts. Découvrez-en davantage sur l'association de devis avec des signataires de devis.

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.

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.

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.

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}

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

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.

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 demande PUT à l'URL suivante :

/crm/v4/objects/quote/{quoteId}/associations/contact/{contactId}

Dans le corps de la demande, vous devrez spécifier associationCategory et associationTypeId, comme indiqué ci-dessous :

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 

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.

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.
• hs_esign_num_signers_required : si vous avez activé les signatures électroniques, affiche le nombre de signatures requises.

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