REST API de RH

  • Versão de lançamento: Yokohama
  • Atualizado 30 de jan. de 2025
  • 5 min. de leitura

    • A REST API de RH fornece endpoints que retornam informações sobre funcionários que trabalham ou moram nos Estados Unidos.

    Para acessar esta API, você deve ter a função sn_hr_core.usa_employee_only e o plug-in Human Resources Scoped App: Core (com_sn_hr_core) ativado.

    REST de RH - GET /get_usa_employee_profile

    Retorna informações de perfil de funcionários baseados nos Estados Unidos.

    As informações retornadas podem ser:
    • Informações de perfil do funcionário para um ID de funcionário especificado.
    • Informações para funcionários que foram adicionados ou cujas informações foram atualizadas em ou após uma data especificada.
    Nota:
    Os funcionários devem ter o país de residência ou de trabalho especificado como os Estados Unidos para que este endpoint os inclua nos resultados de retorno.
    Além disso, o endpoint envia os seguintes parâmetros para a aplicação CIC Plus integrada (consulte a seção Devoluções para obter descrições):
    • EmployeeIdentifier
    • Nome
    • Nome do meio
    • Sobrenome
    • E-mail
    • WorkAddress
    • WorkCity
    • WorkState
    • WorkPostalCode
    • WorkCountry
    • Endereço residencial
    • Cidade natal
    • EstadoDeCasa
    • ResidênciaCódigo Postal
    • País de origem
    • Data de nascimento
    • HireDate

    Formato da URL

    URL padrão: /api/sn_hr_core/hr_rest_api/get_usa_employee_profile

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    Nenhum(a)
    Tabela 2. Parâmetros de consulta
    Parâmetro Descrição
    funcionário_identificador Identificador exclusivo de um funcionário. O sistema de chamada gera este valor e pode estar em qualquer formato que seja consistente com o sistema. Para obter esse valor, primeiro chame o endpoint usando o parâmetro updated_after.
    Nota:
    Este parâmetro é mutuamente exclusivo com o parâmetro updated_after. Este parâmetro define um funcionário exclusivo, enquanto updated_after retorna um grupo de funcionários criados/atualizados após uma data especificada.

    Tipo de dados: cadeia de caracteres
    sysparm_limit Número máximo de registros a serem retornados. Para solicitações que excedem esse número de registros, use o parâmetro sysparm_offset para paginar a recuperação do registro.

    Tipo de dados: número

    Padrão: 1000
    sysparm_offset Índice de registro inicial para o qual a recuperação de registros será iniciada. Use este valor para paginar a recuperação do registro. Essa funcionalidade permite a recuperação de todos os registros, independentemente do número de registros, em pequenos blocos gerenciáveis.

    Por exemplo, na primeira vez que você chama este endpoint, sysparm_offset é definido como "0". Para simplesmente percorrer todos os registros disponíveis, use sysparm_offset=sysparm_offset+sysparm_limitaté chegar ao fim de todos os registros.
    updated_after Data a ser usada para determinar os dados do funcionário a serem retornados. Todos os funcionários baseados nos Estados Unidos (do trabalho ou em casa) que foram adicionados à sua instância ou cujas informações foram atualizadas a partir desta data são incluídos nos resultados de retorno.
    Nota:
    Este parâmetro é mutuamente exclusivo com o parâmetro employee_identifier.

    Tipo de dados: cadeia de caracteres

    Formato: AAAA-MM-DD HH:MM:SS ou AAAA-MM-DD (o tempo padrão é 00:00:00)
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    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. Tipos compatíveis: application/json ou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Próxima página Sinalizador que indica se há dados adicionais a serem obtidos em uma chamada subsequente. Por exemplo, se houver um total de 120 registros de funcionários que correspondam aos critérios de pesquisa e sysparm_limit estiver definido como 100, Next-Page será verdadeiro. Se nenhum resultado adicional estiver disponível, Next-Page será falso.
    Valores válidos:
    • verdadeiro: dados adicionais estão disponíveis, outra chamada deve ser feita para obter a próxima parte de dados.
    • falso: não há dados adicionais.

    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 do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    404 Não encontrado. O item solicitado não foi encontrado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Elemento Descrição
    Data de nascimento Data de nascimento do funcionário.

    Tipo de dados: cadeia de caracteres
    Empresa Nome da empresa.

    Tipo de dados: cadeia de caracteres
    E-mail Endereço de e-mail do funcionário.

    Tipo de dados: cadeia de caracteres
    EmployeeIdentifier Identificador exclusivo do funcionário.

    Tipo de dados: cadeia de caracteres
    Nome Nome do funcionário.

    Tipo de dados: cadeia de caracteres
    HireDate Data em que o funcionário foi contratado.

    Tipo de dados: cadeia de caracteres
    Sobrenome Sobrenome do funcionário.

    Tipo de dados: cadeia de caracteres
    Nome do meio Nome do meio do funcionário.

    Tipo de dados: cadeia de caracteres
    Recontratar Para uso futuro.

    Tipo de dados: cadeia de caracteres
    EndereçoResidência Endereço residencial do funcionário.

    Tipo de dados: cadeia de caracteres
    ResidênciaCidade Cidade natal do funcionário.

    Tipo de dados: cadeia de caracteres
    PaísResidência País de origem do funcionário.

    Tipo de dados: cadeia de caracteres
    Código Postal de Residência CEP residencial do funcionário.

    Tipo de dados: cadeia de caracteres
    Estado de residência Estado natal do funcionário.

    Tipo de dados: cadeia de caracteres
    Sufixo Sufixo do funcionário, como Sr., Sra. ou Dr.

    Tipo de dados: cadeia de caracteres
    WorkAddress Endereço comercial do funcionário.

    Tipo de dados: cadeia de caracteres
    WorkCity Cidade de trabalho do funcionário

    Tipo de dados: cadeia de caracteres
    WorkCountry País de trabalho do funcionário.

    Tipo de dados: cadeia de caracteres
    WorkPostalCode CEP do trabalho do funcionário.

    Tipo de dados: cadeia de caracteres
    WorkState Estado de trabalho do funcionário.

    Tipo de dados: cadeia de caracteres

    Amostra de solicitação cURL para informações de um funcionário específico

    curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?employee_identifier=231"
