Histórico da Página
Versões comparadas
comparado com
Chave
- Esta linha foi adicionada.
- Esta linha foi removida.
- A formatação mudou.
Rest users
O SCIM 'users' é um protocolo de aplicação REST para provisionamento e gerenciamento de dados de identidade na web. O protocolo suporta a criação, modificação, recuperação e descoberta de usuários.
O serviço users do Protheus permite a inclusão e manipulação de dados de usuário no sistema. É altamente aconselhável que a autenticação de serviços esteja habilitada no servidor rest para evitar manipulação indevida dos dados. Todos os usuários que se autenticarem para utilizar este serviço devem possuir acesso a rotina CFGA510 (o cadastro de usuários no Protheus)
Detalhes da configuração do REST Protheus e como ligar a autenticação dos serviços acesse a página do REST Protheus aqui.
| Aviso | ||
|---|---|---|
| ||
|
Métodos disponíveis
GET
Sintaxe /users/{userId}
Para recuperar um usuário conhecido, os clientes enviam requisições GET. Se o usuário existir o servidor responde com o código de estado 200 e inclui o resultado no corpo da resposta. Também é possível listar os usuários do sistema, omitindo o envio do pathParam {userId}.
| HTML |
|---|
<h2>Parâmetros</h2>
<div class="methodsubtabletitle"><b>pathParam</b></div>
<table id="methodsubtable">
<tr>
<th width="150px">Nome</th>
<th>Tipo</th>
<th>Descrição</th>
<th>Default</th>
</tr>
<tr>
<td style="width:150px;">userId
</td>
<td>string</td>
<td style="width:150px;">id ou código do usuário no sistema</td>
<td></td>
</tr>
</table>
<br>
<div class="methodsubtabletitle"><b>queryParam</b></div>
<table id="methodsubtable">
<tr>
<th width="150px">Nome</th>
<th>Tipo</th>
<th>Descrição</th>
<th>Default</th>
</tr>
<tr>
<td style="width:150px;">showAdmin
</td>
<td>boolean</td>
<td style="width:150px;">Indica se o get deve retornar o usuário admin</td>
<td>false</td>
</tr>
<tr>
<td style="width:150px;">count
</td>
<td>numérico</td>
<td style="width:150px;">Indica quantos usuários deverão ser retornados pelo método</td>
<td>Todos</td>
</tr>
<tr>
<td style="width:150px;">startIndex
</td>
<td>numérico</td>
<td style="width:150px;">Indica a partir de qual usuário encontrado deverá ocorrer o retorno.</td>
<td>1</td>
</tr>
<tr>
<td style="width:150px;">attributes
</td>
<td>string</td>
<td style="width:150px;">Indica quais atributos do jSon devem ser retornados. Os atributos devem ser separados por ','.
</td>
<td>Retorna todos os atributos</td>
</tr>
<tr>
<td style="width:150px;">foundBy
</td>
<td>string</td>
<td style="width:150px;">Parâmetro opcional, usado para determinar o tipo de busca do usuário, ID, LOGIN, MAIL, SSO, OAUTH, AD, UID ou LDAP</td>
<td>Todos</td>
</tr>
<tr>
<td style="width:150px;">domainId
</td>
<td>string</td>
<td style="width:150px;">Domínio cadastrado para o Usuário, parâmetro obrigatório quando o tipo de busca for AD(Active Directory)</td>
</tr>
</table>
|
| Nota | ||
|---|---|---|
| ||
O parâmetro atributes é case sensitive. Caso o parâmetro foundBy não for informado, a busca é feita com base em todos os tipos. |
Retorno:
| HTML |
|---|
<h2>Parâmetros</h2>
<div class="methodsubtabletitle"><b>Body</b></div>
<table id="methodsubtable">
<tr>
<th width="150px">Nome</th>
<th>Tipo</th>
<th>Descrição</th>
</tr>
<tr>
<td style="width:150px;">totalResults
</td>
<td>numérico</td>
<td style="width:150px;">Indica a quantidade de registros encontrados</td>
</tr>
<tr>
<td style="width:150px;">itemsPerPage
</td>
<td>numérico</td>
<td style="width:150px;">Quantidade de itens retornados na requisição</td>
</tr>
<tr>
<td style="width:150px;">startIndex</td>
<td>numérico</td>
<td style="width:150px;">Registro “a partir de” do retorno dos registros</td>
</tr>
<tr>
<td style="width:150px;">Id</td>
<td>string</td>
<td style="width:150px;">Id ou código do usuário no Protheus</td>
</tr>
<tr>
<td style="width:150px;">meta</td>
<td>jSon</td>
<td style="width:150px;">Relacionado a criação do usuário</td>
</tr>
<tr>
<td style="width:150px;">created</td>
<td>String</td>
<td style="width:150px;">Data de criação do usuário. Retorna no formato AAAA-MM-DD_HH:MM:SS</td>
</tr>
<tr>
<td style="width:150px;">lastModified</td>
<td>String</td>
<td style="width:150px;">Data da última alteração do usuário. Retorna no formato AAAA-MM-DD_HH:MM:SS</td>
</tr>
<tr>
<td style="width:150px;">externalId</td>
<td>string</td>
<td style="width:150px;">Código externo do usuário (e-mail para a maioria dos sistemas)</td>
</tr>
<tr>
<td style="width:150px;">name</td>
<td>string</td>
<td style="width:150px;">Código do usuário no sistema</td>
</tr>
<tr>
<td style="width:150px;">givenName</td>
<td>string</td>
<td style="width:150px;">Primeiro nome do usuário</td>
</tr>
<tr>
<td style="width:150px;">familyName</td>
<td>string</td>
<td style="width:150px;">Segundo nome do usuário</td>
</tr>
<tr>
<td style="width:150px;">displayName</td>
<td>string</td>
<td style="width:150px;">nome do usuário no sistema</td>
</tr>
<tr>
<td style="width:150px;">emails</td>
<td>array de objetos</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">emails:value</td>
<td>string</td>
<td style="width:150px;">E-mail no sistema</td>
</tr>
<tr>
<td style="width:150px;">emails:type</td>
<td>string</td>
<td style="width:150px;">Tipo do e-mail. Sempre retorna "work"</td>
</tr>
<tr>
<td style="width:150px;">primary</td>
<td>boolean</td>
<td style="width:150px;">Indica se é o e-mail primário do usuário. Sempre retorna true</td>
</tr>
<tr>
<td style="width:150px;">active</td>
<td>boolean</td>
<td style="width:150px;">Retorna se o usuário está ativo ou não no sistema</td>
</tr>
<tr>
<td style="width:150px;">groups</td>
<td>array de objetos</td>
<td style="width:150px;">Grupos ao qual o usuário pertence</td>
</tr>
<tr>
<td style="width:150px;">groups:value</td>
<td>string</td>
<td style="width:150px;">Código do grupo</td>
</tr>
<tr>
<td style="width:150px;">groups:display</td>
<td>string</td>
<td style="width:150px;">Descrição do grupo</td>
</tr>
<tr>
<td style="width:150px;">title</td>
<td>string</td>
<td style="width:150px;">Cargo do usuário</td>
</tr>
<tr>
<td style="width:150px;">employeeNumber</td>
<td>string</td>
<td style="width:150px;">Código de funcionário</td>
</tr>
<tr>
<td style="width:150px;">department</td>
<td>string</td>
<td style="width:150px;">Código do departamento do usuário</td>
</tr>
<tr>
<td style="width:150px;">manager</td>
<td>array de objetos</td>
<td style="width:150px;">Informações dos superiores do usuário</td>
</tr>
<tr>
<td style="width:150px;">manager:manageId</td>
<td>string</td>
<td style="width:150px;">Código do superior do usuário</td>
</tr>
<tr>
<td style="width:150px;">manager:displayName</td>
<td>string</td>
<td style="width:150px;">Nome do superior no sistema</td>
</tr>
</table>
|
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"schemas": [
"urn:scim:schemas:core:2.0:User",
"urn:scim:schemas:extension:enterprise:2.0:User"
],
"id": "000021",
"meta": {
"created": "2018-02-13_00:00:00",
"lastModified": "2018-02-13_00:00:00"
},
"externalId": "[email protected]",
"userName": "User1",
"name": {
"formatted": "User1",
"givenName": "User1",
"familyName": "."
},
"displayName": "Use1r",
"emails": [
{
"value": "[email protected]",
"type": "work",
"primary": true
}
],
"active": true,
"groups": [
{
"value": "000001",
"display": "grupo2"
}
],
"title": "Coordenador",
"employeeNumber": "02|00|000001",
"department": "RH",
"manager": [
{
"managerId": "000000",
"displayName": "Administrador"
}
]
}
|
A busca por um usuário passando o Id difere apenas da omissão no resultado dos parâmetros totalResult, itensPerPage e startIndex.
GET (GetUserId)
Sintaxe /users/GetUserId
Retorna o id do usuário atualmente logado pelo serviço REST no Protheus.
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"userID": "000000"
} |
POST
Sintaxe /users/{userid}/{operation}
Cria novos usuários no sistema devolvendo na requisição, quando bem sucedida, o código de resposta 201 (created).
| HTML |
|---|
<h2>Parâmetros</h2>
<div class="methodsubtabletitle">
<b>pathParam</b>
</div>
<table id="methodsubtable">
<tr>
<th width="150px">Nome</th>
<th>Tipo</th>
<th>Descrição</th>
<th>Default</th>
</tr>
<tr>
<td style="width:150px;">userId
</td>
<td>string</td>
<td style="width:150px;">Código do usuário no sistema (POST para bloquear ou desbloquear um usuário existente. Para bloquear ou desbloquear
é necessário também enviar o parâmetro operation)</td>
<td></td>
</tr>
<tr>
<td style="width:150px;">operation
</td>
<td>string</td>
<td style="width:150px;">Valores aceitos: activate e deactivate.
Indica se o usuário será ativado no sistema (activate) ou se o usuário será
bloqueado via SAML (deactivate) ou se um novo usuário será criado
(parâmetro vazio ou qualquer outro valor diferente dos anteriores. Caso o
parâmetro userId seja enviado mas não seja enviado o parâmetro operation é
assumido que um novo usuário será criado no sistema
</td>
<td></td>
</tr>
</table>
<br>
<div class="methodsubtabletitle">
<b>body</b>
</div>
<table id="methodsubtable">
<tr>
<th width="150px">Nome</th>
<th>Tipo</th>
<th>Descrição</th>
<th>Default</th>
</tr>
<tr>
<td style="width:150px;">userName</td>
<td>string</td>
<td style="width:150px;">Nome do usuário</td>
<td style="width:150px;">valor do atributo ext/adDomain</td>
</tr>
<tr>
<td style="width:150px;">displayName</td>
<td>string</td>
<td style="width:150px;">nome completo do usuário</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">externalId</td>
<td>string</td>
<td style="width:150px;">Código externo do usuário</td>
<td style="width:150px;">Código externo do usuário. Quando enviado indica que o usuário bloqueado via SAML será reativado. O Envio de
um externalId que não exista irá gerar a inclusão de um novo usuário.</td>
</tr>
<tr>
<td style="width:150px;">title</td>
<td>string</td>
<td style="width:150px;">Cargo do usuário</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">emails
<span style="color:red;">*
<sup>obrigatório</sup>
</span>
</td>
<td>array de objetos</td>
<td style="width:150px;">O primeiro e-mail com o valor primary apontado como true é o email cadastrado para o usuário (é necessário no
mínimo um email primário. Qualquer email não primário enviado é descartado). Caso o e-mail enviado já exista
em outro usuário o e-mail ficará em branco.</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">emails:value</td>
<td>string</td>
<td style="width:150px;">Código do e-mail</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">emails:primary</td>
<td>boolean</td>
<td style="width:150px;">Indica se é um email primário</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">active</td>
<td>boolean</td>
<td style="width:150px;">indica se o usuário estará ativo ou bloqueado</td>
<td style="width:150px;">true</td>
</tr>
<tr>
<td style="width:150px;">groups</td>
<td>array de objetos</td>
<td style="width:150px;">grupos ao qual o usuário está associado</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">groups:value
<span style="color:red;">*
<sup>obrigatório</sup>
</span>
</td>
<td>string</td>
<td style="width:150px;">código do grupo</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">password</td>
<td>string</td>
<td style="width:150px;">senha do usuário. Quando não informado a senha deverá ser alterada posteriormente pelo admin.</td>
<td style="width:150px;">hash randômico.</td>
</tr>
<tr>
<td style="width:150px;">ext/SAMAccountName</td>
<td>string</td>
<td style="width:150px;">Indica o login do usuário no SSO (caso informado, ele substituirá o valor informado no campo userName)</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">ext/adDomain</td>
<td>string</td>
<td style="width:150px;">domínio do usuário do SSO</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:enterprise:2.0:User</td>
<td>objeto</td>
<td style="width:150px;">Indica as configurações de usuário superior</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:enterprise:2.0:User:manager</td>
<td>array de objetos</td>
<td style="width:150px;">Array contendo informações do usuário superior</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:enterprise:2.0:User:manager:managerId</td>
<td>string</td>
<td style="width:150px;">código do usuário superior</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:totvs:2.0:User/forceChangePassword</td>
<td>boolean</td>
<td style="width:150px;">Identifica se deve ou não realizar a troca de senha no primeiro acesso</td>
<td style="width:150px;">false</td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:totvs:2.0:User/employeeNumber</td>
<td>string</td>
<td style="width:150px;">Vínculo fincional do usuário. Devem ser enviados os valores de Grupo de Empresas, Filial e Código do vínculo
separados por “|”. Exemplo para o grupo 18, filial D MG 01 e código 002: 18|D MG 01|002</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:totvs:2.0:User/department</td>
<td>string</td>
<td style="width:150px;">código do departamento do usuário</td>
<td style="width:150px;"></td>
</tr>
<tr>
<td style="width:150px;">urn:scim:schemas:extension:totvs:2.0:User/groupRule</td>
<td>numérico</td>
<td style="width:150px;">Define a regra de priorização por grupo: 1 priorizar, 2 desconsiderar e 3 somar. Qualquer valor diferente deste,
quando enviado, assume o valor 1.</td>
<td style="width:150px;"></td>
</tr>
</table>
|
Exemplo de requisição para a inclusão de usuário:
| Bloco de código | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"schemas":[
"urn:scim:schemas:core:2.0:User",
"urn:scim:schemas:extension:enterprise:2.0:User"
],
"externalId":"TesteUsr",
"meta":{
},
"userName":"Usr Tst",
"displayName":"User",
"title":"Coordenador",
"emails":[
{
"value":"[email protected]",
"primary":true
}
],
"active":true,
"groups":[
{
"value":"000002"
}
],
"password":"pass001",
"urn:scim:schemas:extension:totvs:2.0:User/forceChangePassword":true,
"urn:scim:schemas:extension:enterprise:2.0:User/employeeNumber":"02|00|000001",
"urn:scim:schemas:extension:enterprise:2.0:User/department":"RH",
"urn:scim:schemas:extension:totvs:2.0:User/groupRule":2,
"ext/sAMAccountName":"user0007",
"ext/adDomain":"XP01",
"urn:scim:schemas:extension:enterprise:2.0:User":{
"manager":[
{
"managerid":"000000"
}
]
}
} |
PUT
Sintaxe /users/{userid}
Método utilizado para atualizar um usuário existente. Todos os parâmetros podem ser enviados, tal qual o método POST.
| HTML |
|---|
<h2>Parâmetros</h2>
<div class="methodsubtabletitle">
<b>pathParam</b>
</div>
<table id="methodsubtable">
<tr>
<th width="150px">Nome</th>
<th>Tipo</th>
<th>Descrição</th>
<th>Default</th>
</tr>
<tr>
<td style="width:150px;">userId
<span style="color:red;">*
<sup>obrigatório</sup>
</span>
</td>
<td>string</td>
<td style="width:150px;">Código do usuário</td>
<td></td>
</tr>
</table>
|
Retorno: true, false ou o erro gerado.
DELETE
Sintaxe /users/{userid}
Método utilizado para bloquear um usuário existente. O usuário é bloqueado, e todos os itens amarrados ao seu registro (grupos, vínculo funcional, etc) são desassociados.
| HTML |
|---|
<h2>Parâmetros</h2> <br> <div class="methodsubtabletitle"> <b>pathParam< <b>queryParam</b> </div> <table id="methodsubtable"> <tr> <th width="150px">Nome</th> <th>Tipo</th> <th>Descrição</th> <th>Default</th> </tr> <tr> <td style="width:150px;">userId>foundBy </td> <span style="color:red;">* <td>string</td> <td style="width:150px;">Parâmetro opcional, usado para determinar o tipo de busca do usuário, ID, LOGIN, MAIL, SSO, OAUTH, AD, UID ou LDAP</td> <td>Todos</td> </tr> <tr> <td style="width:150px;">domainId </td> <td>string</td> <td style="width:150px;">Domínio cadastrado para o Usuário, parâmetro obrigatório quando o tipo de busca for AD(Active Directory)</td> </tr> </table> |
Retorno: true, false ou o erro gerado.
DELETE
Sintaxe /users/{userid}
Método utilizado para bloquear um usuário existente. O usuário é bloqueado, e todos os itens amarrados ao seu registro (grupos, vínculo funcional, etc) são desassociados.
| HTML |
|---|
<h2>Parâmetros</h2> <div class="methodsubtabletitle"> <b>pathParam</b> </div> <table id="methodsubtable"> <tr> <th width="150px">Nome</th> <th>Tipo</th> <th>Descrição</th> <th>Default</th> </tr> <tr> <td style="width:150px;">userId <span style="color:red;">* <sup>obrigatório</sup> </span> </td> <td>string</td> <td style="width:150px;">Código do usuário</td> <td></td> </tr> </table> <br> <div class="methodsubtabletitle"> <b>queryParam</b> </div> <table id="methodsubtable"> <tr> <th width="150px">Nome</th> <th>Tipo</th> <th>Descrição</th> <th>Default</th> </tr> <tr> <td style="width:150px;">foundBy </td> <td>string</td> <td style="width:150px;">Parâmetro opcional, usado para determinar o tipo de busca do usuário, ID, LOGIN, <sup>obrigatório</sup>MAIL, SSO, OAUTH, AD, UID ou LDAP</td> <td>Todos</td> </tr> </span><tr> <td style="width:150px;">domainId </td> <td>string</td> <td style="width:150px;">Código>Domínio do usuário</td> <td><cadastrado para o Usuário, parâmetro obrigatório quando o tipo de busca for AD(Active Directory)</td> </tr> </table> |
Retorno: true, false ou o erro gerado.
| Status do documento | Concluído |
|---|---|
| Data | 14/02/2018 |
| Versão | 2.0 |
| Versão anterior | 1.0 |
| Autores |
| Índice | ||||||
|
Visão Geral
Import HTML Content
Conteúdo das Ferramentas
Tarefas