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

title	Atenção

Via REST apenas é possível a criação básica do usuário. Para configurar permissões, acessos, menus, etc, é necessária a utilização do Identity.

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

<!DOCTYPE html>
<html>


<head>
    <meta charset="UTF-8" />
    <title>Document</title>
</head>

<body>
    <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>


    </table>
</body>

</html>

Nota

title	Atenção

O parâmetro atributes é case sensitive.

Retorno:

HTML

<!DOCTYPE html>
<html>


<head>
    <meta charset="UTF-8" />
    <title>Document</title>
</head>

<body>
    <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>
</body>

</html>

Bloco de código

language	js
theme	Eclipse
title	Exemplo do json de retorno

{
    "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

language	js
theme	Eclipse
title	Exemplo de retorno do método

{
    "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



<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Document</title>
</head>


<body>
    <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>



    </table>
</body>

</html>

Exemplo de requisição para a inclusão de usuário:

Bloco de código

language	js
theme	Eclipse
title	Exemplo de requisição

{ 
   "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

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8" />
    <title>Document</title>
</head>

<body>
    <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>

</body>

</html>

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

<!DOCTYPE html>
<html>


<head>
    <meta charset="UTF-8" />
    <title>Document</title>
</head>

<body>
    <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>

</body>

</html>

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	Jandir Deodato De Souza Silva, Danilo Basilio Medeiros

Índice

outline	true
indent	10px

Como criar usuários do Protheus através de Webservice

...

Produto:

...

Microsiga Protheus

...

Versões:

...

11 e 12

...

Passo a passo:

O Protheus permite a criação de usuários através de Webservices REST. Para tanto, deve-se configurar o serviço REST no arquivo appserver.ini do Protheus.

Para que seja possível incluir um novo cadastro, é necessário que o usuário enviado no header da requisição REST possua permissão de acesso a rotina CFGA510.

Segue abaixo um exemplo de configuração no arquivo appserver.ini. Para maiores detalhes sobre a configuração do WebService REST no Protheus, acesse:
http://tdn.totvs.com/display/tec/REST

Bloco de código

[HTTP] 
ENABLE=1 
PORT=8079
PATH=C:\TOTVS 12\Microsiga\help-online
Environment=P12
[ONSTART]
JOBS=HTTPJOB
REFRESHRATE=120

[HTTPJOB]
MAIN=HTTP_START
ENVIRONMENT=P12

[HTTPV11]
Enable=1
Sockets=HTTPREST

[HTTPREST] 
Port=8088
IPsBind=
URIs=HTTPURI
Security=0

[HTTPURI]
URL=/rest
PrepareIn=01
Instances=1,1

...

Bloco de código

language	js

{
  "schemas": [
    "urn:scim:schemas:core:2.0:User",
    "urn:scim:schemas:extension:enterprise:2.0:User"
  ],
  "meta": {
  },
  "userName": "usuario1",
  "displayName": "Usuario Um",
  "emails": [
    {
      "value": "[email protected]",
      "primary": true
    }
  ],
  "active": true,
  "groups": [{"value":"000002"}],
  "password": "usuario1",
  "ext/sAMAccountName":"usuario1",
  "ext/adDomain":"XP01",
  "urn:scim:schemas:extension:enterprise:2.0:User":{
	"manager":[
	{
		"managerid":"000000"
		
	}
	]  
  }
}

Descrição das chaves do JSON:

• userName – Nome do usuário (usuário);
• displayName – Nome completo do usuário (Nome completo);
• e-mails – Array de objetos. 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);
- value – valor do email
- primary – Se é um email que será cadastrado
• active - Indica se o usuário estará bloqueado ou não (true);
• groups – Array de objetos contendo os códigos dos grupos de usuário ao qual o usuário está ligado;
• password – Senha do usuário. Se não informada, é gerada uma senha que deverá ser alterada posteriormente pelo admin do sistema;
• ext/SAMAccountName – Indica o login do usuário no SSO (caso informado, ele substituirá o valor informado no campo userName);
• ext/adDomain – Domínio do usuário no SSO;
• urn:scim:schemas:extension:enterprise:2.0:User – Objeto que vai indicar o superior do usuário, sendo:
- manager – Array de objetos contendo os superiores do usuário:
• managerid – Código do superior do usuário

...

Image Removed

Ao efetuar o envio do JSON (Send), será exibido no Console do Protheus uma informação de confirmação como esta:

Image Removed

...

Observações:

...

Páginas filhas

Versões comparadas

Versão antiga 5

Nova versão 6

Chave

Rest users

Métodos disponíveis

GET

GET (GetUserId)

POST

PUT

DELETE

Como criar usuários do Protheus através de Webservice

Páginas filhas

Histórico da Página

Versões comparadas

Versão antiga 5

Nova versão 6

Chave

Rest users

Métodos disponíveis

GET

GET (GetUserId)

POST

PUT

DELETE

Como criar usuários do Protheus através de Webservice