Integração de contas

Última atualização: 22 de Setembro de 2021

Introdução

Com a nossa API de integração de contas será possível integrar conosco as criações e alterações de contas ocorridas em seu website. Também será possível nos notificar sempre que ocorrer algum evento como login, logout e recuperação de senha, por exemplo.

Fingerprint

Para a utilização do módulo Integração de contas é necessário que o Fingerprint esteja integrado ao seu website.

Para maiores informações sobre as configurações do Fingerprint clique aqui.

Criação de Conta

Este método é utilizado para enviar as contas a serem analisadas pela ClearSale.

Requisição
POST http://api.clearsale.com.br/v1/accounts HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "code": "ACCOUNT_2017020505",
  "date": "2016-12-25T15:55:13",
  "sessionID": "cd161347af40806c",
  "referrerAccountID": "account_5678_efgh",
  "name": "João da Silva Souza",
  "personDocument": "89734810619",
  "birthDate": "1980-06-25",
  "gender": "M",
  "companyName": "XPTO",
  "companyDocument": "12345678912345",
  "companyContact": "João da Silva",
  "motherName": "Creuza da Silva",
  "email": "joao.silva@gmail.com",
  "passwordHash": "gxpGmwsudPQoAi9qlskUCrGauz8=",
  "optinEmail": "1",
  "optinMobile": "0",
  "payments": [
    {
      "ownerName": "João da Silva Junior",
      "bin": "123456",
      "endNumber": "5678",
      "type": "Visa"
    }
  ],
  "phones": [
    {
      "name": "Home",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": ""
    },
    {
      "name": "Work",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": "Option 5"
    }
  ],
  "addresses": [
    {
      "name": "Home",
      "street": "E Coast Ave",
      "number": "2547",
      "city": "Miami",
      "state": "UF",
      "country": "USA",
      "county": "bairro1",
      "zipcode": "33137"
    },
    {
      "name": "Work",
      "street": "Biscayne Boulevard",
      "number": "7300",
      "comp": "Suite 200",
      "city": "Miami",
      "state": "UF",
      "county": "bairro2",
      "country": "USA",
      "zipcode": "33138"
    }
  ],
  "socialSignOn": {
    "type": "Facebook",
    "name": "João da Silva",
    "profileUrl": "http://www.facebook.com/joaosilva",
    "socialID": "João da Silva",
    "location": "San Francisco"
  }
}
POST http://homologacao.clearsale.com.br/api/v1/accounts HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "code": "ACCOUNT_2017020505",
  "date": "2016-12-25T15:55:13",
  "sessionID": "cd161347af40806c",
  "referrerAccountID": "account_5678_efgh",
  "name": "João da Silva Souza",
  "personDocument": "89734810619",
  "birthDate": "1980-06-25",
  "gender": "M",
  "motherName": "Creuza da Silva",
  "email": "joao.silva@gmail.com",
  "passwordHash": "gxpGmwsudPQoAi9qlskUCrGauz8=",
  "optinEmail": "1",
  "optinMobile": "0",
  "payments": [
    {
      "ownerName": "João da Silva Junior",
      "bin": "123456",
      "endNumber": "5678",
      "type": "Visa"
    }
  ],
  "phones": [
    {
      "name": "Home",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": ""
    },
    {
      "name": "Work",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": "Option 5"
    }
  ],
  "addresses": [
    {
      "name": "Home",
      "street": "E Coast Ave",
      "number": "2547",
      "city": "Miami",
      "state": "UF",
      "country": "USA",
      "county": "bairro1",
      "zipcode": "33137"
    },
    {
      "name": "Work",
      "street": "Biscayne Boulevard",
      "number": "7300",
      "comp": "Suite 200",
      "city": "Miami",
      "state": "UF",
      "county": "bairro2",
      "country": "USA",
      "zipcode": "33138"
    }
  ],
  "socialSignOn": {
    "type": "Facebook",
    "name": "João da Silva",
    "profileUrl": "http://www.facebook.com/joaosilva",
    "socialID": "João da Silva",
    "location": "San Francisco"
  }
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "requestID": "70O5-18S0-93V0-75B5",
    "account": 
    {
        "code": "codigo_conta"
    }
}
Dicionário de variáveis
Nome Descrição Tipo Tamanho Obrigatório
code ID da conta String 50 Sim
date Data da criação da conta. Data (yyyy-MM-ddThh:mm:ss) - Sim
referrerAccountID ID da conta referente a conta criada, caso o seu negócio permita a indicação de usuários. String 50 Não
sessionID Identificador único da sessão do usuário. String 128 Sim
name Pessoa Física.
Nome do cliente.		 String 500 Sim (se for pessoa física)
personDocument Pessoa Física.
CPF do cliente		 String 11 Sim (se for pessoa física)
birthDate Pessoa Física.
Data de nascimento do cliente.		 Data (yyyy-mm- dd) - Não
gender Pessoa Física.
Gênero do Cliente		 String 1 Não
motherName Pessoa Física.
Nome da mãe do cliente.		 String 500 Não
companyName Pessoa Jurídica.
Nome da empresa.		 String 500 Sim (se for pessoa jurídica)
companyDocument Pessoa Jurídica.
CNPJ da empresa.		 String 14 Sim (se for pessoa jurídica)
companyContact Pessoa Jurídica.
Contato na empresa.		 String 500 Não
email Email do cliente String 150 Sim
passwordHash Os 4 primeiros caracteres da senha em MurmurHash3 64bits. String 32 Não
optinEmail Se o cliente permitiu comunicações por e-mail, (informar 1 ou 0). Boleano 1 Não
optinMobile Se o cliente permitiu comunicações por telefone, (informar 1 ou 0). Boleano 1 Não
payments Os dados de pagamento armazenados no cadastro do cliente. Lista de Pagamentos - Não
phones Os telefones armazenados no cadastro do cliente. Lista de Telefones - Não
addresses Os endereços armazenados no cadastro do cliente. Lista de Endereços - Não
socialSignOn Os dados de rede social vinculados com o cadastro do cliente. Dados de Rede Social - Não

