Este guia tem como objetivo auxiliar desenvolvedores no processo de integração da sua aplicação com o Portal de Serviços, provendo acesso aos dados de usuários do Portal, bem como derivados desses dados, como informações de conta.
O guia foi elaborado para a versão 2.0 da API de serviços do Portal. Caso deseje acessar o guia da API 1.0, clique aqui.
Premissas
Para o sucesso do processo de integração, este guia partirá das seguintes premissas:
A versão do Java utilizada (no projeto a ser integrado) deve ser uma variante da versão 1.7 ou superior.
A API do Portal utiliza a versão 1.5.2.2 da biblioteca BRyX509. Esteja atento para possíveis conflitos de versão.
A aplicação deve estar devidamente cadastrada no Portal. Se a sua aplicação ainda não foi cadastrada, siga os passos descritos em: Cadastrando uma Aplicação
Você deve possuir um Token que identifique sua aplicação (o Token é obtido após o cadastro).
Cadastrando uma Aplicação
Para cadastrar sua aplicação no Portal:
Autentique-se no portal como Pessoa Jurídica.
No menu de conta, selecione a opção "Minhas Aplicações".
Forneça os dados da sua aplicação, e clique em 'inserir'.
Pronto! Sua aplicação está cadastrada e pode integrar-se ao de Serviços.
Para isso, você deve emitir um Token que dará acesso à API de integração. Faça isso selecionando a sua Aplicação e clicando em "Emitir Token". Este token pode ser revogado a Qualquer momento.
Fique atento: o cadastro da sua aplicação poderá falhar nos casos de uma chave que já esteja sendo utilizada por outra aplicação.
A API do Portal provê um conjunto de Web Services REST para que você, parceiro do Portal, tenha acesso aos serviços disponibilizados e acesso ao gerenciamento de identidade do Portal de Serviços.
Preparando o Cliente
Para instanciar o cliente da API de Web Services do Portal o procedimento é simples. Instancie um novo cliente, como demonstrado no trecho abaixo:
//...
ConfiguracaoCliente configuracao = new ConfiguracaoClientePadrao("https://[host]/", "[tokenDaSuaAplicacao]");
ClienteParceiroPortal cliente = new ClienteParceiroPortalPadrao(configuracao);
//...
A partir disso, as chamadas subsequentes serão realizadas com a configuração fornecida.
ATENÇÃO: Para a versão antiga da API do Portal, que exige certificado
SSL de cliente para comunicação, consulte a documentação
da API antiga, que explica os passos configurar seu certificado de cliente.
Solicitando uma URL de Autorização
Para que um usuário autorize a Aplicação a realizar requisições em seu nome, a Aplicação deve solicitar uma URL de Autorização, ao Portal, e exibir esta URL no navegador, para que o Usuário se identifique. Além da URL, este serviço retorna um identificador de contexto de autorização, que servirá para a obtenção do token.
ATENÇÃO: O prazo para concluir o processo de autenticação é de 60 minutos, por padrão (podendo ser alterado por um administrador). Se o prazo de autorização é importante para o seu procedimento, consulte um administrador para mais informações.
Página que deve ser exibida, após a autenticação do usuário:
Há algumas exceções que podem ser lançadas nas chamadas:
caso algum parâmetro obrigatório não tenha sido preenchido.
quando há algum erro no processamento por parte do servidor. Para maiores detalhes das circunstâncias
que ocasionaram o problema de processamento, um objeto com.sun.jersey.api.client.ClientResponse é disponibilizado dentro da exceção (por exemplo, se você
deseja saber qual o status HTTP da requisição gerada pela chamada).
quando a chamada não foi autorizada pelo servidor. Sempre está relacionado a um Status HTTP 403.
As situações mais comuns são:
O certificado utilizado na requisição é inválido (não faz parte da cadeia da BRy / está vencido / foi revogado)
O Token fornecido na chamada é inválido (não existe / foi revogado / está vencido)
A aplicação ou o usuário identificado pelo Token utilizado não possuem privilégios para realizar a chamada.
quando a chamada não foi autorizada pelo servidor devido ao uso de um token expirado.
Neste caso, um token de renovação de autorização é emitido e armazenado em PortalTokenExpiradoException.getTokenRenovacao().
Esta exceção não ocorre nos casos em que o token não é informado. Mais detalhes da renovação de Token serão abordados posteriormente.
Recuperando o Token de Autorização
Em posse do Identificador de Contexto de Autorização obtido no serviço de Solicitar URL de Autorização, o serviço de Recuperar Token deve ser chamado, de forma assíncrona, para se obter o Token de autorização do usuário.
Fica a critério da aplicação a periodicidade com que este serviço será chamado, visto que o Usuário possui até o fim do dia para autorizar a Aplicação, momento em que o contexto de autorização expira (é descartado).
Em poucas palavras, este serviço só retornará um Token de Autorização se o Usuário autenticou-se com sucesso no Portal e autorizou a Aplicação.
//...
// objeto identificadorContextoAutorizacao foi obtido na seção anterior
RespostaPortalVO<StatusAutorizacaoPortalVO> respostaAutorizacao = cliente.getServicosAutorizacao().recuperarTokenDeAutorizacao(identificadorContextoAutorizacao);
//O token de autorização ficará armazenado na seguinte propriedade:
String token = respostaAutorizacao.getEntidades().get(0).getToken();
//...
Um Token expirou! O que fazer?
Todo Token possui um prazo de validade limitado. Após o fim do prazo, a primeira chamada de serviço realizada após o
vencimento gerará uma exceção: br.com.bry.portal.api.excecoes.PortalTokenExpiradoException.
Quando isso acontecer, um Token de Renovação será gerado e estará acessível em br.com.bry.portal.api.excecoes.PortalTokenExpiradoException.getTokenRenovacao().
O Token de Renovação deve ser utilizado, uma única vez, para que um novo Token seja gerado para o usuário, sem que seja necessária uma nova prova de credenciais:
//...
try {
cliente.getServicosUsuario().recuperarUsuarioPorCPFouCNPJ("00000000000");
} catch (PortalTokenExpiradoException e) {
String tokenRenovacao = e.getTokenRenovacao();
RespostaPortalVO<StatusAutorizacaoPortalVO> respostaRenovacaoToken = cliente.getServicosAutorizacao().renovarToken(tokenRenovacao);
String tokenRenovado = respostaRenovacaoToken.getEntidades().get(0).getToken();
// ... Tratamento para atualização do valor do Token ...
}
//...
A partir desse ponto, fica disponibilizado o novo Token, identificando o mesmo usuário e sem que seja necessária uma nova prova de credenciais.
Os Tokens de renovação possuem uma validade mais curta e são descartados assim que vencem, ou assim que são utilizados na renovação (para impedir
o uso repetido).
Serviços Disponíveis
Abaixo, uma relação dos serviços disponibilizados pela API, com uma breve descrição, junto de um link para o Javadoc:
Serviço
Descrição
Links
Solicitar URL de Autorização
Recupera uma URL que deve ser exibida no navegador Web, para que o usuário autentique-se e autorize a Aplicação a realizar requisições em seu nome. ATENÇÃO: O prazo para concluir o processo de autenticação é de 60 minutos, por padrão (podendo ser alterado por um administrador). Se o prazo de autorização é importante para o seu procedimento, consulte um administrador para mais informações.
Checa o status do processo de autorização de um usuário, retornando um Token de autorização, caso o Usuário tenha autorizado a Aplicação. Este serviço serve
para verificar, de forma assíncrona, se todos os passos, após a chamada do serviço anterior (Solicitar URL de Autorização), foram executados com sucesso pelo Usuário
que está sendo autorizado.
