Passo-a-passo: Como se autenticar na API do Credere

Resumindo tudo em um vídeo

Nesse vídeo de pouco mais de 6 minutos a gente implementa um processo de autenticação do início ao fim, além de oferecer um exemplo de como usar o produto desse processo, a Chave de Acesso, pra se comunicar com a API do Credere.

A ideia do vídeo foi ser genérico o suficiente, usando JavaScript, pra que, independente da linguagem que você use, consiga entender os passos necessários. Apesar disso, escrevemos também, mais abaixo nessa documentação, exemplos básicos de um servidor usando Ruby (Sinatra/Faraday) e Python (Flask).

Fazendo login no Credere

Pra iniciar a autenticação na API do Credere, você vai precisar direcionar o seu usuário para a nossa página de login.

Você pode fazer isso redirecionando ele automaticamente ou criando um link HTML, por exemplo. Nesse caso, eu vou fazer isso usando um link HTML:

<a href="">
  Fazer login com o Credere
</a>

Pra montar a URL desse link, alguns parâmetros são necessários:

📘

Você precisa nos informar suas redirect_uris previamente. Você pode ter quantas quiser. Por exemplo, uma pro seu ambiente de testes, uma pro de desenvolvimento e outra para o de produção

Criando um exemplo com os parâmetros linha-a-linha, temos:

https://app.meucredere.com.br/api/v1/authorize
?
response_type=code
&
scope=simulator+proposals
&
client_id=abcdef123
&
redirect_uri=https://exemplo.com/depois-do-login.html

No final, o link pra nossa página de login vai ficar nesse formato:

<a href="https://app.meucredere.com.br/api/v1/authorize?response_type=code&scope=simulator+proposals&client_id=abcdef123&redirect_uri=https://exemplo.com/depois-do-login.html">
  Fazer login com o Credere
</a>

📘

Trazendo esse passo pra algo cotidiano, esse passo de gerar um Código de Autenticação é o mesmo da dado por alguém ao clicar em "Entrar com o Facebook" em algum site. A diferença aqui é que, ao invés de fazer login com o Facebook na sua aplicação, o usuário fará login com o Credere na sua aplicação

Esse link levará o usuário para a página de login do Credere.

Gerando um Código de Autenticação

Depois de fazer login e permitir o acesso da sua aplicação aos dados dele, o usuário será direcionado para o endereço que você informou no redirect_uri, e um parâmetro code será adicionado a esse endereço.

Como exemplo, se você informou: https://exemplo.com/depois-do-login.html
O usuário será redirecionado para: https://exemplo.com/depois-do-login.html?code=abcde123

📘

Utilizando o parâmetro state

Caso você tenha feito uso do parâmetro state no link de geração do código. Exemplo:

https://app.meucredere.com.br/api/v1/authorize
?
response_type=code
&
scope=simulator+proposals
&
client_id=abcdef123
&
redirect_uri=https://exemplo.com/depois-do-login.html
&
state=aHR0cHM6Ly9hcHAubWV1Y3JlZGVyZS5jb20uYnIv

https://app.meucredere.com.br/api/v1/authorize?response_type=code&scope=simulator+proposals&client_id=abcdef123&redirect_uri=https://exemplo.com/depois-do-login.html&state=aHR0cHM6Ly9hcHAubWV1Y3JlZGVyZS5jb20uYnIv

O valor do campo state irá persistir depois do redirecionamento. Exemplo:

https://exemplo.com/depois-do-login.html?code=abcde123&state=aHR0cHM6Ly9hcHAubWV1Y3JlZGVyZS5jb20uYnIv

Esse ?code= retornado na redirect_uri é o Código de Autenticação.

O objetivo desse código é ser usado para gerar uma Chave de Acesso, que será a chave usada pra identificar o usuário em toda e qualquer comunicação entre sua aplicação e a API do Credere.

❗️