-H "accept: application/json" \
-u "username":"password"
    {"result": [
 {
  "EmployeeIdentifier": "231",
  "FirstName": "Harold",
  "MiddleName": "William",
  "LastName": "Lewis",
  "Suffix": "Mr.",
  "Email": "Howard.Lewis@example.com",
  "BirthDate": "",
  "HireDate": "2021-02-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
 }
]}

    Amostra de solicitação cURL para uma lista de funcionários adicionados/atualizados em 18/05/2019 ou após

    curl -X GET "https://instance.servicenow.com/api/sn_hr_core/V1/hr_rest_api/get_usa_employee_profile?update_after=2019-05-18"
-H "accept: application/json" \
-u "username":"password"
    {"result": [
 {
  "EmployeeIdentifier": "2345",
  "FirstName": "Cheryl",
  "MiddleName": "Lynn",
  "LastName": "Smith",
  "Suffix": "Mrs.",
  "Email": "Cheryl.Smith@example.com",
  "BirthDate": "",
  "HireDate": "2019-06-18",
  "Company": "ServiceNow Inc",
  "ResidenceAddress": "",
  "ResidenceCity": "SD",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "2617 South Robinson Avenue, Oklahoma City",
  "WorkCity": "Oklahoma",
  "WorkState": "OK",
  "WorkPostalCode": "73109",
  "WorkCountry": "USA",
  "ReHire": ""
  },
  {
  "EmployeeIdentifier": "1111",
  "FirstName": "Thomas",
  "MiddleName": "",
  "LastName": "Doe",
  "Suffix": "Mr.",
  "Email": "Thomas.Doe@example.com",
  "BirthDate": "1978-05-22",
  "HireDate": "2019-08-14",
  "Company": "",
  "ResidenceAddress": "",
  "ResidenceCity": "San Jose",
  "ResidenceState": "CA",
  "ResidencePostalCode": "",
  "ResidenceCountry": "",
  "WorkAddress": "13308 Midland Road, Poway",
  "WorkCity": "Poway",
  "WorkState": "CA",
  "WorkPostalCode": "",
  "WorkCountry": "USA",
  "ReHire": ""
  }
]}