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
• Prevenindo duplicações
• Obtendo token de autenticação
• Persistindo o token na sessão do usuário
• Removendo token persistido da sessão do usuário
• Consultando token persistido na sessão do usuário
• Consultando dados do cliente logado
• Recuperando a senha
  • Criar uma nova senha
  • Entrar com código temporário
• Alterando a senha atual
• Consultando endereços de clientes
• Cadastrando endereços de clientes
• Removendo endereços de clientes
• Consultando cartões de clientes

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'
    },
    'extra_fields': {
        'foo_123_321' => 'Value',
        'bar_456_654' => 777
    }
}

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.
• extra_fields objeto com os valores dos campos extras que deverão ser salvos ao cliente. Os slugs dos campos deverão ser informados junto dos seus IDs de formulário e campo extra. Por exemplo: para o campo extra com slug "teste" e ID 5 para o form ID 8, a chave do campo extra será teste_8_5.

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.

Consultando dados do cliente logado

Para consultar os dados do cliente já logado, uma requisição poderá ser disparada e o formato de retorno será semelhante aos dados de retorno da requisição de criação de cliente. O endpoint para consulta dos dados do cliente logado é:

[GET] ecommerce/identification/authenticated-user

O corpo do retorno será:

• id
  Número de identificação
• address
  Endereços do cliente
• document1
  CPF/CNPJ do cliente
• document2
  RG/IE do cliente
• email
  E-mail do cliente
• full_name
  Nome completo do cliente
• legal_personality
  Flag com o tipo do cliente, onde 0 representa Pessoa física e 1 representa Pessoa jurídica
• name1
  Nome/Razão social do cliente
• name2
  Sobrenome/Nome fantasia do cliente
• tags
  Dados das tags do cliente
• telephone
  Dados do telefone do cliente

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 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

Cadastrando endereços de clientes

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

Onde:

• {client} é o id do cliente logado

No corpo da requisição, enviar os seguintes dados do endereço:

• zip_code
  CEP do endereço do cliente
• address
  Endereço do endereço do cliente
• number
  Número do endereço do cliente
• complement
  Complemento do endereço do cliente
• neighborhood
  Bairro do endereço do cliente
• city
  Cidade do endereço do cliente.
• state
  Estado do endereço do cliente. Deverá ser algum dos valores entre: 'AC', 'AL', 'AM', 'AP', 'BA', 'CE', 'DF', 'ES', 'GO', 'MA', 'MT', 'MS', 'MG', 'PA', 'PB', 'PR', 'PE', 'PI', 'RJ', 'RN', 'RS', 'RO', 'RR', 'SC', 'SP', 'SE' ou 'TO'

Removendo endereços de clientes

[DELETE] /account/clients/{client}/addresses/{address}

Onde:

• {client} é o id do cliente logado
• {address} é o id do endereço a ser removido

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