Uso único! É importante destacar que o Código de Autenticação tem validade de 5 minutos e só pode ser usado uma vez.

O objetivo dele é criar uma Chave de Acesso. Essa, sim, tem validade maior, de 6 meses, e pode (e vai) ser usada inúmeras vezes pra fazer a comunicação entre a sua aplicação e a API do Credere.

Criando uma Chave de Acesso

Pra gerar uma Chave de Acesso usando o Código de Autenticação que você acabou de gerar, você vai precisar enviar um request (POST) para a nossa API. As informações que precisam ser enviadas são:

{
  code: 'abcde123', // (?code=) gerado no passo anterior
  grant_type: 'authorization_code',
  scopes: 'simulator+proposals',
  redirect_uri: 'https://exemplo.com/depois-do-login.html',
  client_id: 'abcde123',
  client_secret: 'abcde123',
}

Onde:

❗️

Apesar de estarmos expondo o client_secret no nosso exemplo usando JavaScript, indicamos que essa chave esteja guardada no seu backend, e não exposta para o usuário da sua aplicação.

O request para criar uma Chave de Acesso (usando JavaScript, Ruby ou Python) fica assim:

// podemos buscar o ?code= retornado na redirect_uri assim:
const codigoGerado = new URLSearchParams(location.search).get('code');

const informacoesNecessarias = {
  code: codigoGerado,
  grant_type: 'authorization_code',
  scopes: 'simulator+proposals',
  redirect_uri: 'https://exemplo.com/depois-do-login.html',
  client_id: 'abcde123',
  client_secret: 'abcde123',
};

fetch('https://app.meucredere.com.br/api/v1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(informacoesNecessarias),
}).then(chaveGeradaComSuccesso);

async function chaveGeradaComSuccesso(resposta) {
  const json = await resposta.json();

  alert('Chave de acesso gerada com sucesso: ' + json.access_token);
}

require 'sinatra'
require 'faraday'
require 'json'

class Application < Sinatra::Base
  get '/depois-do-login.html' do
    # podemos buscar o ?code= retornado na redirect_uri assim:
    codigo_gerado = params[:code]

    informacoes_necessarias = {
      code: codigo_gerado,
      grant_type: 'authorization_code',
      scopes: 'simulator+proposals',
      redirect_uri: 'https://exemplo.com/depois-do-login.html',
      client_id: 'abcde123',
      client_secret: 'bacde123',
    }

    resposta = Faraday.post(
      'https://app.meucredere.com.br/api/v1/token',
      informacoes_necessarias
    )

    json = JSON.parse(resposta.body, symbolize_names: true)

    return 'Chave de acesso gerada com sucesso: ' + json[:access_token]
  end
end

import requests

from flask import Flask, request
app = Flask(__name__)

@app.route('/depois-do-login.html')
def depois_do_login():
  # podemos buscar o ?code= retornado na redirect_uri assim:
  codigo_gerado = request.args.get('code')

  informacoes_necessarias = {
    'code': codigo_gerado,
    'grant_type': 'authorization_code',
    'scope': 'simulator+proposals',
    'redirect_uri': 'https://exemplo.com/depois-do-login.html',
    'client_id': 'abcde123',
    'client_secret': 'abcd123',
  }

  resposta = requests.post(
    'https://app.meucredere.com.br/api/v1/token',
    data = informacoes_necessarias,
  ).json()

  return 'Chave de acesso gerada com sucesso: ' + resposta['access_token']

if __name__ == '__main__':
  app.run(debug = True, ssl_context = 'adhoc')

📘

Além do json.access_token usado acima, outras informações do usuário (como o nome [user.name], identificador [user.id], etc) são retornadas no JSON da resposta ao gerar uma Chave de Acesso. Consulte a nossa documentação de Usuários para mais informações.

E pronto! Você já pode usar essa Chave de Acesso que você acabou de gerar pra se comunicar com a API do Credere.

