> For the complete documentation index, see [llms.txt](https://kb.stoque.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.stoque.com.br/zeev/apis/all/access/people/add.md). # 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](/zeev/apis/como-utilizar-as-apis-do-zeev/como-gerar-tokens-para-autenticar-nas-apis.md) 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 [#parametros-obrigatorios](#parametros-obrigatorios "mention") e se desejar complementar o cadastro confira os demais parâmetros em [#api-2-users](#api-2-users "mention"); 3. **Enviar a Requisição**: Utilize o endpoint [#api-2-users](#api-2-users "mention") 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: ```json { "name":"Alan Cooper", "username":"alan.cooper", "email":"alan.cooper@zeev.it", "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](/zeev/formula-zeev/configuracoes-iniciais/definir-formas-de-autenticacao.md) ### Modelo de corpo de requisição para criar usuários no Zeev ```json { "ifExists":"update", //update, retrieve ou block "authenticationType":"internal", //internal,network, ssoonly ou default "name":"Alan Cooper", "username":"alan.cooper", "email":"alan.cooper@zeev.it", "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: ```json { "ifExists":"update", //update, retrieve ou block "authenticationType":"internal", //internal,network, ssoonly ou default "name":"Alan Cooper", "username":"alan.cooper", "email":"alan.cooper@zeev.it", "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: ```json { "ifExists":"update", //update, retrieve ou block "authenticationType":"ssoonly", //internal,network, ssoonly ou default "name":"Alan Cooper", "username":"alan.cooper", "email":"alan.cooper@zeev.it", "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) > \[ ```json {"openapi":"3.1.1","info":{"title":"API RESTFul versão 2.0 ","version":"2"},"servers":[{"url":"https://seu_endereco.do.zeev"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Utilize um token válido de usuário para realizar a requisição","name":"Authorization","in":"header"}},"schemas":{"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModelResult":{"type":"object","properties":{"action":{"description":"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","type":"string"},"id":{"format":"int32","description":"Identificador da pessoa","type":"integer"},"username":{"description":"Login da pessoa","type":"string"},"name":{"description":"Nome da pessoa","type":"string"},"email":{"description":"Email da pessoa","type":"string"},"identification":{"description":"Matrícula da pessoa","type":"string"},"document":{"description":"CPF / CNPJ","type":"string"},"isActive":{"description":"Indica se o cadastro da pessoa está ativo","type":"boolean"},"authenticationType":{"description":"Tipo de autenticação","type":"string"},"licenseType":{"description":"Tipo de licença","type":"string"},"businessShiftId":{"format":"int32","description":"Código identificador do turno de trabalho ","type":"integer"},"leadershipId":{"format":"int32","description":"Informações do gestor imediato desta pessoa","type":"integer"},"countryId":{"format":"int32","description":"Código identificador do país","type":"integer"},"countryName":{"description":"Nome do país","type":"string"},"stateId":{"format":"int32","description":"Código identificador do estado","type":"integer"},"stateName":{"description":"Nome do estado","type":"string"},"stateSymbol":{"description":"Sigla/símbolo do estado","type":"string"},"cityId":{"format":"int32","description":"Código identificador da cidade","type":"integer"},"cityName":{"description":"Nome da cidade","type":"string"},"timeZoneId":{"format":"int32","description":"Código identificador do fuso horário","type":"integer"},"timezoneAbbreviation":{"description":"Abreviação do fuso horário","type":"string"}}},"Orquestra.Models.Base.ApiModels.Suport.ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.Error"}}},"Orquestra.Models.Base.ApiModels.Suport.Error":{"type":"object","properties":{"code":{"type":"string"},"key":{"type":"string"},"message":{"type":"string"},"vars":{"type":"array","items":{"type":"string"}},"details":{"type":"array","items":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.Error"}}}},"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel":{"required":["ifExists","username","name","email","licenseType"],"type":"object","properties":{"ifExists":{"description":"Indicativo da operação a realizar se o login já existe","type":"string"},"username":{"description":"Login ou e-mail de autenticação da pessoa","type":"string"},"name":{"description":"Nome da pessoa","type":"string"},"email":{"description":"E-mail para recebimento de notificações","type":"string"},"identification":{"description":"Número de documento ou identificação","type":"string"},"document":{"description":"Número de CPF (11 dígitos numéricos) ou CNPJ (14 caracteres: 12 alfanuméricos + 2 numéricos)","type":"string"},"isActive":{"description":"Indicador se a pessoa está ativa","type":"boolean"},"authenticationType":{"description":"Indicador do tipo de autenticação da pessoa","type":"string"},"licenseType":{"description":"Indicador do tipo de licenciamento a ser usado para a pessoa","type":"string"},"timeZone":{"format":"int32","description":"Identificador do fuso horário","type":"integer"},"positions":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_TeamsAndPositions","description":"Lista de times e funções da pessoa"},"groups":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_Groups","description":"Lista de grupos de manutenção associadas à pessoa"},"welcomeMessage":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_WelcomeMessage","description":"Mensagem de e-mail de instruções e boas vindas a ser enviadas"},"businessShiftId":{"format":"int32","description":"Turno de trabalho da pessoa","type":"integer"},"leadershipId":{"format":"int32","description":"Identificador único do gestor imediato da pessoa","type":"integer"},"countryId":{"format":"int32","description":"Identificador único do país","type":"integer"},"stateId":{"format":"int32","description":"Identificador único do estado","type":"integer"},"cityId":{"format":"int32","description":"Identificador único da cidade","type":"integer"}}},"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_TeamsAndPositions":{"required":["ifExistsUser","items"],"type":"object","properties":{"ifExistsUser":{"description":"Indicativo da operação a realizar para os times e funções se o login já existe previamente","type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_TeamsAndPositions+AddUserModel_TeamsAndPositions_Items"}}}},"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_TeamsAndPositions+AddUserModel_TeamsAndPositions_Items":{"type":"object","properties":{"teamId":{"format":"int32","description":"Identificador único do time","type":"integer"},"teamCode":{"description":"Identificador do código original do time","type":"string"},"positionId":{"format":"int32","description":"Identificador único da função","type":"integer"},"positionCode":{"description":"Identificador do código original da função","type":"string"}}},"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_Groups":{"required":["ifExistsUser","items"],"type":"object","properties":{"ifExistsUser":{"description":"Indicativo da operação a realizar para grupos se o login já existe previamente","type":"string"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_Groups+AddUserModel_Groups_Items"}}}},"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_Groups+AddUserModel_Groups_Items":{"type":"object","properties":{"groupId":{"format":"int32","description":"Identificador único do grupo","type":"integer"},"groupCode":{"description":"Identificador do código original do grupo","type":"string"}}},"Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel+AddUserModel_WelcomeMessage":{"type":"object","properties":{"send":{"type":"boolean"}}}}},"paths":{"/api/2/users":{"post":{"tags":["People / Pessoas"],"summary":"Cadastrar uma pessoa, com grupos de manutenção, times e funções relacionados (Auth)","description":"[https://kb.stoque.com.br/zeev/apis/all/access/people/add](https://kb.stoque.com.br/zeev/apis/all/access/people/add)","operationId":"Users_AddUser","responses":{"200":{"description":"Sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModelResult"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModelResult"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModelResult"}}}},"400":{"description":"Solicitação ou dados da solicitação são inválidas","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}}}},"401":{"description":"Pessoa não autorizada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}}}},"403":{"description":"Pessoa não tem permissão de executar essa operação","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}}}},"404":{"description":"O registro não foi encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}}}},"429":{"description":"Muitas requisições em um determinado período de tempo","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}}}},"500":{"description":"Ocorreu algum erro interno no servidor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}},"text/xml":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.Suport.ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Orquestra.Models.Base.ApiModels.External._20.Users.AddUserModel"}}},"description":"Modelo de dados da pessoa","required":true}}}}} ``` Exemplo de requisição para cadastrar uma pessoa no Zeev {% tabs %} {% tab title="Node.js" %} ```javascript 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": "alan.cooper@zeev.it", "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); }; ``` {% endtab %} {% endtabs %} *** ## **Links relacionados**: * [O que é preciso para fazer integrações do Zeev para outros sistemas?](/zeev/integracoes/o-que-e-preciso-para-fazer-integracoes.md) * [Como autenticar nas APIs do Zeev](/zeev/apis/como-utilizar-as-apis-do-zeev/como-gerar-tokens-para-autenticar-nas-apis.md) * [Como controlar o volume máximo de requisições à APIs](/zeev/apis/como-utilizar-as-apis-do-zeev/como-controlar-o-volume-maximo-de-requisicoes-a-apis.md) * [Como acessar o Swagger / OpenAPI](/zeev/apis/como-utilizar-as-apis-do-zeev/como-acessar-o-swagger-openapi.md) * [Como criar pessoas](/zeev/usuarios-e-permissoes/gerenciar-usuarios/como-criar-usuarios.md) * [Como excluir pessoas](/zeev/usuarios-e-permissoes/gerenciar-usuarios/como-excluir-usuarios.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://kb.stoque.com.br/zeev/apis/all/access/people/add.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.