Appointment Open API
A Appointment Open API é uma API de telecomunicação que permite que você interaja com o aplicativo de agendamentos. Use esta API para reservar compromissos e pesquisar intervalos de tempo disponíveis.
A Appointment Open API é uma ServiceNow® implementação da especificação da API REST de compromisso do Open API TMForum TMF646 e tem conformidade certificada pelo TM Fórum. Esta implementação se baseia na especificação REST da API de compromisso TMF646 R16.0.1.
- Agendamentos (com.snc.appointment_booking)
- Gestão de serviços de campo (com.snc.work_management)
- Gestão de serviços de campo para telecomunicações (com.sn_fsmt)
- APIs abertas de telecomunicação (com.sn_tmf_api)
Antes de usar esta API, a configuração de Agendamentos e a configuração de serviço devem ser definidas. Além disso, deve existir uma tarefa para a qual o compromisso está sendo reservado.
Esta API é fornecida no namespace sn_tmf_api. O usuário de chamada deve ter a função sn_tmf_api.appointment_integrator.
Compromisso em aberto - GET /api/sn_tmf_api/appointment/searchTimeSlot
Retorna intervalos de tempo que foram configurados na configuração do serviço de agendamentos junto com sua disponibilidade.
Formato da URL
/api/sn_tmf_api/appointment/searchTimeSlot
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| Nenhum(a) |
| Nome | Descrição |
|---|---|
| catalog_id | Obrigatório. Sys_id do produtor de registro configurado com uma configuração de serviço de agendamentos. Tipo de dados: cadeia de caracteres Tabela: produtor de registro [sc_cat_item_producer] |
| end_date | Obrigatório. Data e hora de término do período de tempo em que você deseja pesquisar o compromisso. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, |
| local | Sys_id do local do compromisso. Tabela: local [cmn_location] Tipo de dados: cadeia de caracteres Padrão: retorna todos os locais se não for especificado. |
| aberto_para | Obrigatório. Sys_id do usuário para o qual o compromisso está sendo reservado. Tabela: Contato [customer_contact] Tipo de dados: cadeia de caracteres |
| start_date | Obrigatório. Data e hora de início do período em que você deseja pesquisar o compromisso. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, |
| Nome | Descrição |
|---|---|
| Nenhum(a) |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Oferece suporte somente a application/json. |
| Cabeçalho | Descrição |
|---|---|
| Nenhum(a) |
Códigos de status
Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.
| Código do 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 |
|---|---|
| availableTimeSlot | Lista de slots de compromisso dentro do bloco especificado de tempo solicitado. Tipo de dados: matriz de objetos |
| disponívelTempoDeTempo.disponível | Sinalizador que indica se o intervalo de tempo associado está disponível. Valores possíveis:
Tipo de dados: booliano |
| availableTimeSlot.end_date | Data e hora de término do compromisso associado. O fuso horário é baseado no valor no parâmetro timeZone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| availableTimeSlot.end_date_display | Exibir data e hora de término do compromisso associado. O fuso horário é baseado no valor no parâmetro timeZone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| availableTimeSlot.end_dateUTC | Data e hora de término do compromisso associado. Tipo de dados: cadeia de caracteres Formato: UTC |
| disponívelTimeSlot.data_início | Data e hora de início do compromisso associado. Reflete o valor do parâmetro timeZone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| availableTimeSlot.start_date_display | Exibir data e hora de início do compromisso associado. Reflete o valor do parâmetro timeZone. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| disponívelTimeSlot.start_dateUTC | Data e hora de início do compromisso associado. Tipo de dados: cadeia de caracteres Formato: UTC |
| hasMore | Sinalizador que indica se há mais slots de compromisso a serem buscados após o retorno do limite. O limite é especificado na propriedade de Agendamentos, sn_apptmnt_booking.max_appointments_returned (Padrão: 100). Consulte Appointment booking components para obter mais detalhes sobre esta propriedade. Valores possíveis:
Tipo de dados: booliano |
| noApptDisponível | Sinalizador que indica se há mais slots de compromisso disponíveis para a data e hora especificadas. Valores válidos:
Tipo de dados: booliano |
| resultado da pesquisa | Resultados de disponibilidade de compromisso dentro do intervalo de tempo de pesquisa designado. Valores possíveis:
Tipo de dados: cadeia de caracteres |
| status | Status de conclusão da pesquisa de intervalos de tempo disponíveis. Por exemplo, concluído. Tipo de dados: cadeia de caracteres |
| fuso horário | Fuso horário usado ao reservar ou atualizar o período de agendamento especificado. Tipo de data: cadeia de caracteres Formato: formato de país/cidade ou área, como EUA/Leste |
Solicitação de cURL
O exemplo de código a seguir mostra como chamar este endpoint.
curl --location --request GET 'https://instance.service-now.com/api/sn_tmf_api/appointment/searchTimeSlot?
start_date=2024-07-10 09:00:00&end_date=2024-07-20 23:00:00&catalog_id=ada50a93f0220210f8776517d8c8e776&
opened_for=51670151c35420105252716b7d40ddfe&location=f48b21850a0a0ba7004182b18099696d ' \
--user 'username':'password'Resultado:
{
"searchResult": "success",
"status": "done",
"availableTimeSlot": [
{
"start_date": "2024-07-10 09:00:00",
"end_date": "2024-07-10 12:00:00",
"start_date_display": "09:00",
"end_date_display": "12:00",
"start_dateUTC": "2024-07-10 16:00:00",
"end_dateUTC": "2024-07-10 19:00:00",
"available": false
},
{
"start_date": "2024-07-11 13:00:00",
"end_date": "2024-07-11 16:00:00",
"start_date_display": "13:00",
"end_date_display": "16:00",
"start_dateUTC": "2024-07-11 20:00:00",
"end_dateUTC": "2024-07-11 23:00:00",
"available": true
},
{
"start_date": "2024-07-12 09:00:00",
"end_date": "2024-07-12 12:00:00",
"start_date_display": "09:00",
"end_date_display": "12:00",
"start_dateUTC": "2024-07-12 16:00:00",
"end_dateUTC": "2024-07-12 19:00:00",
"available": true
},
{
"start_date": "2024-07-12 13:00:00",
"end_date": "2024-07-12 16:00:00",
"start_date_display": "13:00",
"end_date_display": "16:00",
"start_dateUTC": "2024-07-12 20:00:00",
"end_dateUTC": "2024-07-12 23:00:00",
"available": true
},
{
"start_date": "2024-07-19 13:00:00",
"end_date": "2024-07-19 16:00:00",
"start_date_display": "13:00",
"end_date_display": "16:00",
"start_dateUTC": "2024-07-19 20:00:00",
"end_dateUTC": "2024-07-19 23:00:00",
"available": true
}
],
"hasMore": false,
"noApptAvailable": false,
"timeZone": "US/Arizona"
}Compromisso em aberto - POST /api/sn_tmf_api/appointment/appointment
Permite que você marque compromissos para uma ordem de serviço.
Formato da URL
/api/sn_tmf_api/appointment/appointment
Parâmetros de solicitação compatíveis
| Nome | Descrição |
|---|---|
| Nenhum(a) |
| Nome | Descrição |
|---|---|
| Nenhum(a) |
| Nome | Descrição |
|---|---|
| categoria | Obrigatório. Sys_id do produtor de registro configurado para a configuração do serviço de agendamentos. Tipo de dados: cadeia de caracteres Tabela: no campo Item do catálogo da tabela Configuração do serviço de agendamentos [sn_apptmnt_booking_service_config]. |
| relatedEntity | Obrigatório. Lista de ordens de serviço afetadas a serem associadas ao compromisso. Tipo de dados: matriz de objetos |
| relatedEntity.@referredType | Obrigatório. Tipo de item ou serviço. Somente valor válido: WorkOrder Tipo de dados: cadeia de caracteres Tabela: ordem de serviço [wm_order] |
| relatedEntity.id | Obrigatório. Sys_id da entidade relacionada. Tipo de dados: cadeia de caracteres Tabela: workOrder [wm_order] Padrão: retorna tudo se o sys_id não for fornecido. |
| relatedEntity.role | Obrigatório. Descrição da função da entidade relacionada. Somente valor válido: ordem de serviço Tipo de dados: cadeia de caracteres Tabela: ordem de serviço [wm_order] |
| relatedParty | Obrigatório. Lista de contatos do compromisso. Cada contato é um objeto na matriz. A solicitação deve listar pelo menos um item que contenha informações da conta do cliente. Tipo de dados: matriz de objetos |
| relatedParty.@referredType | Tipo de cliente. Somente valor válido: Individual Tipo de dados: cadeia de caracteres |
| relatedParty.id | Obrigatório. Sys_id ou external_id do contato associado à ordem de serviço. Tipo de dados: cadeia de caracteres Tabela: Contato [customer_contact] |
| relatedParty.name | Nome do contato. Tipo de dados: cadeia de caracteres Tabela: Contato [customer_contact] |
| relatedParty.role | Obrigatório. Função do contato. Valores possíveis:
Tipo de dados: cadeia de caracteres Tabela: Contato [customer_contact] |
| relatedPplace | Obrigatório. Lista dos locais relacionados ao compromisso. Tipo de dados: matriz de objetos |
| relatedPlace.@referredType | Obrigatório. Tipo de local. Por exemplo, Cidade. Tipo de dados: cadeia de caracteres Tabela: Locais [cmn_location] |
| relatedPlace.id | Obrigatório. Sys_id do local relacionado. Tipo de dados: cadeia de caracteres Tabela: Locais [cmn_location] |
| relatedPlace.name | Nome do local relacionado ao contato. Por exemplo, 251 Reddy St, darwin, CA 93522. Tipo de dados: cadeia de caracteres Tabela: Locais [cmn_location] |
| relatedPlace.role | Obrigatório. Descrição da função do local. Por exemplo, ordem de serviço. Tipo de dados: cadeia de caracteres |
| fuso horário | Obrigatório. Fuso horário a ser usado ao reservar o período de compromisso especificado. Tipo de data: cadeia de caracteres Formato: formato de país/cidade ou área, como EUA/Leste |
| validFor | Obrigatório. Intervalo de datas para o qual o compromisso é válido. Tipo de dados: objeto |
| validFor.endDateTime | Obrigatório. Data e hora de término do intervalo de tempo. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| validFor.startDateTime | Obrigatório. Data e hora de início do intervalo de tempo. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
Cabeçalhos
Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.
| Cabeçalho | Descrição |
|---|---|
| Aceitar | Formato de dados do corpo da resposta. Oferece suporte somente a application/json. |
| Cabeçalho | Descrição |
|---|---|
| Tipo de conteúdo | Formato de dados do corpo da solicitação. Oferece suporte somente a application/json. |
Códigos de status
Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP de REST API.
| Código do 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 |
|---|---|
| categoria | Sys_id do produtor de registro configurado para a configuração do serviço de agendamentos. Tipo de dados: cadeia de caracteres Armazenado em: campo Item do catálogo da tabela Configuração do serviço de agendamentos [sn_apptmnt_booking_service_config]. |
| creationDate | Data e hora em que o compromisso foi criado. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| href | Hiperlink para o registro de compromisso. Use este link em outra solicitação de API de abertura de compromisso para reprogramar ou excluir o compromisso. Tipo de dados: cadeia de caracteres |
| id | Sys_id do compromisso. Tipo de dados: cadeia de caracteres Armazenado em: tabela Configuração do serviço de agendamentos [sn_apptmnt_booking_service_config] |
| últimaAtualização | Data e hora em que o compromisso foi atualizado pela última vez. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| relatedEntity | Detalhes sobre a entidade relacionada do compromisso. Tipo de dados: matriz de objetos |
| relatedEntity.@referredType | Tipo de item ou serviço. Tipo de dados: cadeia de caracteres Armazenado em: tabela workOrder [wm_order] |
| relatedEntity.id | Sys_id da entidade relacionada. Tipo de dados: cadeia de caracteres Armazenado em: tabela workOrder [wm_order] |
| relatedEntity.role | Descrição da função da entidade relacionada. Valor possível: ordem de serviço Tipo de dados: cadeia de caracteres Armazenado em: tabela workOrder [wm_order] |
| relatedParty | Lista de contatos do compromisso. Cada contato é um objeto na matriz. Tipo de dados: matriz de objetos |
| relatedParty.@referredType | Tipo de cliente. Tipo de dados: cadeia de caracteres Armazenado em: tabela Contato [customer_contact] |
| relatedParty.id | Sys_id do contato do cliente associado à ordem de serviço. Tipo de dados: cadeia de caracteres Armazenado em: tabela Contato [customer_contact] |
| relatedParty.name | Nome do contato do cliente. Tipo de dados: cadeia de caracteres Armazenado em: tabela Contato [customer_contact] |
| relatedParty.role | Função do contato do cliente. Valores possíveis:
Tipo de dados: cadeia de caracteres Armazenado em: tabela Contato [customer_contact] |
| relatedPplace | Detalhes do local do compromisso associado. Tipo de dados: objeto |
| relatedPlace.@referredType | Endereço geográfico do compromisso. Valor possível: GeographicLocation. Tipo de dados: cadeia de caracteres Armazenado em: tabela Local [cmn_location] |
| relatedPlace.id | Sys_id do local. Tipo de dados: cadeia de caracteres Armazenado em: tabela Local [cmn_location] |
| relatedPlace.name | Nome do local relacionado ao contato. Por exemplo, 100SouthCharlesStreet,Baltimore,MD. Tipo de dados: cadeia de caracteres Armazenado em: tabela Local [cmn_location] |
| relatedPlace.role | Função do local do compromisso como um endereço de intervenção. Valor possível: InterventionAddress Tipo de dados: cadeia de caracteres Armazenado em: tabela Local [cmn_location] |
| êxito | Sinalizador que indica se a solicitação foi bem-sucedida. Valores possíveis:
Tipo de dados: booliano |
| fuso horário | Fuso horário usado ao reservar ou atualizar o período de agendamento especificado. Tipo de data: cadeia de caracteres Formato: formato de país/cidade ou área, como EUA/Leste |
| validFor | Intervalo de datas para o qual o compromisso é válido. Tipo de dados: objeto |
| validFor.endDateTime | Data e hora de término do compromisso. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
| validFor.startDateTime | Data e hora de início do compromisso. Tipo de dados: cadeia de caracteres Formato: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43. |
Solicitação de cURL
O exemplo a seguir mostra como criar um novo agendamento.
curl "https://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"validFor\": {
\"startDateTime\": \"2024-08-19 09:00:00\",
\"endDateTime\": \"2024-08-19 11:00:00\"
},
\"category\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"relatedParty\": [
{
\"id\": \"eaf68911c35420105252716b7d40ddde\",
\"name\": \"Sally Thomas\",
\"role\": \"customer\",
\"@referredType\": \"Individual\"
}
],
\"relatedPlace\": {
\"id\": \"25ab9c4d0a0a0bb300f7dabdc0ca7c1c\",
\"name\": \"100 South Charles Street, Baltimore,MD\",
\"role\": \"interventionAddress\",
\"@referredType\": \"GeographicAddress\"
},
\"relatedEntity\": [
{
\"id\": \"48dbfbf9201f0250f877303e8a020dcd\",
\"role\": \"work order\",
\"@referredType\": \"WorkOrder\"
}
],
\"timeZone\": \"US/Arizona\"
}" \
--user 'username':'password'Resposta:
{
"validFor": {
"startDateTime": "2024-07-19 09:00:00",
"endDateTime": "2024-07-19 11:00:00"
},
"category": "e4c1116b3b810300ce8a4d72f3efc40f",
"relatedParty": [
{
"id": "eaf68911c35420105252716b7d40ddde",
"name": "Sally Thomas",
"role": "customer",
"@referredType": "Individual"
}
],
"relatedPlace": {
"id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
"name": "100 South Charles Street, Baltimore,MD",
"role": "interventionAddress",
"@referredType": "GeographicAddress"
},
"relatedEntity": [
{
"id": "48dbfbf9201f0250f877303e8a020dcd",
"role": "work order",
"@referredType": "WorkOrder"
}
],
"timeZone": "US/Arizona",
"success": true,
"id": "feacb7f9201f0250f877303e8a020d38",
"href": "api/sn_tmf_api/appointment/appointment/feacb7f9201f0250f877303e8a020d38",
"creationDate": "2024-07-10 22:45:01",
"lastUpdate": "2024-07-10 22:45:01"
}