O que é?

O End-Point tem por objetivo fornecer serviços referente à entidade Usuário do serviço de autenticação da API da Assembleia Legislativa do Estado de Mato Grosso.

Como faço para me autenticar?

Para se autenticar no end-point você deverá informar as credenciais (fornecidas pela instituição) para a obtenção de um token de acesso, que deverá ser informado no cabeçalho das requisições deste serviço.

Para obter o token de acesso, utilizando o grant_type denominado password você precisa realizar uma requisição semelhante à esta: 

curl -X POST
/oauth/v2/token
-H 'cache-control: no-cache'
-H 'content-type: application/x-www-form-urlencoded'
-d 'grant_type=password&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]'
POST /oauth/v2/token HTTP/1.1
Host: api.al.mt.gov.br
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=password&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.al.mt.gov.br/oauth/v2/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "grant_type=password&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]",
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: application/x-www-form-urlencoded",
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new RestClient("https://api.al.mt.gov.br/oauth/v2/token");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=password&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Para obter o token de acesso, utilizando o grant_type denominado http://al.mt.gov.br/grants/password_and_totp você precisa realizar uma requisição semelhante à esta: 

curl -X POST
/oauth/v2/token
-H 'cache-control: no-cache'
-H 'content-type: application/x-www-form-urlencoded'
-d 'grant_type=http://al.mt.gov.br/grants/password_and_totp&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]'
POST /oauth/v2/token HTTP/1.1
Host: api.al.mt.gov.br
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=http://al.mt.gov.br/grants/password_and_totp&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.al.mt.gov.br/oauth/v2/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "grant_type=http://al.mt.gov.br/grants/password_and_totp&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]",
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: application/x-www-form-urlencoded",
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new RestClient("https://api.al.mt.gov.br/oauth/v2/token");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=http://al.mt.gov.br/grants/password_and_totp&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Para a geração do totp_pin o autenticador deverá respeitar as seguintes características:

  • Algoritmo SHA-1 Digest
  • PIN atualizado a cada 30 segundos
  • PIN de 6 dígitos
  • RFC 6238

Recomendamos a ferramenta Google Authenticator para a geração do PIN.

Para obter o token de acesso, utilizando o grant_type denominado http://al.mt.gov.br/grants/password_and_totp_and_uuid você precisa realizar uma requisição semelhante à esta: 

curl -X POST
/oauth/v2/token
-H 'cache-control: no-cache'
-H 'content-type: application/x-www-form-urlencoded'
-d 'grant_type=http://al.mt.gov.br/grants/password_and_totp_and_uuid&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]&uuid=[uuid]'
POST /oauth/v2/token HTTP/1.1
Host: api.al.mt.gov.br
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache

grant_type=http://al.mt.gov.br/grants/password_and_totp_and_uuid&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]&uuid=[uuid]
$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://api.al.mt.gov.br/oauth/v2/token",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "grant_type=http://al.mt.gov.br/grants/password_and_totp_and_uuid&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]&uuid=[uuid]",
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: application/x-www-form-urlencoded",
),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
var client = new RestClient("https://api.al.mt.gov.br/oauth/v2/token");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=http://al.mt.gov.br/grants/password_and_totp_and_uuid&client_id=[client_id]&client_secret=[client_secret]&username=[username]&password=[password]&totp_pin=[totp_pin]&uuid=[uuid]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Para a geração do uuid você deverá respeitar as seguintes características:

Observação: As validações acima foram derrubadas, buscando compatibilidade com o UDID.

O token de acesso será retornado em uma resposta semelhante à esta: 

{
    "access_token": "OTlkMjZmMWM4NDljYzA5NzYxNDA3MTg4NGQxNWFlNWYxZjJkMjA3MDFkYzZhMTRiMjE1ZjRlNzBmMDEwMjg4Nw",
    "expires_in": 3600,
    "token_type": "bearer",
    "scope": null,
    "refresh_token": "ZThkOGNhZWVlOGIyNTJjYzg1MjQwZGQzNjFhOWIxYmFjZjE4MDM3MDhmNzgxZTZhN2U5ZDM5Yjk5ZTVkMWM1ZQ"
}

O atributo expires_in representa o tempo em segundos de validade do access_token .

Para utilizar o end-point você deverá adicionar um cabeçalho semelhante a este: 

Authorization: [token_type (a primeira letra deve ser maíuscula)] [access_token]

Quais são os end-points que posso acessar?

Observação: As chamadas devem ser síncronas, as chamadas assíncronas serão rejeitadas pelo servidor, por motivos de segurança.

Como faço para pesquisar nas várias entidades?

Para que seja possível pesquisar dentro das requisições permitidas é necessário informar o parâmetro criterias em formato text/json através desta especificação.

O parâmetro criterias é um vetor escalar, isto implica dizer que será possível informar mais de um critério de pesquisa, os quais serão encadeados com o operador aditivo AND.

Sintaxe

Quando o campo operator for igual a is-null not-is-null : 

criterias=[{"field": "[field]", "operator": "[operator]"}]

Quando o campo operator for igual a equals not-equals contains not-contains start-with not-starts-with end-with not-ends-with greater-than greater-than-or-equals lower-than lower-than-or-equals : 

criterias=[{"field": "[field]", "operator": "[operator]", "parameter": {"type": "[parameter_type]", "value": "[parameter_value]"}}]

Quando o campo operator for igual a range not-in-range : 

