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":"[e-mail]",
     "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":"[e-mail]",
     "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":"[e-mail]",
     "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":"[e-mail]",
     "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

https://kb.stoque.com.br/zeev/apis/all/access/people/add

Autorizações

AuthorizationstringObrigatório

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

Corpo

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 (11 dígitos numéricos) ou CNPJ (14 caracteres: 12 alfanuméricos + 2 numéricos)

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

Identificador do fuso horário

businessShiftIdinteger · int32Opcional

Turno de trabalho da pessoa

leadershipIdinteger · int32Opcional

Identificador único do gestor imediato da pessoa

countryIdinteger · int32Opcional

Identificador único do país

stateIdinteger · int32Opcional

Identificador único do estado

cityIdinteger · int32Opcional

Identificador único da cidade

Respostas

200

Sucesso.

actionstringOpcional

Resultado da operação: Retrieved = Cadastro da pessoa já existia e o ID foi retornado | Update = Cadastro da pessoa já existia e foi atualizado | Created = Cadastro da pessoa foi criado | Error = A operação falhou

idinteger · int32Opcional

Identificador da pessoa

usernamestringOpcional

Login da pessoa

namestringOpcional

Nome da pessoa

emailstringOpcional

Email da pessoa

identificationstringOpcional

Matrícula da pessoa

documentstringOpcional

CPF / CNPJ

isActivebooleanOpcional

Indica se o cadastro da pessoa está ativo

authenticationTypestringOpcional

Tipo de autenticação

licenseTypestringOpcional

Tipo de licença

businessShiftIdinteger · int32Opcional

Código identificador do turno de trabalho

leadershipIdinteger · int32Opcional

Informações do gestor imediato desta pessoa

countryIdinteger · int32Opcional

Código identificador do país

countryNamestringOpcional

Nome do país

stateIdinteger · int32Opcional

Código identificador do estado

stateNamestringOpcional

Nome do estado

stateSymbolstringOpcional

Sigla/símbolo do estado

cityIdinteger · int32Opcional

Código identificador da cidade

cityNamestringOpcional

Nome da cidade

timeZoneIdinteger · int32Opcional

Código identificador do fuso horário

timezoneAbbreviationstringOpcional

Abreviação do fuso horário

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/api/2/users

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

{
  "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,
  "countryId": 1,
  "stateId": 1,
  "cityId": 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,
  "countryId": 1,
  "countryName": "text",
  "stateId": 1,
  "stateName": "text",
  "stateSymbol": "text",
  "cityId": 1,
  "cityName": "text",
  "timeZoneId": 1,
  "timezoneAbbreviation": "text"
}

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": "[e-mail]",
  "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