API de compromisso

A API de compromisso fornece endpoints para interagir com o aplicativo de reserva de compromisso. Use esta API para reservar e reagendar compromissos, verificar os horários disponíveis e buscar detalhes da configuração de reserva de compromisso.

Antes de usar esta API, a configuração de reserva de compromisso e a configuração de serviço devem ser configuradas. Além disso, uma tarefa para a qual o compromisso está sendo reservado já deve existir. Para obter informações adicionais, confira Configuring Appointment Booking.

A Appointment API requer o plug-in Appointment Booking (com.snc.appointment_booking) e é fornecida no namespace sn_apptmnt_booking. Para acessar esta API, você deve ter a função snc_internal.

Compromisso - GET /sn_apptmnt_booking/appointment/calendar

Retorna o intervalo de tempo para o qual você pode reservar compromissos. Os resultados de retorno respeitam o lead time e as datas máximas futuras reserváveis configuradas na configuração do serviço de reserva de compromisso.

Para obter informações adicionais sobre a configuração do tempo de lead e das datas máximas reserváveis futuras, consulte Create or modify an appointment booking application configuration.

Você deve ter a função snc_internal ou snc_external para acessar este endpoint.

Formato de URL

URL com controle de versões: /api/sn_appt_booking/{api_version}/appointment/calendar

URL padrão: /api/sn_apptmnt_booking/appointment/calendar

Parâmetros de solicitação compatíveis

Tabela 1. Parâmetros de caminho

Nome	Descrição
api_version	Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres

Tabela 2. Parâmetros de consulta

Nome	Descrição
catalog_id	Obrigatório. Sys_id do produtor de registro configurado com uma configuração de serviço de reserva de compromisso. Localizado na tabela Produtor de registro [sc_cat_item_producer]. Tipo de dados: cadeia de caracteres
local	Obrigatório. Sys_id do local (cmn_location) do compromisso. Localizado na tabela Local [cmn_location]. Tipo de dados: cadeia de caracteres
opened_for	Obrigatório. Sys_id do usuário para o qual o compromisso está sendo reservado. Localizado na tabela Usuário [sys_user]. Tipo de dados: cadeia de caracteres

Tabela 3. Parâmetros do corpo da solicitação

Nome	Descrição
Nenhum

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.

Tabela 4. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Oferece suporte somente a application/json.

Tabela 5. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir 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 da REST API.

Tabela 6. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
400	Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
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

Nome	Descrição
resultado	Informações sobre os resultados da solicitação de endpoint. Tipo de dados: objeto "result": { "range_end": "String", "range_start": "String" }
resultado.intervalo_end	Fim do intervalo no qual os compromissos podem ser reservados. Fim do intervalo = Hoje + Máximo de dias futuros reserváveis Tipo de dados: cadeia de caracteres Formato: fuso horário do compromisso no formato interno de data e hora.
resultado.intervalo_início	Início do intervalo no qual os compromissos podem ser reservados. Início do intervalo = Hoje + Tempo de lead Tipo de dados: cadeia de caracteres Formato: fuso horário do compromisso no formato interno de data e hora.

Solicitação de cURL

O exemplo de código a seguir mostra como chamar este endpoint.

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/calendar?catalog_id=e4c1116b3b810300ce8a4d72f3efc40f&location=32e8499cdb2d2200d75270f5bf9619d6&opened_for=6816f79cc0a8016401c5a33be04be441" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Resultado:

{
  "result": {
    "range_start": "2023-02-08 03:52:27",
    "range_end": "2023-02-21 23:52:27"
  }
}

Compromisso - GET /sn_apptmnt_booking/appointment/configuration

Retorna a configuração definida em uma configuração de serviço de reserva de compromisso especificada.

Além disso, ele retorna as traduções e as preferências de data e hora do usuário necessárias para renderizar os slots nos widgets de reserva de compromisso.

Você deve ter a função snc_internal ou snc_external para acessar este endpoint.

Formato de URL

URL com controle de versões: /api/sn_apptmnt_booking/{api_version}/appointment/configuration

URL padrão: /api/sn_apptmnt_booking/appointment/configuration

Parâmetros de solicitação compatíveis

Tabela 7. Parâmetros de caminho

Nome	Descrição
api_version	Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres

Tabela 8. Parâmetros de consulta

Nome	Descrição
catalog_id	Obrigatório. Sys_id do produtor de registro configurado com a configuração do serviço de reserva de compromisso. Localizado na tabela Produtor de registro [sc_cat_item_producer]. Tipo de dados: cadeia de caracteres

Tabela 9. Parâmetros do corpo da solicitação

Nome	Descrição
Nenhum

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.

Tabela 10. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Oferece suporte somente a application/json.

Tabela 11. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir 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 da REST API.

Tabela 12. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
400	Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
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