Batimento Cadastral

Caso o cliente tenha a funcionalidade de batimento cadastral configurada, na criação de contas será feito o batimento cadastral dos dados inseridos e o Webhook da Clearsale irá enviar uma notificação para uma URL que deverá ser implementada no lado do integrador.

Os dados do batimento cadastral não serão informados na notificação do Webhook, portanto, fica a cargo do integrador o consumo da consulta desse objeto.

Importante: Se a URL do integrador retornar qualquer status http diferente de 200, o Webhook irá tentar notificar novamente para a conta.

Assim que a URL for desenvolvida é necessário que envie o endereço a equipe de integração através do e-mail integracao@clear.sale para que essa URL seja configurada na base da Clearsale.

Notificação do Webhook

{URL_DO_INTEGRADOR}
Content-Type: application/json
{
    "code": "{ID_DO_BATIMENTO_CADASTRAL}",
    "date": "2018-01-01T10:30:00.000",
    "type": "BatimentoCadastral"
}

Com o ID do batimento cadastral o cliente deve fazer uma consulta para retornar os dados do batimento cadastral da conta inserida previamente.


Requisição

GET http://api.clearsale.com.br/v1/account/registercheck/{ID_DO_BATIMENTO_CADASTRAL}
Accept: application/json
Authorization: Bearer {TOKEN}

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "accountCode": "codigo_conta",
    "adulthood": "1",
    "death": "0"
}

Alteração de Conta

Este método é utilizado para enviar as contas a serem analisadas pela ClearSale.

