API de consulta em aberto

  • Versão de lançamento: Australia
  • Atualizado 12 de mar. de 2026
  • 11 min. de leitura

    • . Compromisso em aberto A API é uma API de telecomunicações que permite interagir com a aplicação de agendamento de compromissos. Use esta API para agendar compromissos e pesquisar intervalos de tempo disponíveis.

    . Compromisso em aberto A API é um ServiceNow® A implementação da API aberta TMForum TMF646 API REST e é certificada em conformidade pelo TM Forum. Esta implementação é baseada em Especificação REST da API de compromisso TMF646 R16.0.1 .

    Logotipo de conformidade da TMF
    Esta API requer os seguintes plug-ins disponíveis no ServiceNow Store.
    • Agendamento de compromisso (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)
    • Telecomunicações em aberto APIs (com.sn_tmf_api)

    Antes de usar esta API, a configuração de agendamento de compromissos e a configuração de serviço devem ser definidas. Além disso, deve existir uma tarefa para a qual o compromisso está sendo agendado.

    Esta API é fornecida no sn_tmf_api namespace. O usuário solicitante deve ter a função sn_tmf_api.appointment_integrator.

    Compromisso aberto - OBTER /api/sn_tmf_api/appointment/searchTimeSlot

    Retorna intervalos de tempo que foram configurados na configuração do serviço de agendamento de compromissos junto com sua disponibilidade.

    Formato de URL

    /api/sn_tmf_api/appointment/searchTimeSlot

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    Nenhum(a)
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    catalog_id Necessário. Sys_id do produtor de registro configurado com uma configuração de serviço de agendamento de compromissos.

    Tipo de dados: Cadeia de caracteres

    Tabela: Produtor de registro [sc_cat_item_producer]
    end_date Necessário. Data e hora de término 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, 2025-01-31 12:00:00 .
    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 forem especificados.
    aberto_para Necessá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 Necessá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, 2025-01-31 09:00:00 .
    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 da 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 possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    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. Um tipo de solicitação incorreto ou uma solicitação malformada foi detectada.
    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
    TimeSlot disponível Lista de intervalos de compromisso no bloco especificado de tempo solicitado.

    Tipo de dados: Matriz de objetos

    'availableTimeSlot': [
 { 
  "available": Boolean,
  "end_date": "String",
  "end_date_display": "String",
  "end_dateUTC": "String",
  "start_date": "String",
  "start_date_display": "String",
  "start_dateUTC": "String"
 }
]
    AvailableTimeSlot.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
    AvailableTimeSlot.end_date Data e hora de término do compromisso associado. O fuso horário é baseado no valor no timeZoneparâmetro.

    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 timeZoneparâmetro.

    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
    TimeSlot.start_date Data e hora de início do compromisso associado. Reflete o valor de timeZoneparâmetro.

    Tipo de dados: Cadeia de caracteres

    FORMATO: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43.
    TimeSlot.start_date_display Exibir data e hora de início do compromisso associado. Reflete o valor de timeZoneparâmetro.

    Tipo de dados: Cadeia de caracteres

    FORMATO: AAAA-MM-DD 00:00:00. Por exemplo, 2025-01-31 09:35:43.
    AvailableTimeSlot.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 para buscar após retornar o limite. O limite é especificado na propriedade Agendamento de compromisso, sn_apptmnt_booking.max_appointments_returned (padrão: 100). Consulte Appointment booking components para obter mais detalhes sobre esta propriedade.
    Valores possíveis:
    • Verdadeiro: É possível buscar mais slots de compromisso.
    • Falso: Não há mais slots de compromisso disponíveis.

    Tipo de dados: Booliano
    NoApptDisponível Sinalizador que indica se há mais intervalos de compromisso disponíveis para a data e hora especificadas.
    Valores válidos:
    • Verdadeiro: Há mais slots de compromisso disponíveis para a data e hora especificadas.
    • Falso: Não há mais slots de compromisso disponíveis para a data e hora especificadas.

    Tipo de dados: Booliano
    Result de pesquisa Resultados da disponibilidade de compromisso dentro do intervalo de tempo de pesquisa designado.
    Valores possíveis:
    • êxito
    • falha

    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 intervalo de compromisso 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 aberto - PUBLICAR /api/sn_tmf_api/appointment/appointment

    Permite agendar compromissos para uma ordem de serviço.

    Formato de URL

    /api/sn_tmf_api/appointment/appointment

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    Nenhum(a)
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Parâmetros do corpo da solicitação
    Nome Descrição
    categoria Necessário. Sys_id do produtor de registro configurado para a configuração do serviço de agendamento de compromissos.

    Tipo de dados: Cadeia de caracteres

    Tabela: No campo Item do catálogo da tabela Configuração do serviço de agendamento de compromissos [sn_apptmnt_booking_service_config].
    EntidadeRelacionada Necessário. Lista de ordens de serviço afetadas a serem associadas ao compromisso.

    Tipo de dados: Matriz de objetos

    "relatedEntity": [
  {
    "@referredType": "String"
    "id": "String",
  }
]
    RelatedEntity. Em referredType Necessário. Tipo de item ou serviço.

    Somente valor válido: Ordem de serviço

    Tipo de dados: Cadeia de caracteres

    Tabela: Ordem de serviço [wm_order]
    relatedEntity.id Necessário. Sys_id da entidade relacionada.

    Tipo de dados: Cadeia de caracteres

    Tabela: Ordem de serviço [wm_order]

    Padrão: Retorna tudo se o sys_id não for fornecido.
    RelatedEntity.Role Necessá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 Necessário. Lista de contatos do compromisso. Cada contato é um objeto na matriz. A solicitação deve listar pelo menos um item que contém informações da conta do cliente.

    Tipo de dados: Matriz de objetos

    "relatedParty": [ 
 {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
 }
]
    RelatedParty. Em referredType Tipo de cliente.

    Somente valor válido: Individual

    Tipo de dados: Cadeia de caracteres
    IdentidadeRelatedParty.id Necessá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 Necessário. Função do contato.
    Valores possíveis:
    • Cliente: O contato tem uma função de cliente.
    • Técnico: O contato tem uma função de técnico.

    Tipo de dados: Cadeia de caracteres

    Tabela: Contato [customer_contact]
    RelatedPlace Necessário. Lista de locais relacionados ao compromisso.

    Tipo de dados: Matriz de objetos

    "relatedPlace": [
 {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
 }
]
    RelatedPlace. Em referredType Necessário. Tipo de local. Por exemplo, Cidade.

    Tipo de dados: Cadeia de caracteres

    Tabela: Locais [cmn_location]
    relatedPlace.id Necessá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 Necessário. Descrição da função de local. Por exemplo, ordem de serviço.

    Tipo de dados: Cadeia de caracteres
    fuso horário Necessário. Fuso horário a ser usado ao reservar o intervalo de compromisso especificado.

    Tipo de data: Cadeia de caracteres

    Formato: Formato de país/cidade ou área, como EUA/Leste
    ValidFor Necessário. Intervalo de datas para o qual o compromisso é válido.

    Tipo de dados: Objeto

    "validFor": {
  "endDateTime": "String",
  "startDateTime": "String"
}
    ValidFor.endDateTime Necessá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 Necessá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 da 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
    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 possíveis códigos de status usados na REST API, consulte REST API códigos de resposta HTTP .

    Tabela 12. 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
    categoria Sys_id do produtor de registro configurado para a configuração do serviço de agendamento de compromissos.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Campo Item do catálogo da tabela Configuração do serviço de agendamento de compromissos [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 reagendar ou excluir o compromisso.

    Tipo de dados: Cadeia de caracteres
    id Sys_id do compromisso.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de Configuração do serviço de agendamento de compromissos [sn_apptmnt_booking_service_config]
    LastUpdate 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.
    EntidadeRelacionada Detalhes sobre a entidade relacionada do compromisso.

    Tipo de dados: Matriz de objetos

    "relatedEntity": [
 {
  "@referredType": "String",
  "id": "String",
  "role": "String"
  }
]
    RelatedEntity. Em referredType Tipo de item ou serviço.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela Ordem de serviço [wm_order]
    EntidadeRelatedEntity.Id Sys_id da entidade relacionada.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela Ordem de serviço [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 Ordem de serviço [wm_order]
    RelatedParty Lista de contatos do compromisso. Cada contato é um objeto na matriz.

    Tipo de dados: Matriz de objetos

    "relatedParty": [
 {
  "@referredType": "String",
  "id": "String",
  "name": " String",
  "role": "String"
 }
]
    RelatedParty. Em referredType Tipo de cliente.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de contato [customer_contact]
    IdentidadeRelatedParty.id Sys_id do contato do cliente associado à ordem de serviço.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de contato [customer_contact]
    relatedParty.name Nome do contato do cliente.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de contato [customer_contact]
    RelatedParty.role Função do contato do cliente.
    Valores possíveis:
    • Cliente: O contato tem uma função de cliente.
    • Técnico: O contato tem uma função de técnico.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de contato [customer_contact]
    RelatedPlace Detalhes do local do compromisso associado.

    Tipo de dados: Objeto

    "relatedPlace": {
  "@referredType": "String",
  "id": "String",
  "name": "String",
  "role": "String"
}
    RelatedPlace. Em referredType Endereço geográfico da consulta.

    Valor possível: GeographicLocation.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de local [cmn_location]
    RelatedPlace.id Sys_id do local.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de local [cmn_location]
    relatedPlace.name Nome do local relacionado ao contato. Por exemplo, 100 South Charles Street, Baltimore, MD.

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de local [cmn_location]
    RelatedPlace.role Função do local da consulta como um endereço de intervenção.

    Valor possível: InterventionAddress

    Tipo de dados: Cadeia de caracteres

    Armazenado em: Tabela de local [cmn_location]
    êxito 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
    fuso horário Fuso horário usado ao reservar ou atualizar o intervalo de compromisso 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": "String"
 "startDateTime": "String"
}
    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 de compromisso.

    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"
}