Nome	Descrição
resultado	Resultados da solicitação de endpoint. Tipo de dados: objeto "result": { "active": Boolean, "active_string": "String", "advanced_calendar_view_portal": Boolean, "auto_acceptance": Boolean, "locale_language": "String", "service_config": {Object}, "task_table": "String", "translations": {Object}, "userDateFormatOptions": {Object}, "useRR": Boolean, "userTimeFormat": {Object}, "userTimeFormatOptions": {Object}, "view_scale": "String" }
resultado.ativo	Sinalizador que indica se a configuração de serviço para o ID do catálogo associado está ativa. Valores possíveis: verdadeiro: a configuração de serviço para o ID do catálogo está ativa. falso: a configuração de serviço para o ID do catálogo não está ativa. Tipo de dados: booliano
resultado.cadeiade_ativas	Representação de texto do status da configuração do serviço para o ID do catálogo associado. Tipo de dados: cadeia de caracteres
result.advanced_calendar_view_portal	Sinalizador que indica se a exibição de calendário avançada é exibida no portal ou exibe a exibição básica. Para obter informações adicionais sobre a exibição de calendário avançada, consulte Create or modify an appointment booking application configuration. Valores possíveis: verdadeiro: a exibição de calendário avançada é exibida no portal. falso: a exibição básica é exibida no portal. Tipo de dados: booliano
resultado.auto_aceitação	Sinalizador que indica se o compromisso faz a transição automaticamente para o estado aceito. Valores possíveis: verdadeiro: o compromisso faz a transição automaticamente para o estado aceito. falso: o agente deve aceitar o compromisso manualmente. Tipo de dados: booliano
resultado.local_idioma	Configuração de idioma do usuário. Tipo de dados: cadeia de caracteres Formato: código de idioma ISO 639.1
result.service_config	Detalhes sobre a configuração do serviço. Tipo de dados: objeto "service_config": { "active": Boolean, "active_string": "String", "appointment_booking_config": "String", "appointment_duration": "String", "appointments_per_bookable_slot": "String", "bookable_days": "String", "cancel_by_time": "String", "default_timezone": "String", "enable_advanced_config": Boolean, "field_mapping": {Object}, "future_bookable_max_days": "String", "lead_time": "String", "mandatory": "String", "use_slot_end_time_as": "String", "work_duration": "String" }
result.service_config.active	Sinalizador que indica o status ativo da configuração do serviço de reserva de compromisso. Valores possíveis: verdadeiro: ativo falso: inativo Tipo de dados: booliano
result.service_config.active_string	Representação de texto do status da configuração do serviço de reserva de compromisso. Tipo de dados: cadeia de caracteres
result.service_config.​appointment_booking_config	Sys_id da configuração do serviço de reserva de compromisso para o ID do catálogo associado. Localizado na tabela Configuração do serviço de reserva de compromisso [sn_apptmnt_booking_service_config]. Tipo de dados: cadeia de caracteres
result.service_config.​appointment_duration	Duração do compromisso. Tipo de dados: cadeia de caracteres Unidade: minutos
result.service_config.​appointments_per_bookable_slot	Número de compromissos que podem ser reservados para o slot associado. Tipo de dados: cadeia de caracteres
result.service_config.​bookable_days	Valores separados por vírgulas que representam os dias em que os compromissos podem ser reservados. Os dias são representados como números inteiros em que segunda-feira = 1 e domingo = 7. Tipo de dados: cadeia de caracteres
result.service_config.cancel_by_time	Quantidade mínima de tempo antes do início de um compromisso que um usuário pode cancelar o compromisso. Por exemplo, se você tiver um compromisso reservado para as 13h e houver um cancelamento de 2 horas por hora, cancele o compromisso até as 10h59. Formato: este valor é a diferença de data e hora de "1970-01-01 00:00:00". Portanto, se o valor retornado for "1970-01-01 04:00:00", isso significa que a sala deve ser cancelada quatro horas antes do início da reunião. Tipo de dados: cadeia de caracteres
result.service_config.default_timezone	Configuração de fuso horário em que os compromissos são reservados. Valores possíveis: local: use o fuso horário do local do compromisso. usuário: use o fuso horário da pessoa para quem o compromisso está sendo reservado. Tipo de dados: cadeia de caracteres
result.service_config.​enable_advanced_config	Sinalizador que indica se as configurações de reserva de compromisso e as regras de reserva de compromisso são consideradas ao reservar compromissos. Para obter informações adicionais, confira Create appointment booking advanced configuration. Valores possíveis: verdadeiro: as configurações de reserva de compromisso e as regras de reserva de compromisso são consideradas ao reservar compromissos. false: as configurações de reserva de compromisso e as regras de reserva de compromisso não são consideradas ao reservar compromissos. Tipo de dados: booliano
result.service_config.field_mapping	Detalhes sobre as variáveis do catálogo mapeadas para o local e valores de contato usados para reservar o compromisso. Tipo de dados: objeto "field_mapping": { "contact": "String", "contactRPVariable": {Object}, "location": "String", "locationRPVariable": {Object} }
result.service_config.​field_mapping.contact	Nome da variável do catálogo que contém o valor do contato. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​contactRPVariable	Detalhes sobre os dados das variáveis do catálogo de locais. Tipo de dados: objeto "contactRPVariable": { "displayName": "String", "label": "String", "name": "String" }
result.service_config.field_mapping.​contactRPVariable.displayName	Nome de exibição da variável do catálogo de contato. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​contactRPVariable.label	Rótulo da variável do catálogo de contato. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​contactRPVariable.name	Nome da variável do catálogo de contato. Tipo de dados: cadeia de caracteres
result.service_config.​field_mapping.location	Nome da variável do catálogo que contém o valor do local. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​locationRPVariable	Detalhes sobre os dados das variáveis do catálogo de locais. Tipo de dados: objeto "locationRPVariable": { "displayName": "String", "label": "String", "name": "String" }
result.service_config.field_mapping.​locationRPVariable.displayName	Nome de exibição da variável do catálogo de local. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​locationRPVariable.label	Rótulo da variável do catálogo de local. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​locationRPVariable.name	Nome da variável do catálogo de local. Tipo de dados: cadeia de caracteres
result.service_config.​future_bookable_max_days	Número máximo de dias no futuro em que um compromisso pode ser reservado. Tipo de dados: cadeia de caracteres
result.service_config.lead_time	Quantidade mínima de tempo antes do início de um compromisso que um usuário pode reservar o compromisso. Por exemplo, se você quiser reservar um compromisso às 13h e houver um prazo de 2 horas, será necessário reservar o compromisso até 10h59. Formato: este valor é a diferença de data e hora de "1970-01-01 00:00:00". Portanto, se o valor retornado for "1970-01-01 04:00:00", isso significa que a sala deve ser reservada quatro horas antes do início da reunião. Tipo de dados: cadeia de caracteres
result.service_config.mandatory	Indicador que indica se o compromisso é obrigatório. Valores possíveis: 0: o compromisso não é obrigatório. 1: o compromisso é obrigatório. Tipo de dados: cadeia de caracteres
result.service_config.​use_slot_end_time_as	Indicador de quando um agente chegará ou concluirá o trabalho programado para o compromisso associado. Valores possíveis: assigned_by: o agente chegará ao local do compromisso dentro do intervalo de tempo especificado. complete_by: o agente concluirá o trabalho do compromisso dentro do intervalo de tempo especificado. vazio: o mesmo que Complete_by. Tipo de dados: cadeia de caracteres
result.service_config.work_duration	Quantidade de tempo necessária para trabalhar no compromisso. A duração do trabalho é configurada na configuração do serviço de reserva de compromisso. Para obter informações adicionais, confira Create or modify an appointment booking service configuration. Tipo de dados: cadeia de caracteres Unidade: minutos
resultado.tabela_tarefa	Nome da tabela para a qual o compromisso pode ser reservado. Configurado na configuração do serviço de reserva de compromisso. Tipo de dados: cadeia de caracteres
resultado.traduções	Pares de nome-valor de traduções de texto usadas pelo widget de reserva de compromisso. Contém valores traduzidos para ações, mensagens, dias e meses. Tipo de dados: objeto
result.userDateFormatOptions	Descreve as opções de formato de data necessárias para renderizar objetos de data JS. Esses valores são definidos em constantes de reserva de compromisso que não podem ser modificadas. Tipo de dados: objeto "userDateFormatOptions": { "day": "String", "month": "String", "week": "String", "weekday": "String" }
result.userDateFormatOptions.day	Formato de data do dia. Tipo de dados: cadeia de caracteres Formato: numérico (valores ou 1-31)
result.userDateFormatOptions.month	Formato de data do mês. Tipo de dados: cadeia de caracteres Formato: Curto (valores em janeiro, fevereiro, março e assim por diante)
result.userDateFormatOptions.week	Formato de data da semana. Tipo de dados: cadeia de caracteres Formato: numérico (valores de 1 a 5)
result.userDateFormatOptions.weekday	Formato de data do dia da semana. Tipo de dados: cadeia de caracteres Formato: Curto (valores de Seg, Ter, Qua e assim por diante)
result.useRR	Valor da propriedade sn_apptmnt_booking.use_read_replica_from_ui. Este valor define se o banco de dados de réplica de leitura deve ser usado para buscar slots de compromisso quando a consulta é realizada na IU. Valores possíveis: verdadeiro: use o banco de dados de réplica de leitura para buscar os slots. falso: não use o banco de dados de réplica de leitura para buscar os slots. Tipo de dados: booliano
resultado.userTimeFormat	Descreve o formato de hora do usuário. O usuário é a pessoa que faz a solicitação de endpoint. Se feita por meio da plataforma, é um agente. Se feita por meio do portal, é um cliente. Tipo de dados: objeto "userTimeFormat": { "type": "String", "value": "String" }
resultado.userTimeFormat.type	Tipo de formato de hora. Valores possíveis: 12hr 24hr Tipo de dados: cadeia de caracteres
resultado.userTimeFormat.value	Formato de hora preferencial, como "HH:mm:ss". Tipo de dados: cadeia de caracteres
result.userTimeFormatOptions	Descreve as opções de formato de hora necessárias para renderizar objetos de hora JS. Esses valores são definidos nas constantes de reserva de compromisso que não podem ser modificadas. Tipo de dados: objeto "userTimeFormatOptions": { "hour": "String", "hourCycle": "String", "minute": "String" }
result.userTimeFormatOptions.hour	Formato para horas. Formato: numérico (valores de 1 a 12)
result.userTimeFormatOptions.hourCycle	Formato do ciclo de horas. O único valor possível é h23.
result.userTimeFormatOptions.minute	Formate para minutos. Formato: numérico (valores de 1 a 60)
resultado.view_scale	Exibir configurado na configuração do serviço. Valores possíveis: dia semana Tipo de dados: cadeia de caracteres