Você pode guardar ele no seu banco-de-dados, na sessão do navegador do usuário, ou onde você preferir. Você pode usar ele quantas vezes quiser e ele fica ativo por, no máximo, 6 meses.

Exemplificando o uso da Chave de Acesso

Agora, pra exemplificar como essa comunicação via Chave de Acesso funciona na prática, vamos listar as lojas que um usuário faz parte.

Pra isso, você vai precisar enviar um request (GET) para o nosso endpoint de listagem de lojas. A Chave de Acesso que você gerou precisa ser enviado no cabeçalho (Header) desse request, no seguinte formato:

Authorization = Bearer abcde123

Onde abcde123 seria a Chave de Acesso criada anteriormente.

O request pra listar as lojas de um usuário, usando JavaScript, fica assim:

fetch('https://app.meucredere.com.br/api/v1/stores', {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer abcde123',
  },
}).then(lojasListadasComSucesso);

async function lojasListadasComSucesso(resposta) {
  const json = await resposta.json();

  alert('Lojas do usuário: ' + json.stores.map(store => store.name).join(', '));
}

Resumindo tudo em dois arquivos

O código de exemplo usando JavaScript para se autenticar na API do Credere se resume à:

index.html

<a href="https://app.meucredere.com.br/api/v1/authorize?response_type=code&scope=simulator+proposals&client_id=abcdef123&redirect_uri=https://exemplo.com/depois-do-login.html">
  Fazer login com o Credere
</a>

depois-do-login.html

Bem-vindo de volta!

<script>
  const codigoGerado = new URLSearchParams(location.search).get('code');

  const informacoesNecessarias = {
    code: codigoGerado, // (?code=) gerado após o login
    grant_type: 'authorization_code',
    scopes: 'simulator+proposals',
    redirect_uri: 'https://exemplo.com/depois-do-login.html',
    client_id: 'abcde123',
    client_secret: 'abcde123',
  };

  fetch('https://app.meucredere.com.br/api/v1/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(informacoesNecessarias),
  }).then(chaveGeradaComSuccesso);

  async function chaveGeradaComSuccesso(resposta) {
    if (resposta.status !== 201) {
      return alert('Algo deu errado: ' + resposta);
    }

    const json = await resposta.json();

    alert('Chave de acesso gerada com sucesso: ' + json.access_token);
    alert('Seja bem-vindo, ' + json.user.name + '!');
  }
</script>

Já vale adiantar...

Em endpoints que possuírem o prefixo /banks_api, você também vai precisar adicionar um segundo cabeçalho (Header) nas suas requisições:

Store-Id = 123

Onde 123 seria o ID da sua loja no Credere.

Por exemplo, o request (GET) pra buscar uma simulação com o UUID abc321 feita na loja com o ID 123 ficaria assim:

fetch('https://app.meucredere.com.br/api/v1/banks_api/simulations/abc321', {
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer abcde123',
    'Store-Id': 123,
  },
}).then(simulacaoLidaComSucesso);

async function simulacaoLidaComSucesso(resposta) {
  const json = await resposta.json();

  alert('UUID da simulação encontrada: ' + json.simulation.uuid);
}

Use HTTPS

Destacamos que toda comunicação deve ser feita via HTTPS com um certificado válido.

A publicação de um endereço IP em um domínio não o deixa vulnerável ou aberto ao ambiente da Internet. O firewall é que permite ou bloqueia que outros sistemas ou pessoas tenham acessos ao seu ambiente interno. Então, em termos de risco de invasão, não há nenhum ganho em se utilizar IP ao invés de domínio.
Mas entendemos como um risco de vazamento de dados trafegar essas informações sem que elas estejam devidamente criptografadas através do certificado digital fornecido pelo parceiro através do certificado HTTPS da url fornecida. Sem o HTTPS, toda a informação enviada do Credere para o parceiro pode ser facilmente interceptada enquanto trafega na internet. A exigência de um domínio com HTTPS vem para mitigar esse risco.