criterias=[{"field": "[field]", "operator": "[operator]", "parameters": {"one": {"type": "[parameter_one_type]", "value": "[parameter_one_value]"}, "two": {"type": "[parameter_two_type]", "value": "[parameter_two_value]"}}}]

O que posso informar no campo field?

O que posso informar nos campos parameter_type, parameter_one_type e parameter_two_type?

string integer float date time datetime

Como devo informar os campos parameter_value, parameter_one_value e parameter_two_value?

Quando o tipo for string o formato deverá ser: "abc".

Quando o tipo for integer o formato deverá ser: 123.

Quando o tipo for float o formato deverá ser: 123.45.

Quando o tipo for date o formato deverá ser: "2017-12-31".

Quando o tipo for time o formato deverá ser: "23:59:59".

Quando o tipo for datetime o formato deverá ser: "2017-12-31 23:59:59".

A aplicação irá realizar testes de integridade sobre os filtros requisitados, podendo gerar exceções pelos mais variados motivos.

O que faço se não precisar de todo o conteúdo da resposta?

Caso não seja necessário todo o conteúdo de resposta é possível reduzir a estrutura de retorno através do parâmetro intersection em formato text/json através desta especificação.

O parâmetro intersection é um vetor de chave e valor multidimensional, que representa a estrutura de vetor que se deseja obter com a resposta.

Sintaxe

Você precisará criar uma representação de vetor semelhante ao resultado esperado para que seja possível interseccionar o vetor de resposta. 

intersection={"[field]": {"[field]": null, "[field]": {"[field]": null, "[field]": null}}}

A mesma intersecção acima apresentada pode ser obtida da forma abaixo: 

intersection={"[field]": {"[field]": null, "[field]": ["[field]", "[field]"]}}

Como faço para paginar as várias entidades?

Para que seja possível paginar dentro das requisições permitidas é necessário informar o parâmetro pagination em formato text/json através desta especificação.

O parâmetro pagination é um vetor de chave e valor, isto implica dizer que não será possível informar mais de um critério de paginação, isto implica em dizer que apenas uma página será retornada por requisição.

Sintaxe

pagination={"response": [response], "count": [count], "page": [page], "sort": {"[field]": "[asc|desc]", "[field]": "[asc|desc]" [...]}}

O que posso informar no campo response?

O parâmetro response é opcional e é utilizado para trazer informações extras no paginador, como a quantidade máxima de itens daquela consulta e se existe página anterior e próxima, por padrão será verdadeiro.

Caso o parâmetro response esteja preenchido com o valor false ele ocultará da resposta os elementos: pagination.response.total, pagination.response.has_previous_page e pagination.response.has_next_page.

O parâmetro response espera um boolean.

O que posso informar no campo count?

O parâmetro count é opcional e é utilizado para limitar a quantidade de resultados da consulta, por padrão será 20 (vinte) entidades.

O parâmetro count espera um número inteiro, positivo e diferente de zero.

O que posso informar no campo page?

O parâmetro page é opcional e é utilizado para iniciar a consulta (conceito de offset), por padrão será 1 (um).

O parâmetro page espera um número inteiro, positivo e diferente de zero.

O que posso informar no campo sort?

O parâmetro sort é opcional e é utilizado para ordenar a consulta, por padrão será vazio.

O parâmetro sort espera um vetor de chave e valor, contendo os parâmetros: field (campo a ser ordenado) e um dos operadores asc (para ordenar do menor para o maior) ou desc (para ordenar do maior para o menor).

O parâmetro field espera uma string e diferente de vazio.

A aplicação irá realizar testes de integridade sobre a paginação requisitada, podendo gerar exceções pelos mais variados motivos.

Como devo esperar a(s) resposta(s)?

Para o end-point /api/v1/usuario/alterar-senha

{
    "id": null,
    "username": null,
    "email": null
}

A estrutura de retorno pode ser modificada de acordo com a estrutura do registro a ser entregue, podendo, então, ocasionar modificações na estrutura de exemplo acima apresentada.

Como devo alterar a senha do usuário?

A ação de alterar senha do usuário ocorrerá quando o end-point /api/v1/usuario/alterar-senha for chamado.

Esta ação irá alterar a senha do usuário logado.

A requisição deve atender a 2 (dois) requisitos, ser do 'tipo' PUT e enviar como parâmetro new_password contento a nova senha.

Entende-se que neste momento já foi gerado o tokem de acesso, e este dever ser referenciado em todas as requisições, conformer sessão Como faço para me autenticar?.

Alguns exemplos de como fazer a requisição. 

Curl -X PUT \
/api/v1/usuario/alterar-senha
\ -H 'Authorization: Bearer
[tokem de acesso]' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Cache-Control: no-cache' \

-d new_password=suanovasenha

PUT
/api/v1/usuario/alterar-senha
HTTP/1.1 Host: api-dev.al.mt.gov.br Content-Type: application/x-www-form-urlencoded Authorization: Bearer
[tokem de acesso]
Cache-Control: no-cache

new_password=suanovasenha

Considere uma ação de alterar senha realizada com sucesso quanto a response da requisição tiver o status code 200, acompanhado do objeto Usuário, conforme estrutura padrão. 

    
{
    "id": null,
    "username": null,
    "email": null
}

A estrutura de retorno pode ser modificada de acordo com a estrutura do registro a ser entregue, podendo, então, ocasionar modificações na estrutura de exemplo acima apresentada.