Solicitação de cURL

O exemplo de código a seguir mostra como chamar este endpoint.

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/configuration?catalog_id=e4c1116b3b810300ce8a4d72f3efc40f" \
--request GET \
--header "Accept:application/json" \
--user ‘username':'password'

Resposta:

{
  "result": {
    "active": true,
    "activeString": "true"
    "view_scale": "day",
    "auto_acceptance": true,
    "task_table": "wm_order",
    "advanced_calendar_view_portal": false,
    "service_config": {
      "appointment_booking_config": "deb1d2fd3b033200ce8a4d72f3efc4c2",
      "future_bookable_max_days": "14",
      "appointments_per_bookable_slot": "20",
      "bookable_days": "1,2,3,4,5",
      "active": true,
      "activeString": "true",
      "mandatory": "1",
      "lead_time": "1970-01-01 04:00:00",
      "cancel_by_time": "1970-01-01 04:00:00",
      "appointment_duration": "120",
      "default_timezone": "location",
      "work_duration": "60",
      "enable_advanced_config": true,
      "field_mapping": {
        "location": "location"
        "opened_for": "contact",
        "locationRPVariable": {
          "name": "location",
          "label": "Location",
          "displayName": "location"
        },
        "contactRPVariable": {
          "name": "contact",
          "label": "Contact",
          "displayName": "contact"
        }
      },
      "use_slot_end_time_as": ""
    },
    "translations": {
      "submit_btn_text": "Select",
      "cancel_btn_text": "Cancel",
      "calendar_prev_text": "Previous",
      "select_appointment_calendar_text": "Select Appointment Calendar",
      "calendar_next_text": "Next",
      "previous_btn_text": "Previous day",
      "next_btn_text": "Next day",
      "date_input_placeholder_text": "Pick a date",
      "show_calendar_btn_text": "Show Calendar",
      "app_window_btn_text_start_time": "Start time",
      "app_window_btn_text_end_time": "End time",
      "appointment_window_aria_label_start_text": "Available appointment window ",
      "no_appointment": "No appointments",
      "time_zone": "Time zone",
      "selected_window": "The window which has been selected is ",
      "day_names": {
        "1": "Monday",
        "2": "Tuesday",
        "3": "Wednesday",
        "4": "Thursday",
        "5": "Friday",
        "6": "Saturday",
        "7": "Sunday"
      },
      "days": [
        "Sunday",
        "Monday",
        "Tuesday",
        "Wednesday",
        "Thursday",
        "Friday",
        "Saturday"
      ],
      "daysShort": [
        "Sun",
        "Mon",
        "Tue",
        "Wed",
        "Thu",
        "Fri",
        "Sat"
      ],
      "daysMin": [
        "Su",
        "Mo",
        "Tu",
        "We",
        "Th",
        "Fr",
        "Sa"
      ],
      "months": [
        "January",
        "February",
        "March",
        "April",
        "May",
        "June",
        "July",
        "August",
        "September",
        "October",
        "November",
        "December"
      ],
      "monthsShort": [
        "Jan",
        "Feb",
        "Mar",
        "Apr",
        "May",
        "Jun",
        "Jul",
        "Aug",
        "Sep",
        "Oct",
        "Nov",
        "Dec"
      ],
      "today": "Today",
      "clear": "Clear",
      "language": "en",
      "arrive_by_msg": "The agent will arrive within the selected slot."
    },
    "useRR": true,
    "locale_language": "en",
    "userTimeFormat": {
      "value": "HH:mm:ss",
      "type": "24hr"
    },
    "userDateFormatOptions": {
      "weekday": "short",
      "year": "numeric",
      "month": "short",
      "day": "numeric"
    },
    "userTimeFormatOptions": {
      "hour": "numeric",
      "minute": "numeric",
      "hourCycle": "h23"
    }
  }
}

