Artigos nessa seção

  1. Betalabs
  2. APIs
  3. API para o e-commerce

Avatar
Alef Corquiola

O plugin Canopus disponibiliza uma série de facilidades para auxiliar nas implementações das lojas. Entre essas facilidades está o modal de identificação padrão que contém uma série de funcionalidades implementadas para o fluxo de cadastro de novos clientes. Entre as funcionalidades está: login via e-mail e senha, login via Facebook, login via Google, verificação de existência de e-mail, cadastro de clientes pessoas física e jurídica, entre outros.

Em alguns cases, algumas demandas podem fazer com que seja necessário sobrescrever algumas dessas funcionalidades.

Cadastrando novos clientes

[POST] /ecommerce/identification

Campos disponíveis:

{
    'legal_personality': 0,
    'name1': 'Nome',
    'name2': 'Sobrenome',
    'document1': '99061578957',
    'document2': '278657461'
    'date_of_birth': '1994-11-07',
    'gender': 'm',
    'email': 'foo@bar.com',
    'password': '123456',
    'telephone': {
        'ddd': '11',
        'number': '985335155'
    }
}

Onde:

  • legal_personality número inteiro obrigatório e deve ser 0 para pessoa física ou 1 para pessoa jurídica.
  • name1 texto obrigatório e com mais de 3 caracteres.
  • name2 texto que pode ser omitido e se informado deve ter mais de 3 caracteres.
  • document1 texto validado no formato de CPF ou CNPJ e único - não deve ter outro cliente com este documento.
  • document2 texto que pode ser omitido.
  • date_of_birth texto que pode ser omitido e se informado deve obedecer o formato de data "Y-m-d" e deve ser menor que hoje.
  • gender texto que pode ser omitido e se informado deve ter 1 caractere e deve ser 'm' para masculino ou 'f' para feminino.
  • email texto obrigatório no formato de e-mail válido.
  • password texto obrigatório de 6 a 50 caracteres.
  • telephone.ddd número que pode ser omitido mas se informado deve ser um DDD válido considerando o número de telefone.
  • telephone.number número que pode ser omitido mas se informado deve ser um número de telefone válido considerando o DDD.

Prevenindo duplicações

Antes de enviar a requisição de criação de clientes é interessante para a experiência do usuário verificar a existência dos dados preenchidos no formulário. Para isso:

[GET] ecommerce/identification/exists/{type}

Onde:

  • {type} é o tipo da informação a ser verificada e pode ser 'email' ou 'document1'

E o corpo da requisição deve ser:

{
    'value': 'foo@bar.com'
}

Onde:

  • value deve ser um valor correspondente ao tipo de informação a ser verificada (e-mail ou documento do tipo CPF/CNPJ).

Obtendo token de autenticação

Para realizar o login no ecommerce, o usuário deverá solicitar um token à API junto de seu login e senha e, assim que autenticado, este token deverá ser utilizado em toda rota que requer autenticação. Para obtenção do token, utilizar a seguinte rota:

[POST] ecommerce/identification/authenticated-user

E o corpo da requisição deve ser:

{
    'username': 'foo@bar.com',
    'password': '******',
    'grant_type': 'password',
    'scope': '*',
    'client_id': '',
    'client_secret': ''
}

Onde:

  • username deve ser o e-mail do cliente
  • password deve ser a senha do cliente
  • grant_type tipo da autenticação a ser feita, nesse caso usar como o valor 'password'
  • scope escopos de acesso a serem requisitados, nesse caso usar como o valor '*'
  • client_id id da aplicação que está requerendo a autenticação, nesse caso a aplicação a ser desenvolvida como alternativa ao canopus. Solicitar este valor para a equipe de atendimento da Betalabs
  • client_secret código da aplicação que está requerendo a autenticação, nesse caso a aplicação a ser desenvolvida como alternativa ao canopus. Solicitar este valor para a equipe de atendimento da Betalabs

O corpo da resposta virá no seguinte formato:

{'access_token': <<ACCESS TOKEN>>}

Persistindo o token na sessão do usuário

Após a obtenção do token, o mesmo deverá ser persistido na sessão. Para isso, utilizar a seguinte rota:

[POST] ecommerce/identification/persist-login

O corpo poderá ser vazio e o token obtido deverá ser informado como valor do cabeçalho Authorization na requisição junto com o prefixo Bearer.

Removendo token persistido da sessão do usuário

Para esquecer o token da sessão do usuário, utilizar a seguinte rota:

[POST] ecommerce/identification/forget-login

O corpo poderá ser vazio e o token deverá ser informado como valor do cabeçalho Authorization na requisição junto com o prefixo Bearer.

Consultando token persistido na sessão do usuário

Para obter o token persistido na sessão do usuário, caso o mesmo não esteja armazenado na sua aplicação, o processo é semelhante ao de login porém altera-se a forma de concessão do token. Utilizar a seguinte rota:

