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:

1. Autenticação: Primeiro obtenha um token de autenticação com permissão de realizar essa operação;

2. 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;

3. 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

Bearer

AuthorizationstringObrigatório

Utilize um token válido de usuário para realizar a requisição

Corpo

application/json

ifExistsstringObrigatório

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

usernamestringObrigatório

Login ou e-mail de autenticação da pessoa

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.

application/jsontext/jsontext/xml

400

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

application/jsontext/jsontext/xml

401

Pessoa não autorizada

application/jsontext/jsontext/xml

403

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

application/jsontext/jsontext/xml

404

O registro não foi encontrado

application/jsontext/jsontext/xml

429

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

application/jsontext/jsontext/xml

500

Ocorreu algum erro interno no servidor

application/jsontext/jsontext/xml

post

/api/2/users

HTTPcURLJavaScriptPython

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

Node.js

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:

• O que é preciso para fazer integrações do Zeev para outros sistemas?

• Como autenticar nas APIs do Zeev

• Como controlar o volume máximo de requisições à APIs

• Como acessar o Swagger / OpenAPI

• Como criar pessoas

• Como excluir pessoas