Compromisso - GET /sn_apptmnt_booking/appointment/execute_rule_conditions

Retorna o sys_id da regra de configuração do serviço de reserva de compromisso que corresponde a um sys_id de tarefa especificado ou a um conjunto de dados de item do catálogo especificado.

O ID da tarefa ou os dados do item do catálogo aprovados são avaliados em relação às regras definidas para uma configuração de serviço. O sys_id da primeira regra para a qual essas condições correspondem é retornado. Você deve passar este sys_id de regra para solicitações de disponibilidade subsequentes para buscar os slots corretos, que são definidos na regra.

Você deve ter a função snc_internal ou snc_external para acessar este endpoint.

Formato de URL

URL com controle de versões: /api/sn_apptmnt_booking/{api_version}/appointment/execute_rule_conditions

URL padrão: /api/sn_apptmnt_booking/appointment/execute_rule_conditions

Parâmetros de solicitação compatíveis

Tabela 13. Parâmetros de caminho

Nome	Descrição
api_version	Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres

Tabela 14. Parâmetros de consulta

Nome	Descrição
Nenhum

Tabela 15. Parâmetros do corpo da solicitação

Nome	Descrição
IdCatálogo	Obrigatório. Sys_id do produtor de registro configurado com a configuração do serviço de reserva de compromisso. Localizado na tabela Produtor de registro [sc_cat_item_producer]. Tipo de dados: cadeia de caracteres
outrasEntradas	Obrigatório se o parâmetro taskId não for especificado. Pares de nome-valor de variáveis de item do catálogo a serem comparados com as regras definidas para uma configuração de serviço. Por exemplo: "otherInputs": { "u_sn_point_of_sale_variable_set": "true", "short_description": "Point-of-Sale Installation", "contact": "6816f79cc0a8016401c5a33be04be441", "description": "Install new point-of-sale system with cash tray", "location": "32e8499cdb2d2200d75270f5bf9619d6" } Tipo de dados: objeto
taskId	Obrigatório se o parâmetro otherInputs não for especificado. Sys_id do registro de tarefa para o qual o compromisso está sendo reservado. Localizado na tabela de tarefas para a qual o compromisso está sendo reservado. O catalogId corresponde a uma configuração de reserva de compromisso específica e cada configuração tem uma tabela de tarefas na qual o compromisso é reservado. Tipo de dados: cadeia de caracteres

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.

