Verificar API de direitos
A API Verificar direitos fornece endpoints que permitem obter uma lista de direitos válidos, detalhes sobre as características dos direitos e as informações de uso mais recentes de um direito.
Para acessar esta API, o plug-in de verificação de direito (sn_ent_verify) deve ser ativado.
Esta API é fornecida no namespace sn_ent_verify.
O usuário de chamada deve ter a função sn_pss_core.pss_integrator.
- Conta [customer_account]
- Consumidor [csm_consumer]
- Direito [service_entitlement]
- Característica de direito [sn_pss_core_entitlement_characteristic]
- Usos de direito [sn_pss_core_entitlement_usage]
- Residência [csm_household]
- Base de instalação [sn_install_base_item]
- Oferta de produto [sn_prd_pm_product_offering]
- Modelo do produto [cmdb_model]
- Contrato de serviço [sn_pss_core_service_contract]
- Linha de contrato de serviço [sn_pss_core_service_contract_line]
- Produto vendido [sn_install_base_sold_product]
Verificar direitos - /sn_ent_verify/verifyentitlements
Retorna os registros de direito válidos com base no filtro fornecido.
- Conta
- Consumidor
- Contrato
- Residência
- Base de instalação
- Modelo de produto
- Oferta de produto
- Linha do contrato de serviço
- Direito vendido
- Produto vendido
- Estado
Quando vários parâmetros de filtro são passados, o endpoint aplica o operador AND aos parâmetros. Por exemplo, se você passar parâmetros de filtro como "conta = boxeo" e "estado = rascunho", o endpoint retornará todos os direitos com Conta = boxeo E estado = rascunho.
Você pode implementar a paginação para os resultados de retorno aprovando os parâmetros de paginação do sistema sysparm_offset e sysparm_limit. Por padrão sysparm_offset, está definido como 0 e sysparm_limit está definido como 10. Portanto, se após a aplicação do filtro 100 direitos atenderem aos critérios, a resposta incluirá os primeiros 10 direitos. Você pode modificar esses valores passando-os na chamada do endpoint.
Formato da URL
URL com controle de versão: /api/sn_ent_verify/v1/verifyentitlements
URL padrão: /api/sn_ent_verify/verifyentitlements
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| api_version | Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres |
| sysparm_limit | Opcional. Número máximo de registros a serem retornados. Para solicitações que excedem esse número de registros, use o parâmetro sysparm_offset para paginar a recuperação do registro. Na resposta, o parâmetro booliano hasMore é retornado. Indica se há mais registros a serem retornados que atendam aos critérios de filtro. Tipo de dados: número Padrão: 10 Máximo: 100 |
| sysparm_offset | Opcional. Índice de registro inicial para o qual a recuperação de registros será iniciada. Use este valor para paginar a recuperação do registro. Essa funcionalidade permite a recuperação de todos os registros, independentemente do número de registros, em pequenos blocos gerenciáveis. Por exemplo, na primeira vez que você chama este endpoint, sysparm_offset é definido como "0". Para simplesmente percorrer todos os registros disponíveis, use Não passe um número negativo no parâmetro sysparm_offset. Tipo de dados: número Padrão: 0 |
| Nome | Descrição |
|---|---|
| conta | O parâmetro account ou consumer deve ser passado. Eles são mutuamente exclusivos. Sys_id do registro de conta para o qual os registros de direito serão retornados. Localizado na tabela Conta [customer_account]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| cliente | O parâmetro account ou consumer deve ser passado. Eles são mutuamente exclusivos. Sys_id do registro do consumidor para o qual os registros de direito serão retornados. Localizado na tabela Consumidor [csm_consumer]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| contrato | Sys_id do registro de contrato para o qual os registros de direito serão retornados. Localizado na tabela Contrato [sn_pss_core_service_contract]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| display_value | Sinalizador que indica se o valor do campo associado, o valor de exibição ou ambos devem ser retornados. Valores válidos:
Tipo de dados: cadeia de caracteres Padrão: falso |
| residência | Sys_id do registro da residência para o qual os registros de direito serão retornados. Localizado na tabela Residência [csm_household]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| install_base | Sys_id do registro de base de instalação para o qual os registros de direito serão retornados. Localizado na tabela Base de instalação [sn_install_base_item]. O endpoint usa o sys_id do registro da base de instalação para pesquisar a tabela Produto vendido coberto [sn_install_base_m2m_contract_sold_product]" para retornar todos os direitos cobertos pela base de instalação associada. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| Produto | Sys_id do registro do produto para o qual os registros de direito serão retornados. Localizado na tabela Modelo de Produto [cmdb_model]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| produto_oferta | Sys_id do registro de oferta de produto para o qual os registros de direito serão retornados. Localizado na tabela Oferta de produto [sn_prd_pm_product_offering]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| linha_de_contrato_de_serviço | Sys_id do registro de linha do contrato de serviço para o qual os registros de direito serão retornados. Localizado na tabela Linha de contrato de serviço [sn_pss_core_service_contract_line]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| direito_vendido | Sys_id do registro de direito vendido para o qual os registros de direito serão retornados. Localizado na tabela Produto vendido [sn_install_base_sold_product]. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| produto_vendido | Sys_id do registro do produto vendido para o qual os registros de direito serão retornados. Localizado na tabela Produto vendido [sn_install_base_sold_product]. O endpoint usa o sys_id do registro de Produto vendido para pesquisar a tabela Produto vendido coberto [sn_install_base_m2m_contract_sold_product]" para retornar todos os direitos cobertos pelo produto vendido associado. Tipo de dados: cadeia de caracteres Padrão: nenhum |
| estado | Estado dos direitos a serem retornados. Valores válidos:
Tipo de dados: cadeia de caracteres Padrão: todos |
| Nome | Descrição |
|---|---|
| Nenhum(a) |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml. Padrão: application/json |
| Cabeçalho | Descrição |
|---|---|
| Nenhum(a) |
Códigos de status
Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.
| Código de status | Descrição |
|---|---|
| 200 | Bem-sucedido. A solicitação foi processada com sucesso. |
| 403 | Proibido. O usuário não tem direitos de acesso ao registro especificado. |
| 404 | Não encontrado. O item solicitado não foi encontrado. |
| 500 | Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro. |
Parâmetros do corpo da resposta (JSON ou XML)
| Nome | Descrição |
|---|---|
| direitos | Lista de direitos que correspondem aos critérios de filtro aprovados. Tipo de dados: matriz de objetos |
| direitos.conta | Sys_id do registro de conta associado a este direito. Localizado na tabela Conta [customer_account]. Tipo de dados: cadeia de caracteres |
| direitos.consumidor | Sys_id do registro do consumidor associado a este direito. Localizado na tabela Consumidor [csm_consumer]. Tipo de dados: cadeia de caracteres |
| direitos.contrato | Sys_id do registro do contrato associado a este direito. Localizado na tabela Contrato [sn_pss_core_service_contract]. Tipo de dados: cadeia de caracteres |
| end_date | Valor do campo Data de término no registro de direito associado. Tipo de dados: cadeia de caracteres |
| direitos.direito_nome | Nome do direito. Tipo de dados: cadeia de caracteres |
| direitos.residência | Sys_id do registro da residência associado a este direito. Localizado na tabela Residência [csm_household]. Tipo de dados: cadeia de caracteres |
| direitos.produto | Sys_id do registro do produto associado a este direito. Localizado na tabela Modelo de Produto [cmdb_model]. Tipo de dados: cadeia de caracteres |
| direitos.oferta_do_produto | Sys_id do registro de oferta de produto associado a este direito. Localizado na tabela Oferta de produto [sn_prd_pm_product_offering]. Tipo de dados: cadeia de caracteres |
| direitos.service_contract_line | Sys_id do registro de linha do contrato de serviço associado a este direito. Localizado na tabela Linha de contrato de serviço [sn_pss_core_service_contract_line]. Tipo de dados: cadeia de caracteres |
| direitos.sold_entitlement | Sys_id do registro de direito vendido associado a este direito. Localizado na tabela Produto vendido [sn_install_base_sold_product]. Tipo de dados: cadeia de caracteres |
| direitos.data_início | Valor do campo Data de início no registro de direito associado. Tipo de dados: cadeia de caracteres |
| direitos.estado | Estado do registro de direitos. Valores válidos:
Tipo de dados: cadeia de caracteres |
| direitos.sys_id | Sys_id do registro de direito. Localizado na tabela Direito [service_entitlement]. Tipo de dados: cadeia de caracteres |
| erro | Descreve o erro ocorrido. Tipo de dados: objeto Exemplos de respostas de erro:
|
| erro.detalhe | Informações detalhadas sobre o motivo da falha na chamada do endpoint. Tipo de dados: cadeia de caracteres |
| mensagem.erro | Mensagem que descreve o erro em alto nível. Tipo de dados: cadeia de caracteres |
| hasMore | Sinalizador que indica se há mais registros de direito a serem retornados. Valores válidos:
Tipo de dados: booliano |
| status | Status da chamada do endpoint. Valores válidos:
Tipo de dados: cadeia de caracteres |
| sysparm_limit | Se os parâmetros sysparm_limit foram passados na chamada do endpoint, ele conterá o valor passado, caso contrário, conterá o valor padrão. Tipo de dados: número |
| sysparm_offset | Se os parâmetros sysparm_offset foram passados na chamada do endpoint, ele conterá o valor passado, caso contrário, conterá o valor padrão. Tipo de dados: número |
Solicitação de cURL
O exemplo de código a seguir mostra como retornar direitos de uma conta específica.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?account=9e2fd2ee11b43110f877366201dea674" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Retornar resultados:
{
"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,
"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,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
}
],
"status": "success"
}
}Solicitação de cURL
O exemplo de código a seguir mostra como retornar direitos para uma conta e linha de contrato de serviço específicas.
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"Retornar resultados:
{
"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,
"sold_entitlement": null,
"product": null,
"start_date": "2023-11-21",
"end_date": ""
}
],
"status": "success"
}
}Solicitação de cURL
O exemplo de código a seguir mostra uma resposta de erro.
curl "https://instance.service-now.com/api/sn_ent_verify/verifyentitlements?service_contract_line=e79dce4151723d10f877bf82d3ddf31d" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Retornar resultados:
{
"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"
}Verificar direitos - /sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}
Retorna detalhes do registro de característica de direito especificado e seu registro de uso mais recente.
O registro de uso mais recente de uma característica é definido como o registro em que a data de início do período é menor ou igual à data atual e a data de término do período é maior ou igual à data atual.
Formato da URL
URL com controle de versão: /api/sn_ent_verify/v1/verifyentitlements/getEntitlementCharacteristic/{id}
URL padrão: /api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/{id}
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| api_version | Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Somente especifique este valor para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres |
| ID | Sys_id do registro de característica de direito a ser retornado. Localizado na tabela Característica de direito [sn_pss_core_entitlement_characteristic]. Tipo de dados: cadeia de caracteres |
| Nome | Descrição |
|---|---|
| display_value | Sinalizador que indica se o valor do campo associado, o valor de exibição ou ambos devem ser retornados. Valores válidos:
Tipo de dados: cadeia de caracteres Padrão: falso |
| Nome | Descrição |
|---|---|
| Nenhum(a) |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Tipos compatíveis: application/json ou application/xml. Padrão: application/json |
| Cabeçalho | Descrição |
|---|---|
| Nenhum(a) |
Códigos de status
Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.
| Código de status | Descrição |
|---|---|
| 200 | Bem-sucedido. A solicitação foi processada com sucesso. |
| 403 | Proibido. O usuário não tem direitos de acesso ao registro especificado. |
| 404 | Não encontrado. O item solicitado não foi encontrado. |
| 500 | Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro. |
Parâmetros do corpo da resposta (JSON ou XML)
| Nome | Descrição |
|---|---|
| característica | Sys_id do registro de característica de direito associado. Localizado na tabela Característica [sn_prd_pm_characteristic]. Tipo de dados: cadeia de caracteres |
| opção_característica | Sys_id do registro de opções de característica associado. Localizado na tabela Opção de característica [sn_prd_pm_characteristic_option]. Tipo de dados: cadeia de caracteres |
| direito_uso | Detalhes sobre o registro de uso de direito associado ao registro de característica de direito especificado. Tipo de dados: matriz de objetos |
| entitlement_usage.entitlement_characteristic | Sys_id do registro de característica de direito associado. Localizado na tabela Característica de direito [sn_pss_core_entitlement_characteristic]. Tipo de dados: cadeia de caracteres |
| entitlement_usage.period_end | Valor do campo de fim do período no registro de uso de direito. Este valor é a data em que o acompanhamento de uso termina para este direito. Tipo de dados: cadeia de caracteres |
| entitlement_usage.period_start | Valor do campo de início do período no registro de uso de direito. Este valor é a data em que o acompanhamento de uso começa para este direito. Tipo de dados: cadeia de caracteres |
| entitlement_usage.sys_id | SYS ID do registro de uso de direito retornado. Localizado na tabela Usos de direito [sn_pss_core_entitlement_usage]. Tipo de dados: cadeia de caracteres |
| entitlement_usage.total_units | Número total de unidades compradas. Localizado no campo de unidades totais no registro de uso de direito. Tipo de dados: cadeia de caracteres |
| entitlement_usage.used_units | Número de unidades que foram usadas. Localizado no campo de unidades usadas no registro de uso de direito. Tipo de dados: cadeia de caracteres |
| sys_id | SYS ID do registro da característica de direito. Localizado na tabela Característica de direito [sn_pss_core_entitlement_characteristic]. Tipo de dados: cadeia de caracteres |
| tipo | Valor do campo de tipo no registro de característica de direito. Valores possíveis:
Tipo de dados: cadeia de caracteres |
| valor | Cobertura para fornecer a característica. Para algumas características, as coberturas são definidas na tabela Opção de característica. No entanto, se não houver coberturas definidas na tabela Opção de característica, você poderá passar as informações de cobertura no parâmetro value. As opções de característica são definidas somente para os tipos de característica de:
Por exemplo, se a característica for "Número de substituições" e suas coberturas não estiverem definidas na tabela Opção de característica, você poderá especificar as coberturas, como "10", "20", neste parâmetro. Nota: Este parâmetro contém o valor de cobertura final da característica. Se houver informações na tabela Opção de característica, elas serão propagadas para este parâmetro. Tipo de dados: cadeia de caracteres |
Solicitação de cURL
O exemplo de código a seguir mostra como chamar este endpoint usando todos os seus valores padrão.
curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Retornar resultados:
{
"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"
}
]
}
}Solicitação de cURL
O exemplo de código a seguir mostra como chamar este endpoint e retornar todos os valores de exibição.
curl "https://instance.servicenow.com/api/sn_ent_verify/verifyentitlements/getEntitlementCharacteristic/3c817faa43823110341605ed0bb8f23a?display_value=all" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"Retornar resultados:
{
"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"
}
}
]
}
}