[POST] ecommerce/identification/authenticated-user

E o corpo da requisição deve ser:

{
    'grant_type': 'persisted',
    'scope': '*',
    'client_id': '',
    'client_secret': ''
}

Onde:

  • grant_type tipo da autenticação a ser feita, nesse caso usar como o valor 'persisted'
  • scope escopos de acesso a serem requisitados, nesse caso usar como o valor '*'
  • client_id id da aplicação que está requerendo a autenticação, nesse caso a aplicação a ser desenvolvida como alternativa ao canopus. Solicitar este valor para a equipe de atendimento da Betalabs
  • client_secret código da aplicação que está requerendo a autenticação, nesse caso a aplicação a ser desenvolvida como alternativa ao canopus. Solicitar este valor para a equipe de atendimento da Betalabs

O corpo da resposta virá no seguinte formato, caso exista um cliente autenticado na sessão:

{'access_token': <<ACCESS TOKEN>>}

Caso não exista um cliente na sessão, a requisição retornará como erro de autenticação e o status 401.

Recuperando a senha

Para recuperar a senha dos clientes, uma solicitação deve ser registrada e então um código será enviado para o e-mail informado. Com esse código uma nova senha poderá ser definida. Para solicitar o código de recuperação, utilizar a seguinte rota:

[POST] ecommerce/identification/password-recovery/token

E o corpo da requisição deverá ser:

{
    'email': 'foo@bar.com',
    'type': ''
}

Onde:

  • email é o e-mail do cliente que deseja receber o token
  • type é o tipo do token que o usuário deseja receber, podendo ser 1 para criar uma nova senha ou 2 para entrar com um código temporário.

Após o disparo do token para o email solicitado, o cliente poderá:

Criar uma nova senha

Para isso, a seguinte rota poderá ser utilizada:

[POST] ecommerce/identification/password-recovery

E o corpo da requisição deverá ser:

{
    'password': '',
    'token': ''
}

Onde:

  • password é a senha nova a ser definida
  • token é o token recebido por no e-mail no passo anterior e que servirá para identificar o cliente a ter a senha alterada.

Entrar com código temporário

O processo de login com código temporário funciona de forma semelhante à autenticação com senha, porém alguns parâmetros serão alterados. O endpoint é o mesmo e o corpo deverá ser:

{
    'access_token': '******',
    'grant_type': 'password_recovery_token',
    'scope': '*',
    'client_id': '',
    'client_secret': ''
}

Onde:

  • access_token deve ser o token recebido pelo cliente por e-mail
  • grant_type tipo da autenticação a ser feita, nesse caso usar como o valor 'password_recovery_token'
  • scope escopos de acesso a serem requisitados, nesse caso usar como o valor '*'
  • client_id id da aplicação que está requerendo a autenticação, nesse caso a aplicação a ser desenvolvida como alternativa ao canopus. Solicitar este valor para a equipe de atendimento da Betalabs
  • client_secret código da aplicação que está requerendo a autenticação, nesse caso a aplicação a ser desenvolvida como alternativa ao canopus. Solicitar este valor para a equipe de atendimento da Betalabs.

Alterando a senha atual

Para alterar a senha atual do cliente sem a necessidade dos passos de recuperação, basta adicionar uma senha nova ao cliente e a anterior será automaticamente invalidada. Para adicionar uma nova senha:

[POST] account/clients/{client}/passwords

Onde:

  • {client} é o id do cliente logado

E o corpo da requisição deverá ser:

{
    password: '******'
}

Consultando endereços de clientes

[GET] /account/clients/{client}/addresses

Onde:

  • {client} é o id do cliente logado

O corpo de resposta estão disponíveis os dados dos endereços:

  • id
    Número de identificação do endereço do cliente
  • address
    Endereço do endereço do cliente
  • city
    Cidade do endereço do cliente
  • complement
    Complemento do endereço do cliente
  • neighborhood
    Bairro do endereço do cliente
  • number
    Número do endereço do cliente
  • state
    Estado do endereço do cliente
  • zip_code
    CEP do endereço do cliente

Consultando cartões de clientes

[GET] /account/clients/{client}/cards

Onde:

  • {client} é o id do cliente logado

O corpo de resposta estão disponíveis os dados básicos dos cartões:

  • id
    Número de identificação do cartão do cliente
  • brand
    Bandeira do cartão do cliente
  • expiration_date
    Data de expiração do cartão do cliente no formato "99/9999"
  • expiration_month
    Mês de expiração do cartão do cliente
  • expiration_year
    Ano de expiração do cartão cliente
  • first_digits
    Dígitos iniciais do cartão do cliente
  • holder_name
    Nome como escrito no cartão do cliente
  • last_digits
    Últimos dígitos do cartão do cliente

Artigos relacionados

Comentários

0 comentário

Por favor, entre para comentar.