Tabela 16. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Oferece suporte somente a application/json.
Tipo de conteúdo	Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.

Tabela 17. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir 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 da REST API.

Tabela 18. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
400	Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
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

Nome	Descrição
resultado	Descrição das informações retornadas pelo endpoint. Tipo de dados: objeto “result": { "dedicatedCapacity": Boolean, "futureMaxBookableDays": "String", "ruleId": "String", "ruleName": "String" }
result.dedicatedCapacity	Sinalizador que indica se a regra associada tem capacidade dedicada. Para obter informações adicionais sobre capacidade dedicada, consulte Create appointment booking service configuration rules. Valores possíveis: verdadeiro: a regra tem capacidade dedicada. falso: a capacidade é compartilhada entre a regra associada e a configuração de base. Também é compartilhado com outras regras que não têm capacidade dedicada. Tipo de dados: booliano
resultado.futureMaxBookableDays	Número máximo de dias no futuro para os quais um compromisso com a regra de correspondência pode ser reservado. Tipo de dados: cadeia de caracteres
result.ruleId	Sys_id da regra de configuração do serviço de reserva de compromisso que corresponde aos parâmetros taskId ou otherInputs passados na solicitação. Localizado na tabela Regra de configuração de serviço [sn_apptmnt_booking_config_rule]. Tipo de dados: cadeia de caracteres
result.ruleName	Nome da regra que correspondeu aos parâmetros passados. Tipo de dados: cadeia de caracteres

Solicitação de cURL

O exemplo de código a seguir mostra como usar o parâmetro taskId para fazer a solicitação de comparação de regra.

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/execute_rule_conditions" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"taskId\": \"ce1f397c43b861105e0dbcba6ab8f298\"}" \
--user 'username':'password'

Resposta:

{
  "result": {
    "ruleId": "f7d5d98f437c21105e0dbcba6ab8f2fc",
    "ruleName": "Priority 1 rule",
    "dedicatedCapacity": true,
    "futureMaxBookableDays": "14"
  }
}

Solicitação de cURL

O exemplo de código a seguir mostra como usar o parâmetro otherInputs para fazer a solicitação de comparação de regra.

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/execute_rule_conditions" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"otherInputs\": {
    \"u_sn_point_of_sale_variable_set\": \"true\",
    \"short_description\": \"Point-of-Sale Installation\",
    \"contact\": \"6816f79cc0a8016401c5a33be04be441\",
    \"description\": \"Install new point-of-sale system with cash tray\",
    \"location\": \"32e8499cdb2d2200d75270f5bf9619d6\"
  }
}" \
--user 'username':'password'

Resposta:

{
  "result": {
    "ruleId": " 1d1bb72b4334a1105e0dbcba6ab8f275",
    "ruleName": "Lake View SC rule",
    "dedicatedCapacity": false,
    "futureMaxBookableDays": "21"
  }
}

Compromisso - POST /sn_apptmnt_booking/appointment/appointment

Permite reservar e reagendar compromissos para uma tarefa Gestão de serviços de campo.

Nota:

Este endpoint permite apenas reservar e programar compromissos que tenham horários de início e término definidos na configuração do serviço de reserva de compromisso associado e que tenham slots disponíveis.

Para obter informações adicionais sobre Gestão de serviços de campo tarefas, consulte Configuring Appointment Booking.

Formato de URL

URL com controle de versões: /api/sn_apptmnt_booking/{api_version}/appointment/appointment

URL padrão: /api/sn_apptmnt_booking/appointment/appointment

Parâmetros de solicitação compatíveis

Tabela 19. Parâmetros de caminho

Nome	Descrição
api_version	Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres

Tabela 20. Parâmetros de consulta

Nome	Descrição
Nenhum

Tabela 21. Parâmetros do corpo da solicitação