Requisição
PUT https://api.clearsale.com.br/v1/accounts HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "code": "ACCOUNT_2017020505",
  "date": "2016-12-25T15:55:13",
  "sessionID": "cd161347af40806c",
  "referrerAccountID": "account_5678_efgh",
  "name": "João da Silva Souza",
  "personDocument": "89734810619",
  "birthDate": "1980-06-25",
  "gender": "M",
  "companyName": "XPTO",
  "companyDocument": "12345678912345",
  "companyContact": "João da Silva",
  "motherName": "Creuza da Silva",
  "email": "joao.silva@gmail.com",
  "passwordHash": "gxpGmwsudPQoAi9qlskUCrGauz8=",
  "optinEmail": "1",
  "optinMobile": "0",
  "payments": [
    {
      "ownerName": "João da Silva Junior",
      "bin": "123456",
      "endNumber": "5678",
      "type": "Visa"
    }
  ],
  "phones": [
    {
      "name": "Home",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": ""
    },
    {
      "name": "Work",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": "Option 5"
    }
  ],
  "addresses": [
    {
      "name": "Home",
      "street": "E Coast Ave",
      "number": "2547",
      "city": "Miami",
      "state": "UF",
      "country": "USA",
      "county": "bairro1",
      "zipcode": "33137"
    },
    {
      "name": "Work",
      "street": "Biscayne Boulevard",
      "number": "7300",
      "comp": "Suite 200",
      "city": "Miami",
      "state": "UF",
      "county": "bairro2",
      "country": "USA",
      "zipcode": "33138"
    }
  ],
  "socialSignOn": {
    "type": "Facebook",
    "name": "João da Silva",
    "profileUrl": "http://www.facebook.com/joaosilva",
    "socialID": "João da Silva",
    "location": "San Francisco"
  }
}
PUT https://homologacao.clearsale.com.br/api/v1/accounts HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "code": "ACCOUNT_2017020505",
  "date": "2016-12-25T15:55:13",
  "sessionID": "cd161347af40806c",
  "referrerAccountID": "account_5678_efgh",
  "name": "João da Silva Souza",
  "personDocument": "89734810619",
  "birthDate": "1980-06-25",
  "gender": "M",
  "motherName": "Creuza da Silva",
  "email": "joao.silva@gmail.com",
  "passwordHash": "gxpGmwsudPQoAi9qlskUCrGauz8=",
  "optinEmail": "1",
  "optinMobile": "0",
  "payments": [
    {
      "ownerName": "João da Silva Junior",
      "bin": "123456",
      "endNumber": "5678",
      "type": "Visa"
    }
  ],
  "phones": [
    {
      "name": "Home",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": ""
    },
    {
      "name": "Work",
      "ddi": "55",
      "ddd": "11",
      "number": "1234-5678",
      "extension": "Option 5"
    }
  ],
  "addresses": [
    {
      "name": "Home",
      "street": "E Coast Ave",
      "number": "2547",
      "city": "Miami",
      "state": "UF",
      "country": "USA",
      "county": "bairro1",
      "zipcode": "33137"
    },
    {
      "name": "Work",
      "street": "Biscayne Boulevard",
      "number": "7300",
      "comp": "Suite 200",
      "city": "Miami",
      "state": "UF",
      "county": "bairro2",
      "country": "USA",
      "zipcode": "33138"
    }
  ],
  "socialSignOn": {
    "type": "Facebook",
    "name": "João da Silva",
    "profileUrl": "http://www.facebook.com/joaosilva",
    "socialID": "João da Silva",
    "location": "San Francisco"
  }
}
Resposta
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "requestID": "70O5-18S0-93V0-75B5",
    "account": {
    "code": "codigo_conta"
    }
}

Contrato de Contas

Account


Nome Descrição Tipo Tamanho Obrigatório
code ID da conta String 50 Sim
date Data da criação da conta. Data (yyyy-MM-ddThh:mm:ss) - Sim
referrerAccountID ID da conta referente a conta criada, caso o seu negócio permita a indicação de usuários. String 50 Não
sessionID Identificador único da sessão do usuário. String 128 Sim
name Pessoa Física.
Nome do cliente.		 String 500 Sim (se for pessoa física)
personDocument Pessoa Física.
CPF do cliente		 String 11 Sim (se for pessoa física)
birthDate Pessoa Física.
Data de nascimento do cliente.		 Data (yyyy-mm- dd) - Não
gender Pessoa Física.
Nome da mãe do cliente.		 String 500 Não
companyName Pessoa Jurídica.
Nome da empresa.		 String 500 Sim (se for pessoa jurídica)
companyDocument Pessoa Jurídica.
CNPJ da empresa.		 String 14 Sim (se for pessoa jurídica)
companyContact Pessoa Jurídica.
Contato na empresa.		 String 500 Não
email E-mail do cliente String 150 Sim
passwordHash Os 4 primeiros caracteres da senha em MurmurHash3 64bits. String 32 Não
optinEmail Se o cliente permitiu comunicações por e-mail, (informar 1 ou 0). Boleano 1 Não
optinMobile Se o cliente permitiu comunicações por telefone, (informar 1 ou 0). Boleano 1 Não
payments Os dados de pagamento armazenados no cadastro do cliente. Lista de Pagamentos - Não
phones Os telefones armazenados no cadastro do cliente. Lista de Telefones - Não
addresses Os endereços armazenados no cadastro do cliente. Lista de Endereços - Não
socialSignOn Os dados de rede social vinculados com o cadastro do cliente. Dados de Rede Social - Não

Payment


Nome Descrição Tipo Tamanho Obrigatório
ownerName Nome do proprietário do cartão. String 500 Não
bin Número do BIN do cartão. (6 primeiros dígitos). String 6 Sim
endNumber 4 últimos dígitos do número do cartão. String 4 Sim
type Bandeira do cartão.
As opções disponíveis são: Diners, MasterCard, Visa, AmericanExpress, HiperCard, Aura, Outros. 		String 128 Sim

Phone


