API de compromisso

A Appointment API fornece endpoints para interagir com o aplicativo de reserva de compromisso. Use esta API para reservar e reprogramar compromissos, verificar slots de compromisso disponíveis e buscar detalhes de configuração de reserva de compromisso.

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

A Appointment API requer o plug-in de Agendamentos (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 prazo e o máximo de datas futuras reserváveis configuradas na configuração do serviço de agendamentos.

Para obter informações adicionais sobre o tempo de lead e a configuração de datas máximas reserváveis no futuro, 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 da URL

URL com controle de versão: /api/sn_apptmnt_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. Somente especifique este valor 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 agendamentos. 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
aberto_para	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(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.

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

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.range_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 de data e hora interno.
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 de data e hora interno.

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 do serviço de agendamentos 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 agendamentos.

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

Formato da URL

URL com controle de versão: /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. Somente especifique este valor 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 agendamentos. 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(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.

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

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 de 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.string_ativa	Representação de texto do status da configuração de serviço para o ID de 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 base. Para obter informações adicionais sobre a exibição avançada de calendário, 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 manualmente o compromisso. Tipo de dados: booliano
resultado.locale_idioma	Configuração de idioma do usuário. Tipo de dados: cadeia de caracteres Formato: código de idioma ISO 639.1
resultado.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 agendamentos. Valores possíveis: verdadeiro: ativo falso: inativo Tipo de dados: booliano
resultado.service_config.active_string	Representação de texto do status da configuração do serviço de agendamentos. Tipo de dados: cadeia de caracteres
result.service_config.​appointment_booking_config	Sys_id da configuração do serviço de agendamentos para o ID do catálogo associado. Localizado na tabela Configuração do serviço de agendamentos [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 em 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, você deverá cancelar 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 do 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 agendamentos e as regras de agendamentos são consideradas ao agendar compromissos. falso: as configurações de agendamentos e as regras de agendamentos não são consideradas ao agendar 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 de 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 contatos. 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 locais. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​locationRPVariable.label	Rótulo da variável do catálogo de locais. Tipo de dados: cadeia de caracteres
result.service_config.field_mapping.​locationRPVariable.name	Nome da variável do catálogo de locais. 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é 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 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: Compromisso é obrigatório. Tipo de dados: cadeia de caracteres
result.service_config.​use_slot_end_time_as	Indicador que indica quando um agente chegará ou concluirá o trabalho programado para o compromisso associado. Valores possíveis: chegar_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 Completed_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 é definida na configuração do serviço de agendamentos. Para obter informações adicionais, confira Create or modify an appointment booking service configuration. Tipo de dados: cadeia de caracteres Unidade: minutos
resultado.tarefa_tabela	Nome da tabela para a qual o compromisso pode ser reservado. Configurado na configuração do serviço de agendamentos. Tipo de dados: cadeia de caracteres
result.translations	Pares de nome-valor de traduções de texto usados pelo widget de agendamentos. 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 são modificáveis. 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)
resultado.usarRR	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 for feita por meio da plataforma, será um agente. Se for feito por meio do portal, será 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	Formate por 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.exibição_escala	Exibição configurada 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 agendamentos que corresponde a um sys_id de tarefa especificado ou a um conjunto de dados de item do catálogo especificados.

O ID de tarefa aprovado ou os dados do item do catálogo 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 da URL

URL com controle de versão: /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. Somente especifique este valor 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(a)

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

Nome	Descrição
catalogId	Obrigatório. Sys_id do produtor de registro configurado com a configuração do serviço de agendamentos. 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(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.

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" }
resultado.capacidadededicada	Sinalizador que indica se a regra associada tem capacidade dedicada. Para obter informações adicionais sobre a 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 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 correspondente pode ser reservado. Tipo de dados: cadeia de caracteres
resultado.ruleId	Sys_id da regra de configuração do serviço de agendamentos 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 regras.

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

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 que você reserve e reagende compromissos para uma tarefa Gestão de serviços de campo.

Nota:

Este endpoint só permite reservar e programar compromissos com horários de início e término definidos na configuração do serviço de agendamentos 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 da URL

URL com controle de versão: /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. Somente especifique este valor 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(a)

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

Nome	Descrição
actualEndDate	Obrigatório. Data e hora de término do período de compromisso no fuso horário do compromisso. Tipo de data: cadeia de caracteres Formato: AAAA-MM-dd HH:mm:ss
actualInícioDate	Obrigatório. Data e hora de início do período de compromisso no fuso horário do compromisso. Tipo de data: cadeia de caracteres Formato: AAAA-MM-dd HH:mm:ss
catalogId	Obrigatório. Sys_id do produtor de registro configurado para a configuração do serviço de agendamentos. O produtor de registro é definido no campo Item do catálogo no registro de configuração do serviço de agendamentos relacionado - tabela Configuração do serviço de agendamentos [sn_apptmnt_booking_service_config]. Tipo de data: cadeia de caracteres
endDateUTC	Obrigatório. Data e hora de término do período 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 de local relacionado ao compromisso. Localizado na tabela Local [cmn_location]. Tipo de data: cadeia de caracteres
abertoPara	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 remarcado. Valores válidos: verdadeiro: o compromisso existe no momento e está sendo remarcado. falso: novo compromisso. Tipo de dados: booliano
regra_cof_de_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 período 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 período 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(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.

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 um novo agendamento 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 agendamentos junto com sua disponibilidade.

Se as configurações avançadas estiverem habilitadas para a configuração de 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 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 da URL

URL com controle de versão: /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. Somente especifique este valor 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(a)

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 agendamentos. O produtor de registro é definido no campo Item do catálogo no registro de configuração do serviço de agendamentos relacionado - tabela Configuração do serviço de agendamentos [sn_apptmnt_booking_service_config]. Tipo de dados: cadeia de caracteres
end_date	Obrigatório. Data e hora de término para buscar compromissos. Tipo de dados: cadeia de caracteres Formato: fuso horário UTC e no 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 na data de início e de 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 slot de compromisso disponível deve ser retornado com a resposta, mesmo que não faça parte dos parâmetros start_date e end_date passados. Valores possíveis: verdadeiro: retorna o primeiro slot de compromisso disponível. falso: não retorna o primeiro slot de compromisso disponível. Tipo de dados: booliano Padrão: falso
limite	Número máximo de compromissos a serem retornados. Tipo de dados: 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 de local associado ao compromisso. Localizado na tabela Local [cmn_location]. Tipo de dados: cadeia de caracteres
aberto_para	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
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 reservas, 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_de_configuração_de_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 dados: cadeia de caracteres
start_date	Obrigatório. Data e hora de início para buscar compromissos. Tipo de dados: cadeia de caracteres Formato: fuso horário UTC e no 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 dados: 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 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 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(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.

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 no 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 no 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 no parâmetro time_zone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
result.availability.start_date_display	Exibir data e hora de início do compromisso associado. O fuso horário é baseado no valor no parâmetro time_zone_display_value. Tipo de dados: cadeia de caracteres Formato: formato de data e hora do usuário solicitante.
resultado.disponibilidade.data_inícioUTC	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 a serem buscados após o retorno do 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.next_available_slot	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 aprovadas. 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_disponível_slot.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.next_available_slot.end_date	Data e hora de término do compromisso associado. O fuso horário é baseado no valor no 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 no 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
result.next_available_slot.start_date	Data e hora de início do compromisso associado. O fuso horário é baseado no valor no parâmetro time_zone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD hh:mm:ss
result.next_available_slot.start_date_display	Exibir data e hora de início do compromisso associado. O fuso horário é baseado no valor no 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 slots de tempo de compromisso disponíveis. falso: não há mais slots 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
resultado.time_zone	Fuso horário no qual os slots de compromisso foram renderizados. Com base nos valores na configuração do serviço de agendamentos. Tipo de dados: cadeia de caracteres
resultado.time_zone_display_value	Exibir o fuso horário no qual os slots de compromisso foram renderizados. Com base nos valores na configuração do serviço de agendamentos. 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
}