Nome	Descrição
dataEndReal	Obrigatório. Data e hora de término do intervalo de compromisso no fuso horário do compromisso. Tipo de data: cadeia de caracteres Formato: AAAA-MM-dd HH:mm:ss
datainícioreal	Obrigatório. Data e hora de início do intervalo de compromisso no fuso horário do compromisso. Tipo de data: cadeia de caracteres Formato: AAAA-MM-dd HH:mm:ss
IdCatálogo	Obrigatório. Sys_id do produtor de registro configurado para a configuração do serviço de reserva de compromisso. O produtor de registro é definido no campo Item do catálogo no registro de configuração do serviço de reserva de compromisso relacionado - tabela Configuração do serviço de reserva de compromisso [sn_apptmnt_booking_service_config]. Tipo de data: cadeia de caracteres
endDateUTC	Obrigatório. Data e hora de término do intervalo de compromisso no fuso horário UTC. Tipo de data: cadeia de caracteres Formato: AAAA-MM-dd HH:mm:ss
local	Obrigatório. Sys_id do registro do local relacionado ao compromisso. Localizado na tabela Local [cmn_location]. Tipo de data: cadeia de caracteres
openedFor	Obrigatório. Sys_id do usuário para o qual o compromisso está sendo reservado. Localizado na tabela Usuário [sys_user]. Tipo de data: cadeia de caracteres
reprogramar	Obrigatório. Sinalizador que indica se o compromisso está sendo reagendado. Valores válidos: verdadeiro: o compromisso existe no momento e está sendo reagendado. falso: novo compromisso. Tipo de dados: booliano
regra_de_copo_serviço	Se o compromisso estiver sendo reservado de acordo com uma regra, o sys_id da regra de configuração de serviço. Localizado na tabela Regra de configuração de serviço [sn_apptmnt_booking_config_rule]. Tipo de data: cadeia de caracteres
startDateUTC	Obrigatório. Data e hora de início do intervalo de compromisso no fuso horário UTC. Tipo de data: cadeia de caracteres Formato: AAAA-MM-dd HH:mm:ss no fuso horário UTC
taskId	Obrigatório. Sys_id do registro de tarefa para o qual o compromisso está sendo reservado. A tabela que contém este sys_id é definida no parâmetro taskTable. Tipo de data: cadeia de caracteres
taskTable	Obrigatório. Nome da tabela que contém o registro de tarefa para o qual o compromisso está sendo reservado. Tipo de data: cadeia de caracteres
fuso horário	Obrigatório. Fuso horário a ser usado ao reservar ou atualizar o intervalo de compromisso especificado. Formato: formato de país/cidade ou área, como EUA/Leste Tipo de data: cadeia de caracteres

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.

Tabela 22. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Oferece suporte somente a application/json.
Tipo de conteúdo	Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.

Tabela 23. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir 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 da REST API.

Tabela 24. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
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

Nome	Descrição
resultado	Informações sobre os resultados da solicitação de endpoint. Tipo de dados: objeto "result": { "data": "String", "message": "String", "reason": "String", "success": Boolean }
resultado.dados	Sys_id do registro de compromisso que foi criado ou reprogramado. Tipo de dados: cadeia de caracteres
resultado.mensagem	Mensagem que explica se a solicitação de compromisso foi programada ou falhou. Por exemplo, as respostas de erro podem incluir: O compromisso não pode ser agendado. O compromisso não pode ser reagendado. Se a operação for bem-sucedida, uma mensagem semelhante à seguinte será retornada: Seu compromisso foi agendado com sucesso. Tipo de dados: cadeia de caracteres
resultado.motivo	Informações adicionais sobre os resultados da solicitação de compromisso. Tipo de dados: cadeia de caracteres
resultado.sucesso	Sinalizador que indica se a solicitação foi bem-sucedida. Valores possíveis: verdadeiro: solicitação bem-sucedida falso: falha na solicitação Tipo de dados: booliano

Solicitação de cURL

O exemplo a seguir mostra como criar uma nova reserva de compromisso para uma tarefa na tabela Ordem de serviço [wm_order].

curl "https://instance.servicenow.com/api/sn_apptmnt_booking/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"startDateUTC\": \"2023-02-01 20:00:00\",
\"endDateUTC\": \"2023-02-01 22:00:00\",
\"actualStartDate\": \"2023-02-01 15:00:00\",
\"actualEndDate\": \"2023-02-01 17:00:00\",
\"taskTable\": \"wm_order\",
\"location\": \"32e8499cdb2d2200d75270f5bf9619d6\",
\"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"openedFor\": \"ddce70866f9331003b3c498f5d3ee417\"
\"taskId\": \"ce1f397c43b861105e0dbcba6ab8f298\",
\"reschedule\": false,
\"service_configuration_rule\": \"\",
\"timezone\": \"US/Eastern\"
}" \

--user 'username':'password'

Resposta:

{
"result": {
  "success": true,
  "message": "Your appointment has been scheduled successfully.",
  "reason": "Appointment created!",
  "data": "7a5f393c43b861105e0dbcba6ab8f29f"
  }
}

Compromisso - POST /sn_apptmnt_booking/appointment/availability

Retorna os slots que foram configurados na configuração do serviço de reserva de compromisso junto com sua disponibilidade.