Nome Descrição Tipo Tamanho Obrigatório
name Nome para o telefone, pode ser um campo aberto preenchido pelo usuário ou a identificação para cobrança, entrega ou recado, por exemplo. String 500 Não
ddi DDI do telefone. Número 3 Sim
ddd DDD do telefone. String 2 Sim
number Número do telefone. Número 9 Sim
extension Ramal ou alguma outra opção para o telefone. String 10 Não

Address


Nome Descrição Tipo Tamanho Obrigatório
name Nome para o endereço, pode ser um campo aberto preenchido pelo usuário ou a identificação para cobrança, entrega ou recado, por exemplo. String 500 Não
street Nome do logradouro do endereço. String 200 Sim
ddd DDD do telefone. String 2 Sim
number Número do endereço. Número 15 Sim
comp Complemento do endereço. String 150 Não
county Bairro do endereço. String 150 Sim
city Cidade do endereço. String 150 Sim
state Sigla do estado do endereço. String 2 Sim
country País do endereço. String 150 Não
zipCode CEP do endereço. String 10 Sim
reference Referência para o endereço. String 250 Não

SocialSignOn


Nome Descrição Tipo Tamanho Obrigatório
type O provedor de rede social que o usuário usou para realizar o cadastro da conta. As opções disponíveis são: Facebook, Google, LinkedIn, Twitter, Yahoo e Outros. String - Sim
socialID ID do usuário na rede social. String 50 Sim
name Nome cadastrado na rede. String 200 Não
profileUrl Endereço do perfil na rede. String 150 Não
location Localização do cliente na rede. String 150 Não

Descrição dos campos JSON retornada pelo método SendOrders:

Campo Tipo Descrição
RequestID GUID Identificador único para a requisição da conta enviada.
StatusCode String Código do erro ou da mensagem de sucesso referente à transação.
Message String Mensagem de erro ou de sucesso da operação.

Abaixo está a lista dos códigos retornados na TAG StatusCode:

Código Descrição Reenviar
00 Transação concluída. Não
01 Não autenticado. Sim
02 Erro na validação do JSON Sim
03 Erro ao transformar JSON Sim
04 Erro Inesperado Sim
05 A conta já foi enviada, por favor, utilize o método UpdateAccount Sim
06 A conta não existe, por favor, utilize o método CreateAccount Sim

Eventos

Login

Este método será responsável por registrar os logins realizados em uma conta.

Requisição
POST Request: http://api.clearsale.com.br/v1/Accounts/Login HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "code": "codigo_conta",
    "sessionID": "session_id"
}
POST Request: http://homologacao.clearsale.com.br/api/v1/Accounts/Login HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "code": "codigo_conta",
    "sessionID": "session_id"
}

O campo "codigo_conta" deve ser preenchido com o código que foi utilizado na criação da conta do usuário e o campo "session_id" é o valor da sessão do usuário.

Resposta
HTTP/1.1 200 OK
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "requestID": "70O5-18S0-93V0-75B5",
    "account": 
    {
        "code": "codigo_conta"
    }
}

Logout

Este método será responsável por registrar os logouts realizados em uma conta.

Requisição
POST Request: http://api.clearsale.com.br/v1/Accounts/Logout HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "code": "codigo_conta"
}
POST Request: http://homologacao.clearsale.com.br/api/v1/Accounts/Logout HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "code": "codigo_conta"
}

O campo "codigo_conta" deve ser preenchido com o código que foi utilizado na criação da conta do usuário.

Resposta
HTTP/1.1 200 OK
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "requestID": "70O5-18S0-93V0-75B5",
    "account": 
    {
        "code": "codigo_conta"
    }
}

Recuperação de Senha

Se o campo PasswordHash não estiver integrado na criação e alteração de contas, sempre que a senha da conta for alterada este método deverá ser chamado.

Requisição
POST Request: http://api.clearsale.com.br/v1/Accounts/ResetPassword HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "code": "codigo_conta",
    "sessionID": "session_id"
}
POST Request: http://homologacao.clearsale.com.br/api/v1/Accounts/ResetPassword HTTP/1.1
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "code": "codigo_conta",
    "sessionID": "session_id"
}

O campo "codigo_conta" deve ser preenchido com o código que foi utilizado na criação da conta do usuário e o campo "session_id" é o valor da sessão do usuário.

Resposta
HTTP/1.1 200 OK
Content-Type:application/json
Accept:application/json
Authorization: Bearer {Token}
{
    "requestID": "70O5-18S0-93V0-75B5",
    "account": 
    {
        "code": "codigo_conta"
    }
}