Criar ou atualizar dados de pessoas

Como cadastrar pessoas no Zeev utilizando API?

Para preparar uma requisição de cadastro de usuários ao Zeev, siga estes passos:

Autenticação: Primeiro obtenha um token de autenticação com permissão de realizar essa operação;
Dados de cadastro: Obtenha os dados necessários para os campos obrigatórios conforme explicado em Parâmetros obrigatórios e se desejar complementar o cadastro confira os demais parâmetros em Criar ou atualizar dados de pessoas;
Enviar a Requisição: Utilize o endpoint Criar ou atualizar dados de pessoas para enviar a requisição conforme modelo e exemplo (troque seu_endereco.do.zeev pelo endereço que você usa para acessar o Zeev);

Parâmetros obrigatórios

Para esta requisição é obrigatório informar no corpo as propriedades username, name, email e licenseType, confira um modelo simples para esta requisição:

{
     "name":"Alan Cooper",
     "username":"alan.cooper",
     "email":"[email protected]",
     "licenseType":"actor"
}

Parâmetro ifExists

Na raiz da estrutura do corpo de requisição, o parâmetro ifExists indica o que deve ser feito se o username (login) da pessoa já existir no cadastro, confira abaixo as opções disponíveis:

block: caso o username já exista, o retorno será um erro e a operação será bloqueada. Se a propriedade não for informada no corpo da requisição, este é o comportamento padrão adotado;
retrieve: Se este valor for preenchido na propriedade ifExistis na estrutura raiz do corpo da requisição, caso o username já exista, o retorno serão os dados da pessoa existente;
update: Se este valor for preenchido na propriedade ifExistis na estrutura raiz do corpo da requisição, caso o username já exista, os dados da pessoa existente serão atualizados.

Parâmetro authenticationType

Na raiz da estrutura do corpo de requisição, o parâmetro authenticationType indica qual o tipo de autenticação será definido para a pessoa. As opções atualmente disponíveis são:

default: Será usado o padrão do sistema para autenticação (opção utilizada se o parâmetro não for informado no corpo da requisição;
internal: Será criada uma senha temporária e armazenada no sistema;
network: A pessoa autenticará através da rede / active directory / LDAP;
ssoonly: A pessoa autenticará através de SSO somente;

Entenda mais sobre tipos de autenticação em Definir formas de autenticação

Modelo de corpo de requisição para criar usuários no Zeev

{
     "ifExists":"update", //update, retrieve ou block
     "authenticationType":"internal", //internal,network, ssoonly ou default 
     "name":"Alan Cooper",
     "username":"alan.cooper",
     "email":"[email protected]",
     "licenseType":"actor" //actor, requester
}

Como indicar times e funções da pessoa ao realizar o cadastro via API?

Ao realizar o cadastro de pessoas utilizando API, é possível informar os times e funções da pessoa na propriedade positions. Para indicar time e posição, é obrigatório informar também a propriedade ifExistsUser neste nível ( esta opção é diferente de ifExists informada na raiz do corpo de requisição) e um array de itens que indicam os times e funções da pessoa. As opções disponíveis para a propriedade positions.ifExistsUser são:

append: caso o username já exista, os times e funções que a pessoa não possuir serão acrescentados;
donothing: caso o username já exista, nada será modificado ou acrescentado na lista de times e funções;
replace: caso o username já exista, os times e funções já existentes serão excluídos e substituídos pelos enviados no modelo;

Obs: No array de itens, se informado teamId, não precisa ser informado temCode e o mesmo para postionId e positionCode.

Exemplo:

{
     "ifExists":"update", //update, retrieve ou block
     "authenticationType":"internal", //internal,network, ssoonly ou default 
     "name":"Alan Cooper",
     "username":"alan.cooper",
     "email":"[email protected]",
     "licenseType":"actor", //actor, requester
     "positions":{
          "ifExistsUser":"append", //append, replace, donothing
          "items":[
                {
                    "teamCode": "admN043",
                    "positionCode": "Analist054"
                }
           ]
     }
}

Como indicar o grupos de permissão ao cadastrar pessoas utilizando API?

Ao realizar o cadastro de pessoas utilizando API, é possível informar os grupos de acesso da pessoa na propriedade groups. Para indicar os grupos, é obrigatório informar também a propriedade ifExistsUser neste nível ( esta opção é diferente de ifExistsUser informada dentro da estrutura positions do corpo de requisição) e um array de itens que indicam os times e funções da pessoa. As opções disponíveis para a propriedade groups.ifExistsUser são:

append: caso o username já exista, os grupos de manutenção que a pessoa não possuir serão acrescentados
donothing: caso o username já exista, nada será modificado ou acrescentado na lista de grupos de manutenção
replace: caso o username já exista, os grupos de manutenção já existentes serão excluídos e substituídos pelos enviados no modelo

Obs: No array de itens, apenas uma das propriedades é obrigatória entre groupId e groupCode.

Exemplo:

{
     "ifExists":"update", //update, retrieve ou block
     "authenticationType":"ssoonly", //internal,network, ssoonly ou default 
     "name":"Alan Cooper",
     "username":"alan.cooper",
     "email":"[email protected]",
     "licenseType":"actor", //actor, requester
     "groups":{
          "ifExistsUser":"append", //append, replace, donothing
          "items":[
                {
                    "groupCode": "adm1z0"
                }
           ]
     }
}

Cadastrar uma pessoa, com grupos de manutenção, times e funções relacionados (Auth)

post

Autorizações

Corpo

ifExistsstringObrigatório

Indicativo da operação a realizar se o login já existe

usernamestringObrigatório

namestringObrigatório

Nome da pessoa

emailstringObrigatório

E-mail para recebimento de notificações

identificationstringOpcional

Número de documento ou identificação

documentstringOpcional

Número de CPF ou CNPJ

Pattern: [0-9\.\-\/]+

isActivebooleanOpcional

Indicador se a pessoa está ativa

authenticationTypestringOpcional

Indicador do tipo de autenticação da pessoa

licenseTypestringObrigatório

Indicador do tipo de licenciamento a ser usado para a pessoa

timeZoneinteger · int32Opcional

Fuso horário do cliente

businessShiftIdinteger · int32Opcional

Turno de trabalho da pessoa

leadershipIdinteger · int32Opcional

Identificador único do gestor imediato da pessoa

Respostas

200

Sucesso.

400

Solicitação ou dados da solicitação são inválidas

401

Pessoa não autorizada

403

Pessoa não tem permissão de executar essa operação

404

O registro não foi encontrado

429

Muitas requisições em um determinado período de tempo

500

Ocorreu algum erro interno no servidor

post

POST /api/2/users HTTP/1.1
Host: seu_endereco.do.zeev
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 444

{
  "ifExists": "text",
  "username": "text",
  "name": "text",
  "email": "text",
  "identification": "text",
  "document": "text",
  "isActive": true,
  "authenticationType": "text",
  "licenseType": "text",
  "timeZone": 1,
  "positions": {
    "ifExistsUser": "text",
    "items": [
      {
        "teamId": 1,
        "teamCode": "text",
        "positionId": 1,
        "positionCode": "text"
      }
    ]
  },
  "groups": {
    "ifExistsUser": "text",
    "items": [
      {
        "groupId": 1,
        "groupCode": "text"
      }
    ]
  },
  "welcomeMessage": {
    "send": true
  },
  "businessShiftId": 1,
  "leadershipId": 1
}

{
  "action": "text",
  "id": 1,
  "username": "text",
  "name": "text",
  "email": "text",
  "identification": "text",
  "document": "text",
  "isActive": true,
  "authenticationType": "text",
  "licenseType": "text",
  "businessShiftId": 1,
  "leadershipId": 1
}

Exemplo de requisição para cadastrar uma pessoa no Zeev

const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("Authorization", "Bearer TOKEN_DO_USUARIO");

const raw = JSON.stringify({
  "ifExists": "update",
  "username": "alan.cooper",
  "name": "Alan Cooper",
  "email": "[email protected]",
  "licenseType": "actor",
  "identification": "09785921213",
  "document": "12344321",
  "isActive": true,
  "authenticationType": "internal",
  "positions": {
    "ifExistsUser": "donothing",
    "items": [
      {
        "teamId": 123,
        "teamCode": "Tst01",
        "positionId": 432,
        "positionCode": "Ps0t1"
      }
    ]
  },
  "groups": {
    "ifExistsUser": "donothing",
    "items": [
      {
        "groupId": 96818982,
        "groupCode": "grp0cod"
      }
    ]
  },
  "welcomeMessage": {
    "send": false
  },
  "businessShiftId": 189,
  "leadershipId": 4321
});

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw
};

try {
  const response = await fetch("https://seu_endereco.do.zeev/api/2/users", requestOptions);
  const result = await response.json();
  console.log(result)
} catch (error) {
  console.error(error);
};

Links relacionados:

AnteriorConsultar dados de uma pessoa PróximoExcluir pessoas

Atualizado há 1 ano