Se as configurações avançadas estiverem habilitadas para a configuração do serviço, o endpoint honrará essas configurações e retornará os dados de acordo com as regras e a configuração avançada. Você também pode usar este endpoint para encontrar o primeiro slot disponível passando o parâmetro [ get_next_available_slot ou o parâmetro get_next_available_day_data no corpo da solicitação como verdadeiro.

Você deve ter a função snc_internal ou snc_external para acessar este endpoint.

Formato de URL

URL com controle de versões: /api/sn_apptmnt_booking/{api_version}/appointment/availability

URL padrão: /api/sn_apptmnt_booking/appointment/availability

Parâmetros de solicitação compatíveis

Tabela 25. Parâmetros de caminho

Nome	Descrição
api_version	Opcional. Versão do endpoint a ser acessada. Por exemplo, v1 ou v2. Especifique este valor somente para usar uma versão de endpoint diferente da mais recente. Tipo de dados: cadeia de caracteres

Tabela 26. Parâmetros de consulta

Nome	Descrição
Nenhum

Tabela 27. Parâmetros do corpo da solicitação

Nome	Descrição
catalog_id	Obrigatório. Sys_id do produtor de registro configurado para a configuração do serviço de reserva de compromisso. O produtor de registro é definido no campo Item do catálogo no registro de configuração do serviço de reserva de compromisso relacionado - tabela Configuração do serviço de reserva de compromisso [sn_apptmnt_booking_service_config]. Tipo de data: cadeia de caracteres
end_date	Obrigatório. Data e hora de término para as quais buscar compromissos. Tipo de data: cadeia de caracteres Formato: fuso horário UTC e formato interno de data e hora AAAA-MM-dd HH:mm:ss
full_day	Obrigatório. Sinalizador que indica se todos os compromissos do intervalo de datas especificado devem ser retornados, independentemente dos valores de hora nas datas de início e término. Valores possíveis: verdadeiro: retorna todos os compromissos, independentemente dos horários especificados. falso: retorna somente compromissos que correspondem às datas e horas especificadas. Tipo de dados: booliano
get_next_available_slot	Sinalizador que indica se o primeiro bloco de compromisso disponível deve ser retornado com a resposta, mesmo que ela não faça parte dos parâmetros start_date e end_date passados. Valores possíveis: verdadeiro: retorna o primeiro intervalo de compromisso disponível. falso: não retorna o primeiro intervalo de compromisso disponível. Tipo de dados: booliano Padrão: falso
limite	Número máximo de compromissos a serem retornados. Tipo de data: número Padrão: valor especificado na propriedade retornada sn_apptmnt_booking .max_appointments_ ou 1000 se a propriedade estiver vazia.
local	Obrigatório. Sys_id do registro do local associado ao compromisso. Localizado na tabela Local [cmn_location]. Tipo de data: cadeia de caracteres
opened_for	Obrigatório. Sys_id do usuário para o qual o compromisso está sendo reservado. Localizado na tabela Usuário [sys_user]. Tipo de data: cadeia de caracteres
outrasEntradas	Pares de nome-valor de quaisquer outros valores necessários para calcular a disponibilidade no método com script. Normalmente, esses valores são variáveis de item do catálogo. No entanto, se você personalizar sua aplicação de reserva, poderá passar todos os valores necessários para sua implementação. Por exemplo: "otherInputs": { "u_sn_point_of_sale_variable_set": "true", "short_description": "Point-of-Sale Installation", "contact": "6816f79cc0a8016401c5a33be04be441", "description": "Install new point-of-sale system with cash tray", "location": "32e8499cdb2d2200d75270f5bf9619d6" } Tipo de dados: objeto
regra_config_serviço	Sys_id da regra de configuração de serviço a ser usada para calcular os slots de compromisso e a disponibilidade. Localizado na tabela Regra de configuração de serviço [sn_apptmnt_booking_config_rule]. Tipo de data: cadeia de caracteres
start_date	Obrigatório. Data e hora de início para as quais buscar compromissos. Tipo de data: cadeia de caracteres Formato: fuso horário UTC e formato interno de data e hora AAAA-MM-dd HH:mm:ss
task_table	Obrigatório. Nome da tabela que contém o registro de tarefa para o qual o compromisso está sendo reservado. Tipo de data: cadeia de caracteres
use_read_replica	Sinalizador que indica se a réplica de leitura do banco de dados deve ser usada ao buscar os slots de compromisso e sua disponibilidade. Valores válidos: verdadeiro: use a réplica de leitura do banco de dados. falso: não use a réplica de leitura do banco de dados. Padrão: falso
exibição	Obrigatório. Ponto de origem da solicitação. Valores válidos: (diferencia maiúsculas de minúsculas) plataforma portal Tipo de data: cadeia de caracteres

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.

Tabela 28. Cabeçalhos da solicitação

Cabeçalho	Descrição
Aceitar	Formato de dados do corpo da resposta. Oferece suporte somente a application/json.
Tipo de conteúdo	Formato de dados do corpo da solicitação. Oferece suporte somente a application/json.

Tabela 29. Cabeçalhos de resposta

Cabeçalho	Descrição
Nenhum

Códigos de status

Os códigos de status a seguir 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 da REST API.

Tabela 30. Códigos de status

Código de status	Descrição
200	Bem-sucedido. A solicitação foi processada com sucesso.
400	Solicitação Incorreta. Foi detectado um tipo de solicitação incorreto ou solicitação malformada.
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

Nome	Descrição
resultado	Detalhes sobre os compromissos que correspondem à solicitação. Tipo de dados: objeto "result": { "availability": [Array], "has_more": Boolean, "next_available_slot": {Object}, "no_appt_available": Boolean, "success": Boolean, "time_zone": "String", "time_zone_display_value": "String" }
resultado.disponibilidade	Lista de slots de compromisso que atendem à solicitação especificada. Tipo de dados: objeto "availability": { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" }
resultado.disponibilidade.disponível	Sinalizador que indica se o intervalo de tempo associado está disponível. Valores possíveis: verdadeiro: o intervalo de tempo está disponível. falso: o intervalo de tempo não está disponível. Tipo de dados: booliano
result.availability.end_date	Data e hora de término do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
result.availability.end_date_display	Exibir data e hora de término do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone_display_value. Tipo de dados: cadeia de caracteres Formato: formato de data e hora do usuário solicitante.
result.availability.end_dateUTC	Data e hora de término do compromisso associado no horário UTC. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
resultado.disponibilidade.data_início	Data e hora de início do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
result.availability.start_date_display	Exiba a data e a hora de início do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone_display_value. Tipo de dados: cadeia de caracteres Formato: formato de data e hora do usuário solicitante.
result.availability.start_dateUTC	Data e hora de início do compromisso associado no horário UTC. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
resultado.tem_mais	Sinalizador que indica se há mais slots de compromisso para buscar após retornar o limite. Valores possíveis: verdadeiro: há mais slots de compromisso disponíveis. falso: não há mais slots disponíveis. Tipo de dados: booliano
resultado.próximo_vaga_disponível	Se o parâmetro get_next_available_slot foi passado como verdadeiro, detalhes sobre o primeiro slot disponível, independentemente das datas de início e término passadas. Tipo de dados: objeto "next_available_slot": { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" }
resultado.próximo_vaga_disponível.disponível	Sinalizador que indica se o intervalo de tempo associado está disponível. Valores possíveis: verdadeiro: o intervalo de tempo está disponível. falso: o intervalo de tempo não está disponível. Tipo de dados: booliano
resultado.próximo_vaga_disponível.data_término	Data e hora de término do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
result.next_available_slot.end_date_display	Exibir data e hora de término do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone_display_value. Tipo de dados: cadeia de caracteres Formato:
result.next_available_slot.end_dateUTC	Data e hora de término do compromisso associado no horário UTC. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
resultado.próximo_vaga_disponível.data_início	Data e hora de início do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
result.next_available_slot.start_date_display	Exiba a data e a hora de início do compromisso associado. O fuso horário é baseado no valor do parâmetro time_zone_display_value. Tipo de dados: cadeia de caracteres Formato:
result.next_available_slot.start_dateUTC	Data e hora de início do compromisso associado no horário UTC. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
resultado.sem_app_disponível	Sinalizador que indica se há mais slots de compromisso disponíveis para a data e hora especificadas. Valores possíveis: verdadeiro: há mais intervalos de tempo de compromisso disponíveis. falso: não há mais intervalos de tempo de compromisso disponíveis. Tipo de dados: booliano
resultado.sucesso	Sinalizador que indica se a chamada do endpoint foi bem-sucedida. Valores possíveis: verdadeiro: a chamada do endpoint foi bem-sucedida. falso: falha na chamada do endpoint. Tipo de dados: booliano
result.time_zone	Fuso horário no qual os slots de compromisso foram renderizados. Com base nos valores na configuração do serviço de reserva de compromisso. Tipo de dados: cadeia de caracteres
result.time_zone_display_value	Exiba o fuso horário no qual os intervalos de compromisso foram renderizados. Com base nos valores na configuração do serviço de reserva de compromisso. Tipo de dados: cadeia de caracteres

Solicitação de cURL

O exemplo de código a seguir mostra como chamar este endpoint.

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/availability" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"start_date\": \"2023-02-05 05:00:00\",
  \"end_date\": \"2023-02-07 04:59:59\",
  \"location\": \"32e8499cdb2d2200d75270f5bf9619d6\",
  \"catalog_id\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"opened_for\": \"6816f79cc0a8016401c5a33be04be441\",
  \"full_day\": false,
  \"task_table\": \"wm_order\",
  \"view\": \"portal\",
  \"get_next_available_slot\": true,
  \"use_read_replica\": true,
  \"service_config_rule\": \"f7d5d98f437c21105e0dbcba6ab8f2fc\"
}" \
--user 'username':'password

Resposta:

{
"result": {
  "success": true,
  "availability": [
    {
      "start_date": "2023-02-06 09:00:00",
      "end_date": "2023-02-06 11:00:00",
      "start_date_display": "09:00",
      "end_date_display": "11:00",
      "start_dateUTC": "2023-02-06 14:00:00",
      "end_dateUTC": "2023-02-06 16:00:00",
      "available": false
    },
    {
      "start_date": "2023-02-06 13:00:00",
      "end_date": "2023-02-06 15:00:00",
      "start_date_display": "13:00",
      "end_date_display": "15:00",
      "start_dateUTC": "2023-02-06 18:00:00",
      "end_dateUTC": "2023-02-06 20:00:00",
      "available": false
    },
    {
      "start_date": "2023-02-06 15:00:00",
      "end_date": "2023-02-06 17:00:00",
      "start_date_display": "15:00",
      "end_date_display": "17:00",
      "start_dateUTC": "2023-02-06 20:00:00",
      "end_dateUTC": "2023-02-06 22:00:00",
      "available": false
    }
  ],
  "has_more": false,
  "no_appt_available": true,
  "time_zone": "US/Eastern",
  "time_zone_display_value": "US/Eastern",
  "next_available_slot": {
    "start_date": "2023-02-10 13:00:00",
    "end_date": "2023-02-10 15:00:00",
    "start_date_display": "13:00",
    "end_date_display": "15:00",
    "start_dateUTC": "2023-02-10 18:00:00",
    "end_dateUTC": "2023-02-10 20:00:00",
    "available": true
}