REST API de RH

  • Versão de lançamento: Washingtondc
  • Atualizado 1 de fev. de 2024
  • 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 essa 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 dos funcionários que foram adicionados ou cujas informações foram atualizadas na data especificada ou após.
    Nota:
    Os funcionários devem ter o trabalho ou o país de origem especificados como Estados Unidos para este endpoint para incluí-los nos resultados do retorno.
    Além disso, o endpoint envia os seguintes parâmetros para a aplicação CIC Plus integrada (consulte a seção Retornos para obter as descrições):
    • EmployeeIdentifier
    • Nome
    • Nome do meio
    • Sobrenome
    • E-mail
    • WorkAddress
    • WorkCity
    • Estado do trabalho
    • WorkPostalCode
    • WorkCountry
    • Endereço residencial
    • Cidade natal
    • Estado natal
    • Código postal residencial
    • País natal
    • Data de nascimento
    • Contratar data

    Formato de 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
    Tabela 2. Parâmetros de consulta
    Parâmetro Descrição
    employee_identifier 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 dele. 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 iniciar a recuperação de registros. Use este valor para paginar a recuperação do registro. Esta 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 paginar todos os registros disponíveis, use sysparm_offset=sysparm_offset+sysparm_limit, até 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 (trabalho ou residência) que foram adicionados à sua instância, ou cujas informações foram atualizadas nesta data ou após, são incluídos nos resultados retornados.
    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 padrão é 00:00:00)
    Tabela 3. Parâmetros do corpo da solicitação (XML ou JSON)
    Nome Descrição
    Nenhum

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis.

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. 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ário 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 dos dados.
    • falso: não há dados adicionais.

    Códigos de status

    Os códigos de status a seguir se aplicam a esta ação HTTP. Para obter uma lista de códigos de status possíveis usados na REST API, consulte Códigos de resposta HTTP da REST API.

    Tabela 6. Códigos de status
    Código de status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    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
    Contratar data 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ência Cidade natal do funcionário.

    Tipo de dados: cadeia de caracteres
    País de residê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
    Estado do trabalho Estado de trabalho do funcionário.

    Tipo de dados: cadeia de caracteres

    Amostra de solicitação de cURL para as 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 de cURL para uma lista de funcionários adicionados/atualizados em ou após 18/05/2019

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