API Vérifier les droits
L’API de vérification des autorisations fournit des points de terminaison qui vous permettent d’obtenir une liste des autorisations valides, des détails sur les caractéristiques des autorisations et des informations sur la dernière utilisation d’une autorisation.
Pour accéder à cette API, le module d’extension Vérification de l’autorisation (com.sn_ent_verify) doit être activé.
Cette API est fournie dans l’espace de noms sn_ent_verify .
L’utilisateur appelant doit avoir le rôle sn_pss_core.pss_integrator.
- Compte [customer_account]
- Consommateur [csm_consumer]
- Droit [service_entitlement]
- Caractéristique du droit [sn_pss_core_entitlement_characteristic]
- Utilisations des droits [sn_pss_core_entitlement_usage]
- Ménage [csm_household]
- Base d’installation [sn_install_base_item]
- Modèle de produit [cmdb_model]
- Offre de produits [sn_prd_pm_product_offering]
- Spécification de produit [sn_prd_pm_product_specification]
- Contrat de service [sn_pss_core_service_contract]
- Ligne de contrat de service [sn_pss_core_service_contract_line]
- Produit vendu [sn_install_base_sold_product]
Vérifier les droits : GET /sn_ent_verify/verifyentitlements
Renvoie les enregistrements d’autorisation valides en fonction du filtre fourni.
- Compte
- Consommateur
- Contrat
- Ménage
- Base d'installation
- Modèle de produit
- Offre de produits
- Spécification de produit
- Ligne du contrat de service
- Droit vendu
- Produit vendu
- État
Lorsque plusieurs paramètres de filtre sont transmis, le point de terminaison applique l’opérateur AND aux paramètres. Par exemple, si vous transmettez des paramètres de filtre tels que « compte = boxeo » et « état = brouillon », le point de terminaison renvoie tous les droits avec Compte = boxeo ET état = brouillon.
Vous pouvez implémenter la pagination pour les résultats de retour en transmettant les paramètres sysparm_offset de pagination système et sysparm_limit. Par défaut sysparm_offset , il est défini sur 0 et sysparm_limit sur 10. Donc, si après l’application du filtre, 100 autorisations répondent aux critères, la réponse inclura les 10 premières autorisations. Vous pouvez modifier ces valeurs en les transmettant dans l’appel du point de terminaison.
Format d'URL
URL versionnée : /api/sn_ent_verify/{api_version}/verifyentitlements
URL par défaut : /api/sn_ent_verify/verifyentitlements
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| sysparm_limit | Facultatif. Nombre maximal d'enregistrements à renvoyer. Pour les demandes qui dépassent ce nombre d'enregistrements, utilisez le paramètre sysparm_offset pour paginer la récupération d'enregistrements. Dans la réponse, le paramètre hasMore booléen est renvoyé. Elle indique s’il existe d’autres enregistrements à renvoyer qui répondent aux critères de filtre. Type de données : nombre Valeur par défaut : 10 Maximum : 100 |
| sysparm_offset | Facultatif. Index de début des enregistrements pour lequel commencer à récupérer des enregistrements. Utilisez cette valeur pour paginer la récupération des enregistrements. Cette fonctionnalité permet de récupérer tous les enregistrements, quel que soit le nombre d'enregistrements, par petits blocs gérables. Par exemple, lors du premier appel de ce point de terminaison, sysparm_offset est défini sur « 0 ». Pour parcourir simplement tous les enregistrements disponibles, utilisez le paramètre Ne transmettez pas de nombre négatif dans le paramètre sysparm_offset. Type de données : nombre Par défaut : 0 |
| Nom | Description |
|---|---|
| compte | Le account paramètre ou consumer doit être transmis. Ils s'excluent mutuellement. Sys_id de l’enregistrement de compte pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Table : Compte [customer_account] |
| consommateur | Le account paramètre ou consumer doit être transmis. Ils s'excluent mutuellement. Sys_id de l’enregistrement de consommateur pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Table : Consommateur [csm_consumer] |
| contrat | Sys_id de l’enregistrement du contrat pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Table : Contrat [sn_pss_core_service_contract] |
| display_value | Marqueur indiquant s’il faut renvoyer la valeur de champ associée, la valeur d’affichage ou les deux. Valeurs valides :
Type de données : chaîne Valeur par défaut : false |
| household | Sys_id de l’enregistrement du ménage pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Tableau : Ménage [csm_household] |
| install_base | Sys_id de l’enregistrement de base d’installation pour lequel renvoyer les enregistrements d’autorisation. Le point de terminaison utilise la sys_id de l’enregistrement de la base d’installation pour rechercher dans la table Produit vendu couvert [sn_install_base_m2m_contract_sold_product] afin de renvoyer toutes les autorisations couvertes par la base d’installation associée. Type de données : chaîne Par défaut : aucun Table : Base d’installation [sn_install_base_item] |
| produit | Sys_id de l’enregistrement de produit pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Table : Modèle de produit [cmdb_model] |
| product_offering | Sys_id de l’enregistrement d’offre de produit pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Table : Offre de produits [sn_prd_pm_product_offering] |
| product_specification | Sys_id d’enregistrement de spécification de produit pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Tableau : Spécification de produit [sn_prd_pm_product_specification] |
| service_contract_line | Sys_id de l’enregistrement de ligne de contrat de service pour lequel renvoyer les enregistrements d’autorisation. Type de données : chaîne Par défaut : aucun Table : Ligne de contrat de service [sn_pss_core_service_contract_line] |
| sold_entitlement | Sys_id de l’enregistrement du droit vendu pour lequel renvoyer les enregistrements du droit. Type de données : chaîne Par défaut : aucun Table : Produit vendu [sn_install_base_sold_product] |
| sold_product | Sys_id de l’enregistrement du produit vendu pour lequel renvoyer les enregistrements d’autorisation. Le point de terminaison utilise le sys_id de l’enregistrement du produit vendu pour rechercher dans la table Produit vendu couvert [sn_install_base_m2m_contract_sold_product] et renvoyer toutes les autorisations couvertes par le produit vendu associé. Type de données : chaîne Par défaut : aucun Table : Produit vendu [sn_install_base_sold_product] |
| État | État des droits de retour. Valeurs valides :
Type de données : chaîne Par défaut : Tout |
| Nom | Description |
|---|---|
| Aucun |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 403 | Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié. |
| 404 | Introuvable. L’élément demandé est introuvable. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de la réponse (JSON ou XML)
| Nom | Description |
|---|---|
| droits | Liste des droits qui correspondent aux critères de filtre réussis. Type de données : tableau d’objets |
| droits.compte | Sys_id de l’enregistrement de compte associé à ce droit. Type de données : chaîne Table : Compte [customer_account] |
| droits.consommateur | Sys_id de l’enregistrement de consommateur associé à ce droit. Type de données : chaîne Table : Consommateur [csm_consumer] |
| droits.contrat | Sys_id de l’enregistrement du contrat associé à ce droit. Type de données : chaîne Table : Contrat [sn_pss_core_service_contract] |
| entitlements.end_date | Valeur du champ Date de fin sur l’enregistrement d’autorisation associé. Type de données : chaîne |
| entitlements.entitlement_name | Nom du droit. Type de données : chaîne |
| droits.ménage | Sys_id de l’enregistrement de ménage associé à ce droit. Type de données : chaîne Tableau : Ménage [csm_household] |
| droits.produit | Sys_id de l’enregistrement de produit associé à ce droit. Type de données : chaîne Table : Modèle de produit [cmdb_model] |
| entitlements.product_offering | Sys_id de l’enregistrement d’offre de produit associé à ce droit. Type de données : chaîne Table : Offre de produits [sn_prd_pm_product_offering] |
| entitlements.product_specification | Sys_id de l’enregistrement de spécification du produit associé à ce droit. Type de données : chaîne Tableau : Spécification de produit [sn_prd_pm_product_specification] |
| entitlements.service_contract_line | Sys_id de l’enregistrement de ligne de contrat de service associé à ce droit. Type de données : chaîne Table : Ligne de contrat de service [sn_pss_core_service_contract_line] |
| entitlements.sold_entitlement | Sys_id de l’enregistrement du droit vendu associé à ce droit. Type de données : chaîne Table : Produit vendu [sn_install_base_sold_product] |
| entitlements.start_date | Valeur du champ Date de début sur l’enregistrement d’autorisation associé. Type de données : chaîne |
| droits.état | État de l’enregistrement des droits. Valeurs possibles :
Type de données : chaîne |
| entitlements.sys_id | Sys_id de l’enregistrement de l’autorisation. Type de données : chaîne Table : Droit [service_entitlement] |
| erreur | Décrit l’erreur qui s’est produite. Type de données : objet Exemples de réponses d’erreur :
|
| erreur.détail | Informations détaillées sur le motif d’échec de l’appel du point de terminaison. Type de données : chaîne |
| message.erreur | Message qui décrit l’erreur à un niveau élevé. Type de données : chaîne |
| hasMore | Marqueur indiquant s’il existe d’autres enregistrements d’autorisation à renvoyer. Valeurs possibles :
Type de données : booléennes |
| état | État de l’appel du point de terminaison. Valeurs possibles :
Type de données : chaîne |
| sysparm_limit | Si les sysparm_limit paramètres ont été transmis dans l’appel de point de terminaison, ils contiennent la valeur transmise, sinon ils contiennent la valeur par défaut. Type de données : nombre |
| sysparm_offset | Si les sysparm_offset paramètres ont été transmis dans l’appel de point de terminaison, ils contiennent la valeur transmise, sinon ils contiennent la valeur par défaut. Type de données : nombre |
Demande cURL
L’exemple de code suivant montre comment renvoyer des autorisations pour un compte spécifique.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Renvoyer les résultats :
{
"result": {
"sysparm_offset": "0",
"sysparm_limit": "10",
"has_more": "false",
"entitlements": [
{
"sys_id": "38374bf251e27110f877bf82d3ddf30a",
"entitlement_name": "test ent",
"account": "9e2fd2ee11b43110f877366201dea674",
"consumer": null,
"household": null,
"contract": "0e1747f251e27110f877bf82d3ddf31c",
"service_contract_line": "da278fb251e27110f877bf82d3ddf3b7",
"state": "active",
"product_offering": null,
"product_specification": null,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
},
{
"sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
"entitlement_name": "tets entitlement",
"account": "9e2fd2ee11b43110f877366201dea674",
"consumer": null,
"household": null,
"contract": "0e1747f251e27110f877bf82d3ddf31c",
"service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
"state": "active",
"product_offering": null,
"product_specification": null,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
}
],
"status": "success"
}
}Demande cURL
L’exemple de code suivant montre comment renvoyer des autorisations pour un compte et une ligne de contrat de service spécifiques.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d&account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Renvoyer les résultats :
{
"result": {
"sysparm_offset": "0",
"sysparm_limit": "10",
"has_more": "false",
"entitlements": [
{
"sys_id": "e6ad4e4151723d10f877bf82d3ddf3fb",
"entitlement_name": "test entitlement",
"account": "9e2fd2ee11b43110f877366201dea674",
"consumer": null,
"household": null,
"contract": "0e1747f251e27110f877bf82d3ddf31c",
"service_contract_line": "e79dce4151723d10f877bf82d3ddf31d",
"state": "active",
"product_offering": null,
"product_specification": null,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
}
],
"status": "success"
}
}Demande cURL
L’exemple de code suivant montre une réponse d’erreur.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Renvoyer les résultats :
{
"error": {
"detail": "At least one of Account or Consumer parameter is mandatory.",
"message": "At least one of Account or Consumer parameter is mandatory."
},
"status": "failure"
}Vérifier les droits : GET /sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}
Renvoie les détails de l’enregistrement des caractéristiques du droit spécifié et son dernier enregistrement d’utilisation.
Le dernier enregistrement d’utilisation d’une caractéristique est défini comme l’enregistrement dont la date de début de la période est inférieure ou égale à la date actuelle et la date de fin de la période est supérieure ou égale à la date actuelle.
Format d'URL
URL versionnée : /api/sn_ent_verify/{api_version}/verifyentitlements/getEntitlementCharacteristic/{id}
URL par défaut : /api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}
Paramètres de demande pris en charge
| Nom | Description |
|---|---|
| api_version | Facultatif. Version du point de terminaison auquel accéder. Par exemple, v1 ou v2. Spécifiez uniquement cette valeur pour utiliser une version de point de terminaison différente de la dernière. Type de données : chaîne |
| id | Sys_id de l’enregistrement des caractéristiques du droit à renvoyer. Type de données : chaîne Table : Caractéristique du droit [sn_pss_core_entitlement_characteristic] |
| Nom | Description |
|---|---|
| display_value | Marqueur indiquant s’il faut renvoyer la valeur de champ associée, la valeur d’affichage ou les deux. Valeurs valides :
Type de données : chaîne Valeur par défaut : false |
| Nom | Description |
|---|---|
| Aucun |
En-têtes
Les en-têtes de demande et de réponse suivants s'appliquent à cette action HTTP uniquement ou s'appliquent à cette action d'une manière distincte. Pour obtenir la liste des en-têtes généraux utilisés dans l’API REST, consultez En-têtes d’API REST pris en charge.
| En-tête | Description |
|---|---|
| Accepter | Format de données du corps de la réponse. Types pris en charge : application/json ou application/xml. Valeur par défaut : application/json |
| En-tête | Description |
|---|---|
| Aucun |
Codes d'état
Les codes d'état suivants s'appliquent à cette action HTTP. Pour obtenir la liste des codes d’état possibles utilisés dans l’API REST, consultez Codes de réponse HTTP de l’API REST.
| Code d'état | Description |
|---|---|
| 200 | Réussi. La demande a été correctement traitée. |
| 403 | Interdit. L’utilisateur ne dispose pas des droits d’accès à l’enregistrement spécifié. |
| 404 | Introuvable. L’élément demandé est introuvable. |
| 500 | Erreur interne du serveur. Une erreur inattendue s'est produite lors du traitement de la demande. La réponse contient des informations supplémentaires sur l'erreur. |
Paramètres du corps de la réponse (JSON ou XML)
| Nom | Description |
|---|---|
| characteristic | Sys_id de l’enregistrement des caractéristiques du droit associé. Type de données : chaîne Table : Caractéristique [sn_prd_pm_characteristic] |
| characteristic_option | Sys_id de l’enregistrement des options de caractéristiques associées. Type de données : chaîne Table : Option de la caractéristique [sn_prd_pm_characteristic_option] |
| entitlement_usage | Détails sur l’enregistrement d’utilisation du droit associé à l’enregistrement de caractéristique du droit spécifié. Type de données : tableau d’objets |
| entitlement_usage.entitlement_characteristic | Sys_id de l’enregistrement des caractéristiques du droit associé. Type de données : chaîne Table : Caractéristique du droit [sn_pss_core_entitlement_characteristic] |
| entitlement_usage.period_end | Valeur du champ de fin de période dans l’enregistrement d’utilisation du droit. Cette valeur est la date à laquelle le suivi de l’utilisation prend fin pour ce droit. Type de données : chaîne |
| entitlement_usage.period_start | Valeur du champ de début de la période dans l’enregistrement d’utilisation du droit. Cette valeur est la date à laquelle le suivi de l’utilisation commence pour ce droit. Type de données : chaîne |
| entitlement_usage.sys_id | Sys_id de l’enregistrement d’utilisation du droit retourné. Type de données : chaîne Table : Utilisations des droits [sn_pss_core_entitlement_usage] |
| entitlement_usage.total_units | Nombre total d’unités achetées. Type de données : chaîne Table : dans le champ total_units de la table Utilisations des droits [sn_pss_core_entitlement_usage]. |
| entitlement_usage.used_units | Nombre d’unités qui ont été utilisées. Type de données : chaîne Table : dans le champ used_units de la table Utilisations du droit [sn_pss_core_entitlement_usage]. |
| sys_id | Sys_id de l’enregistrement des caractéristiques du droit. Type de données : chaîne Table : Caractéristique du droit [sn_pss_core_entitlement_characteristic] |
| type | Valeur du champ type dans l’enregistrement de caractéristique du droit. Valeurs possibles :
Type de données : chaîne |
| valide | Couverture pour donner la caractéristique. Pour certaines caractéristiques, les couvertures sont définies dans la table Option de caractéristique. Toutefois, si aucune couverture n’est définie dans la table Option de caractéristique, vous pouvez transmettre les informations de couverture dans le value paramètre. Les options de caractéristiques ne sont définies que pour les types de caractéristiques de :
Par exemple, si la caractéristique est « Nombre de remplacements » et que ses couvertures ne sont pas définies dans la table Option de caractéristique, vous pouvez spécifier les couvertures, telles que « 10 », « 20 » dans ce paramètre. Remarque :
Ce paramètre contient la valeur de couverture finale pour la caractéristique. Si des informations se trouvent dans la table Option de caractéristique, elles sont propagées à ce paramètre. Type de données : chaîne |
Demande cURL
L’exemple de code suivant montre comment appeler ce point de terminaison à l’aide de toutes ses valeurs par défaut.
curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Renvoyer les résultats :
{
"result": {
"sys_id": "3c817faa43823110341605ed0bb8f23a",
"characteristic": "b73177aa43823110341605ed0bb8f246",
"type": "coverage",
"characteristic_option": "ff617baa43823110341605ed0bb8f266",
"value": "Minor parts",
"entitlement_usage": [
{
"sys_id": "03e3224d51b23d10f877bf82d3ddf310",
"period_start": "2022-12-12",
"period_end": "2025-12-12",
"entitlement_characteristic": "3c817faa43823110341605ed0bb8f23a",
"total_units": "10",
"used_units": "5"
}
]
}
}Demande cURL
L’exemple de code suivant montre comment appeler ce point de terminaison et renvoyer toutes les valeurs d’affichage.
curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a?display_value=all" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Renvoyer les résultats :
{
"result": {
"sys_id": {
"label": "Sys ID",
"value": "3c817faa43823110341605ed0bb8f23a",
"displayValue": "3c817faa43823110341605ed0bb8f23a",
"type": "GUID"
},
"characteristic": {
"name": "characteristic",
"label": "Characteristic",
"value": "b73177aa43823110341605ed0bb8f246",
"display_value": "Repair parts covered",
"type": "reference"
},
"type": {
"name": "type",
"label": "Type",
"value": "coverage",
"display_value": "Coverage",
"type": "string"
},
"characteristic_option": {
"name": "characteristic_option",
"label": "Characteristic option",
"value": "ff617baa43823110341605ed0bb8f266",
"display_value": "Minor parts",
"type": "reference"
},
"value": {
"name": "value",
"label": "Value",
"value": "Minor parts",
"display_value": "Minor parts",
"type": "string"
},
"entitlement_usage": [
{
"sys_id": {
"label": "Sys ID",
"value": "03e3224d51b23d10f877bf82d3ddf310",
"displayValue": "03e3224d51b23d10f877bf82d3ddf310",
"type": "GUID"
},
"period_start": {
"name": "period_start",
"label": "Period start",
"value": "2022-12-12",
"display_value": "2022-12-12",
"type": "glide_date"
},
"period_end": {
"name": "period_end",
"label": "Period end",
"value": "2025-12-12",
"display_value": "2025-12-12",
"type": "glide_date"
},
"entitlement_characteristic": {
"name": "entitlement_characteristic",
"label": "Entitlement characteristic",
"value": "3c817faa43823110341605ed0bb8f23a",
"display_value": "Repair parts covered",
"type": "reference"
},
"total_units": {
"name": "total_units",
"label": "Total units",
"value": "10",
"display_value": "10",
"type": "string"
},
"used_units": {
"name": "used_units",
"label": "Used units",
"value": "5",
"display_value": "5",
"type": "string"
}
}
]
}
}