O que é?

O End-Point tem por objetivo fornecer serviços referente à entidade Cadastro Político do serviço da SSL do portal 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?

cadastroPolitico.id cadastroPolitico.status cadastroPolitico.biografia cadastroPolitico.fotografia cadastroPolitico.fotoGaleriaPresidente pessoaFisica.id pessoaFisica.nome pessoaFisica.cpf pessoaFisica.dataNascimento pessoaFisica.sexo cidadeNascimento.id cidadeNascimento.codigoIbge cidadeNascimento.descricao uf.id uf.codigoIbge uf.descricao uf.sigla mandato.id mandato.nome mandato.condicao mandato.inicio mandato.fim mandato.diploma mandato.votos mandatoLegislatura.id mandatoLegislatura.numero mandatoLegislatura.inicio mandatoLegislatura.fim mandatoLegislatura.eleicao mandatoLegislatura.mesaDiretora coligacao.id coligacao.nome coligacao.votos cadastroPolitico.site cadastroPolitico.facebook cadastroPolitico.twitter cadastroPolitico.google cadastroPolitico.linkedin cadastroPolitico.youtube cadastroPolitico.flickr cadastroPolitico.instagram filiacoesPartidaria.id filiacoesPartidaria.inicio filiacoesPartidaria.fim partido.id partido.sigla partido.nome partido.numero contato.id contato.tipo contato.valor contato.observacao licencaParlamentar.id licencaParlamentar.diarioOficial licencaParlamentar.motivo licencaParlamentar.observacao licencaParlamentar.numeroApresentacao licencaParlamentar.numeroConcessao sessaoPlenariaApresentacao.id sessaoPlenariaApresentacao.tipo sessaoPlenariaApresentacao.numero sessaoPlenariaApresentacao.inicio sessaoPlenariaApresentacao.fim sessaoPlenariaApresentacao.ata sessaoPlenariaApresentacao.sumula sessaoLegislativaApresentacao.id sessaoLegislativaApresentacao.tipo sessaoLegislativaApresentacao.numero sessaoLegislativaApresentacaoPeriodo.id sessaoLegislativaApresentacaoPeriodo.inicio sessaoLegislativaApresentacaoPeriodo.fim sessaoLegislativaApresentacaoPeriodo.prorrogacao legislaturaApresentacao.id legislaturaApresentacao.numero legislaturaApresentacao.inicio legislaturaApresentacao.fim legislaturaApresentacao.eleicao legislaturaApresentacao.mesaDiretora licencaParlamentarPeriodo.id licencaParlamentarPeriodo.inicio licencaParlamentarPeriodo.fim licencaParlamentarPeriodo.prorrogacao sessaoPlenariaConcessao.id sessaoPlenariaConcessao.tipo sessaoPlenariaConcessao.numero sessaoPlenariaConcessao.inicio sessaoPlenariaConcessao.fim sessaoPlenariaConcessao.ata sessaoPlenariaConcessao.sumula sessaoLegislativaConcessao.id sessaoLegislativaConcessao.tipo sessaoLegislativaConcessao.numero sessaoLegislativaConcessaoPeriodo.id sessaoLegislativaConcessaoPeriodo.inicio sessaoLegislativaConcessaoPeriodo.fim sessaoLegislativaConcessaoPeriodo.prorrogacao legislaturaConcessao.id legislaturaConcessao.numero legislaturaConcessao.inicio legislaturaConcessao.fim legislaturaConcessao.eleicao membroMesaDiretora.id membroMesaDiretora.cargo mesaDiretora.id mesaDiretora.situacao mesaDiretora.eleicao mesaDiretora.observacao sessaoLegislativaMesaDiretora.id sessaoLegislativaMesaDiretora.tipo sessaoLegislativaMesaDiretora.numero sessaoLegislativaMesaDiretoraPeriodo.id sessaoLegislativaMesaDiretoraPeriodo.inicio sessaoLegislativaMesaDiretoraPeriodo.fim sessaoLegislativaMesaDiretoraPeriodo.prorrogacao legislaturaMesaDiretora.id legislaturaMesaDiretora.numero legislaturaMesaDiretora.inicio legislaturaMesaDiretora.fim legislaturaMesaDiretora.eleicao

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/ssl/parlamentar/

{
    "pagination": {
        "request": {
            "page": 1,
            "count": 3
        },
        "response": {
            "page": 1,
            "count": 3,
            "total": 145,
            "has_previous_page": false,
            "has_next_page": true
        }
    },
    "entities": [
        {
            "pessoa_fisica": {
                "cidade_nascimento": {
                    "uf": []
                }
            },
            "mandatos": [],
            "midias_sociais": {
                "site": "",
                "facebook": "",
                "twitter": "",
                "google": "",
                "linkedin": "",
                "youtube": "",
                "flickr": "",
                "instagram": ""
            },
            "filiacoes": [],
            "contatos": [],
            "licencas_parlamentares": [],
            "membro_mesas_diretoras": [],
            "id": "",
            "status": "",
            "biografia": "",
            "fotografia": "",
            "fotografia_presidente": ""
        },
        {
            "pessoa_fisica": {
                "cidade_nascimento": {
                    "uf": []
                }
            },
            "mandatos": [],
            "midias_sociais": {
                "site": "",
                "facebook": "",
                "twitter": "",
                "google": "",
                "linkedin": "",
                "youtube": "",
                "flickr": "",
                "instagram": ""
            },
            "filiacoes": [],
            "contatos": [],
            "licencas_parlamentares": [],
            "membro_mesas_diretoras": [],
            "id": "",
            "status": "",
            "biografia": "",
            "fotografia": "",
            "fotografia_presidente": ""
        },
        {
            "pessoa_fisica": {
                "cidade_nascimento": {
                    "uf": []
                }
            },
            "mandatos": [],
            "midias_sociais": {
                "site": "",
                "facebook": "",
                "twitter": "",
                "google": "",
                "linkedin": "",
                "youtube": "",
                "flickr": "",
                "instagram": ""
            },
            "filiacoes": [],
            "contatos": [],
            "licencas_parlamentares": [],
            "membro_mesas_diretoras": [],
            "id": "",
            "status": "",
            "biografia": "",
            "fotografia": "",
            "fotografia_presidente": ""
        }
    ]
}

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.

Para o end-point /api/v1/ssl/parlamentar/1

{
    "pessoa_fisica": {
        "cidade_nascimento": {
            "uf": []
        }
    },
    "mandatos": [],
    "midias_sociais": {
        "site": "",
        "facebook": "",
        "twitter": "",
        "google": "",
        "linkedin": "",
        "youtube": "",
        "flickr": "",
        "instagram": ""
    },
    "filiacoes": [],
    "contatos": [],
    "licencas_parlamentares": [],
    "membro_mesas_diretoras": [],
    "id": "",
    "status": "",
    "biografia": "",
    "fotografia": "",
    "fotografia_presidente": ""
}

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.