BNPL BACKGROUND TRUST | ClearSale Docs

Introdução

Buy Now Pay Later, ou, em tradução livre, “Compre agora, pague depois”, é um método de pagamento digital parcelado semelhante a um crediário digital, para compras online mais comum em e-commerces. Alguns também têm chamado o modelo de parcelamento inteligente.

A grande diferença entre o BNPL e o crediário convencional é a tecnologia por trás deste produto, que permite fazer a análise e a liberação de crédito de forma instantânea e digital, inclusive, utilizando na análise, informações da própria transação como os produtos que estão sendo comprados. Não é mais uma operação física, mas também funciona para transações em estabelecimentos físicos.

Brasileiros estão acostumados a pagar em parcelas, mas a grande maioria da população ainda não é atendida pelos modelos existentes de pagamento além do cartão de crédito. O modelo de Buy Now Pay Later impacta principalmente pessoas que não tem cartão de crédito (como geração Z), pessoas que tem cartão de crédito, mas o limite é baixo e pessoas que não querem, ou preferem não usar, cartão de crédito.

Descrição

O produto BNPL Background Trust foi desenvolvido para que no momento da jornada de pagamento no modelo de BNPL, o tomador de decisão para aprovação de crédito ou averiguação de fraude, possa interagir com o nosso serviço e se beneficiar de todo know-how que a Clear Sale pode oferecer.
Através de uma cominicação via HTTP - API REST entregamos scores e outras informações de apoio para que a análise de aprovação possa ser a mais robusta e satisfatória possível.

Queremos entregar um produto que otimize a jornada no modelo BNPL, oferecendo uma forma unificada, segura e ágil de solução. E que auxilie no crescimento das vendas através deste meio de pagamento
Para isso, entendemos que nossa abordagem traz consigo vários ganhos nesse processo:

Traremos agilidade ao concentrar várias áreas de inteligência da ClearSale em um único gateway inteligente fornecendo mais informações no menor tempo possível.
Traremos simplicidade ao fornecer informações claras e de alta relevância nas tomadas de decisão.
Traremos ainda mais segurança para o processo de BNPL através do Know-How Clear Sale.

Segurança

Todas as requisições submetidas à nossa API devem conter um token de autenticação gerado através de um usuário e senha que devem ser fornecidos pela ClearSale. Neste processo, além do token retornamos seu tempo de expiração em segundos e é necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração.
Além disso, também aplicamos uma configuração de restrição de IP em nossos serviços para que somente um escopo conhecido de endereços cadastrados possa ter seu acesso garantido, assim, em produção, é necessário realizar previamente o cadastros dos IPs. Devido a esta camada de segurança, toda a integração com a nossa API deve ser feita via Backend.

Autorização

Para enviar uma requisição é necessário que o cliente esteja cadastrado no SSO (Single Sign On) da ClearSale, durante o contato para homologação e integração solicite suas credenciais.

Também é necessário que você considere em seu desenvolvimento a gestão da vida útil do token com base no tempo de expiração que é retornado em segundos.

Request


POST  https://bnpl-backgroundtrust.clear.sale/api/v1/identity/auth/token HTTP/1.1 
Content-Type:application/x-www-form-urlencoded

client_id:'client_id'
client_secret:'client_secret''
grant_type:client_credentials
scope:'escopo'


POST  https://bnpl-backgroundtrust-hml.clear.sale/api/v1/identity/auth/token HTTP/1.1 
Content-Type:application/x-www-form-urlencoded

client_id:'client_id'
client_secret:'client_secret''
grant_type:client_credentials
scope:'escopo'

Response

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "token": "...fhgytudX345f.... ",
        "expiresIn": 000 //valor retornado em segundos
    }
}

Análise das transações no contexto de concessão de fraude.

As transações analizadas dentro desse contexto, retornam um conjunto de informações que servem de apoio à averiguação de possível fraude.

Criar transação

Cria uma transação, com os dados da jornada de pagamento.
Essa requisição somente cria uma transação, para obter as informações de apoio à averiguação de possível fraude será necessário uma nova requisição solicitando o processamento.

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v1/fraud/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}

POST https://bnpl-backgroundtrust-hml.clear.sale/api/v1/fraud/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}

Response

A transação foi criada com sucesso.

HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8
{
  "message": "",
  "success": true,
  "result": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
    "message": "The inputs supplied to the API are invalid",
    "success": false,
    "result": [
        "Document is required",
        "Document must be between 11 and 15 characters"
    ]
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de solicitação e resposta

Request
Response

Nome	Descrição	Tipo	Obrigatório
Consumer	Objeto com as informações do consumidor.	Consumer	Sim
Order	Objeto com as informações do pedido.	Order	Não
Merchant	Objeto com as informações do lojista.	Merchant	Não

Consumer

Nome	Descrição	Tipo	Tamanho	Obrigatório
Document	Número do CPF do consumidor.	String	[ 11 .. 15 ]	Sim
DateOfBirth	Data de nascimento do consumidor.	DateTime		Não
Email	Endereço de email do consumidor.	String	[ 0 .. 19 ]	Não
IP	Número de IP do dispositivo do consumidor.	String	[ 0 .. 30 ]	Não
DeviceId	Identificador do dispositivo utilizado.	String	[ 0 .. 30 ]	Não
Address	Endereço residencial do consumidor.	Address		Não

Order

Nome	Descrição	Tipo	Obrigatório
Price	Valor total do pedido.	Decimal	Não
Items	Lista de items do pedido.	Items	Sim
Shipping	Informações sobre o envio do pedido.	Shipping	Não

Merchant

Nome	Descrição	Tipo	Tamanho	Obrigatório
Document	Número de CNPJ do estabelecimento.	String	[ 14 .. 20 ]	Sim
CorporateName	Razão social do estabelecimento.	String	200	Não
Email	Endereço de email do estabelecimento.	String	[ 0 .. 19 ]	Não
Phone	Número do telefone do estabelecimento no formato +55 (32) 91234-5678	String	19	Não
Address	Endereço do estabelecimento.	Address		Não

Item

            Nome
            Descrição
            Tipo
            Tamanho
            Obrigatório
        
            Code
            Código de identificação do item
            String
            
            Sim
        
            Name
            Nome do item.
            String
            
            Sim
        
            Description
            Descrição do item.
            String
            
            Não
        
            Price
            Valor do item.
            Decimal
            
            Sim
        
            Quantity
            Quantidade do item.
            Int
            
            Não

Nome	Descrição	Tipo	Obrigatório
Code	Código de identificação do item	String	Sim
Name	Nome do item.	String	Sim
Description	Descrição do item.	String	Não
Price	Valor do item.	Decimal	Sim
Quantity	Quantidade do item.	Int	Não

Shipping

Nome	Descrição	Tipo	Obrigatório
ReceiverName	Nome de uma pessoa que também poderá receber o produto	String	Não
Price	Valor do frete.	Decimal	Não
Note	Campo para alguma observação relativa a entrega.	String	Não
Address	Endereço de entrega.	Address	Sim

Address

            Nome
            Descrição
            Tipo
            Tamanho
            Obrigatório
        
            ZipCode
            Código postal (Sem pontuação)
            String
            8
            Sim
        
            Street
            Nome da rua ou avenida.
            String
            
            Não
        
            Number
            Número da residência.
            String
            
            Não
        
            Complement
            Complemento do endereço.
            String
            
            Não
        
            District
            Nome do bairro, logradouro ou distrito.
            String
            
            Não
        
            City
            Cidade.
            String
            
            Não
        
            State
            Estado.
            String
            
            Não
        
            Country
            País.
            String
            
            Não

Nome	Descrição	Tipo	Tamanho	Obrigatório
ZipCode	Código postal (Sem pontuação)	String	8	Sim
Street	Nome da rua ou avenida.	String		Não
Number	Número da residência.	String		Não
Complement	Complemento do endereço.	String		Não
District	Nome do bairro, logradouro ou distrito.	String		Não
City	Cidade.	String		Não
State	Estado.	String		Não
Country	País.	String		Não

    
                Nome
                Descrição
                Tipo
            
                Message
                Campo para alguma mensagem de erro ou alerta.
                String
            
                Success
                Campo indicando se a requisição ocorreu com sucesso.
                Boolean
            
                Result
                Identificador único da transação.
                Guid

Nome	Descrição	Tipo
Message	Campo para alguma mensagem de erro ou alerta.	String
Success	Campo indicando se a requisição ocorreu com sucesso.	Boolean
Result	Identificador único da transação.	Guid

Consultar transação

Consulta a transação e retorna as informações de apoio à averiguação de possível fraude.

Request

GET https://bnpl-backgroundtrust.clear.sale/api/v1/fraud/transactions/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

GET https://bnpl-backgroundtrust-hml.clear.sale/api/v1/fraud/transactions/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

Response

A transação foi recuperada com sucesso.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
	"message": "string",
	"success": true,
	"result": {
		"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"date": "2023-06-29T19:50:30.508Z",
		"document": "12345678900",
		"score": 8.1,
		"ratings": [
			{
				"value": 3,
				"related": "Document, ZipCode",
				"description": "O vínculo entre as informações de número de CPF e CEP é considerado Alto"
			},
			{
				"value": 1,
				"related": "Email, ZipCode",
				"description": "O vínculo entre as informações de endereço de email e CEP é considerado Baixo"
			},
			{
				"value": 3,
				"related": "Phone, ZipCode",
				"description": "O vínculo entre as informações de número de telefone e CEP é considerado Alto"
			}
		],
		"insights": [
			{
				"code": "GER2152",
				"description": "CPF com alta incidência de transações positivas"
			},
			{
				"code": "GER2115",
				"description": "Estado de emissão do CPF: MG"
			}
		]
	}
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar esse recurso.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

A transação não foi encontrada ou expirou.

HTTP/1.1 404 NotFound
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Ocorreu algum erro interno durante a criação da requisição.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de solicitação e resposta

Request
Response

    
                Nome
                Descrição
                Tipo
                Tamanho
                Obrigatório
            
                Id
                Identificador único da transação.
                Guid
                
                Sim

Nome	Descrição	Tipo	Tamanho	Obrigatório
Id	Identificador único da transação.	Guid		Sim

Nome	Descrição	Tipo
Document	Número do CPF do consumidor.	String
Score	Pontuação relacionada ao número do documento.	Decimal
Ratings	Lista de valores que indicam o relacionamento entre as informações da transação.	Ratings
Insights	Lista de insights contento observações para apoio na análise.	Insights

    Ratings
    
                Nome
                Descrição
                Tipo
            
                Value
                Valor de 1 à 3 indicando a força do vínculo entre as informações (1 - Baixo, 2 - Médio, 3 - Alto).
                Int
            
                Related
                Informações sobre as quais o vínculo é referente.
                String[]
            
                Description
                Descrição para entender melhor a informação.
                String

Nome	Descrição	Tipo
Value	Valor de 1 à 3 indicando a força do vínculo entre as informações (1 - Baixo, 2 - Médio, 3 - Alto).	Int
Related	Informações sobre as quais o vínculo é referente.	String[]
Description	Descrição para entender melhor a informação.	String

    Insights
    
                Nome
                Descrição
                Tipo
            
                Code
                Código de identificação para o Insight.
                String
            
                Description
                Descrição para o Insight.
                String

Nome	Descrição	Tipo
Code	Código de identificação para o Insight.	String
Description	Descrição para o Insight.	String

Consultar lista de transações

Consulta uma lista paginada de transações e retorna informações básicas sobre elas.

Request

GET https://bnpl-backgroundtrust.clear.sale/api/v1/fraud/transactions?page=0&count=100 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

GET https://bnpl-backgroundtrust-hml.clear.sale/api/v1/fraud/transactions?page=0&count=100 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

Response

A transação foi recuperada com sucesso.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "date": "2023-06-29T19:16:46.431Z",
        "document": "12345678900",
        "url": "/api/v1/fraud/transactions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar esse recurso.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

A transação não foi encontrada ou expirou.

HTTP/1.1 404 NotFound
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Ocorreu algum erro interno durante a criação da requisição.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de solicitação e resposta

Request
Response

    
        
                Nome
                Descrição
                Tipo
                Valor padrão
                Obrigatório
            

        
                Page
                Índice da página a ser retornado.
                Int
                0
                Não
            

                Count
                Total de registro a serem retornados.
                Int
                100
                Não
            

    

Nome	Descrição	Tipo	Valor padrão	Obrigatório
Page	Índice da página a ser retornado.	Int	0	Não
Count	Total de registro a serem retornados.	Int	100	Não

    
                Nome
                Descrição
                Tipo
            
                Id
                Identificador único da transação.
                Guid
            
                Date
                Data em que a transação foi criada.
                Date Time
            
                Document
                Número do CPF do consumidor.
                String
            
                Url
                Endereço relativo para consultar a transação de forma unitária.
                String

Nome	Descrição	Tipo
Id	Identificador único da transação.	Guid
Date	Data em que a transação foi criada.	Date Time
Document	Número do CPF do consumidor.	String
Url	Endereço relativo para consultar a transação de forma unitária.	String

Análise das transações no contexto de concessão de crédito

As transações analizadas dentro desse contexto, retornam um conjunto de scores que servem de apoio a tomada de decisão na concessão de crédito.

Criar transação

Cria uma transação, com os dados da jornada de pagamento.
Essa requisição somente cria uma transação, para obter as informações de apoio a análise de crédito será necessário uma nova requisição solicitando o processamento.

Request

POST https://bnpl-backgroundtrust.clear.sale/api/v1/credit/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}

POST https://bnpl-backgroundtrust-hml.clear.sale/api/v1/credit/transactions HTTP/1.1
Content-Type: application/json
Accept:application/json
Authorization: Bearer {Token}
{
  "consumer": {
    "document": "112.174.320-00",
    "dateOfBirth": "2023-06-29T17:30:47.949Z",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "ip": "192.158.1.38",
    "deviceId": "string",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  },
  "order": {
    "price": 50,
    "items": [
      {
        "code": "A34RF-76",
        "name": "Meu item....",
        "description": "descrição do meu item....",
        "price": 50,
        "quantity": 3
      }
    ],
    "shipping": {
      "receiverName": "João da Silva",
      "price": 87.5,
      "address": {
        "zipCode": "12345678",
        "street": "Nome da rua",
        "number": "1",
        "complement": "Casa/Apartamento",
        "district": "Meu bairro",
        "city": "São Paulo/Rio de Janeiro...",
        "state": "MG/SP/RJ ....",
        "country": "Brasil"
      },
      "note": "Realizar a entrega somente depois das 18:00h"
    }
  },
  "merchant": {
    "document": "12.345.678/0001-99",
    "corporateName": "Vendendor de produtos LTDA.",
    "email": "user@example.com",
    "phone": "+55 (32) 91234-5678",
    "address": {
      "zipCode": "12345678",
      "street": "Nome da rua",
      "number": "1",
      "complement": "Casa/Apartamento",
      "district": "Meu bairro",
      "city": "São Paulo/Rio de Janeiro...",
      "state": "MG/SP/RJ ....",
      "country": "Brasil"
    }
  }
}

Response

A transação foi criada com sucesso.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "date": "2023-06-29T19:16:46.431Z",
        "document": "12345678900",
        "score": 500,
        "digital": true,
        "rank": "g",
        "varietyIndex": 100,
        "behaviourIndex": 200,
        "profileIndex": 300,
        "statusIndex": 400,
        "postalIndex": 500,
        "rapportIndex": 600
    }
}

Existem parâmetros inválidos na requisição.

HTTP/1.1 400 Bad Request
Content-Type: application/json; charset=utf-8
{
    "message": "The inputs supplied to the API are invalid",
    "success": false,
    "result": [
        "Document is required",
        "Document must be between 11 and 15 characters"
    ]
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar o recurso desejado.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

Ocorreu algum erro interno durante a criação da requisição.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de solicitação e resposta

Request
Response

Nome	Descrição	Tipo	Obrigatório
Consumer	Objeto com as informações do consumidor.	Consumer	Sim
Order	Objeto com as informações do pedido.	Order	Não
Merchant	Objeto com as informações do lojista.	Merchant	Não

Consumer

Nome	Descrição	Tipo	Tamanho	Obrigatório
Document	Número do CPF do consumidor.	String	[ 11 .. 15 ]	Sim
DateOfBirth	Data de nascimento do consumidor.	DateTime		Não
Email	Endereço de email do consumidor.	String	[ 0 .. 19 ]	Não
IP	Número de IP do dispositivo do consumidor.	String	[ 0 .. 30 ]	Não
DeviceId	Identificador do dispositivo utilizado.	String	[ 0 .. 30 ]	Não
Address	Endereço residencial do consumidor.	Address		Não

Order

Nome	Descrição	Tipo	Obrigatório
Price	Valor total do pedido.	Decimal	Não
Items	Lista de items do pedido.	Items	Sim
Shipping	Informações sobre o envio do pedido.	Shipping	Não

Merchant

Nome	Descrição	Tipo	Tamanho	Obrigatório
Document	Número de CNPJ do estabelecimento.	String	[ 14 .. 20 ]	Sim
CorporateName	Razão social do estabelecimento.	String	200	Não
Email	Endereço de email do estabelecimento.	String	[ 0 .. 19 ]	Não
Phone	Número do telefone do estabelecimento no formato +55 (32) 91234-5678	String	19	Não
Address	Endereço do estabelecimento.	Address		Não

Item

            Nome
            Descrição
            Tipo
            Tamanho
            Obrigatório
        
            Code
            Código de identificação do item
            String
            
            Sim
        
            Name
            Nome do item.
            String
            
            Sim
        
            Description
            Descrição do item.
            String
            
            Não
        
            Price
            Valor do item.
            Decimal
            
            Sim
        
            Quantity
            Quantidade do item.
            Int
            
            Não

Nome	Descrição	Tipo	Obrigatório
Code	Código de identificação do item	String	Sim
Name	Nome do item.	String	Sim
Description	Descrição do item.	String	Não
Price	Valor do item.	Decimal	Sim
Quantity	Quantidade do item.	Int	Não

Shipping

Nome	Descrição	Tipo	Obrigatório
ReceiverName	Nome de uma pessoa que também poderá receber o produto	String	Não
Price	Valor do frete.	Decimal	Não
Note	Campo para alguma observação relativa a entrega.	String	Não
Address	Endereço de entrega.	Address	Sim

Address

            Nome
            Descrição
            Tipo
            Tamanho
            Obrigatório
        
            ZipCode
            Código postal (Sem pontuação)
            String
            8
            Sim
        
            Street
            Nome da rua ou avenida.
            String
            
            Não
        
            Number
            Número da residência.
            String
            
            Não
        
            Complement
            Complemento do endereço.
            String
            
            Não
        
            District
            Nome do bairro, logradouro ou distrito.
            String
            
            Não
        
            City
            Cidade.
            String
            
            Não
        
            State
            Estado.
            String
            
            Não
        
            Country
            País.
            String
            
            Não

Nome	Descrição	Tipo	Tamanho	Obrigatório
ZipCode	Código postal (Sem pontuação)	String	8	Sim
Street	Nome da rua ou avenida.	String		Não
Number	Número da residência.	String		Não
Complement	Complemento do endereço.	String		Não
District	Nome do bairro, logradouro ou distrito.	String		Não
City	Cidade.	String		Não
State	Estado.	String		Não
Country	País.	String		Não

    
                Nome
                Descrição
                Tipo
            
                Document
                Número do CPF do consumidor.
                String
            
                Score
                Pontuação relacionada ao número do documento.
                Int
            
                Digital
                Parâmetro de classificação que indica se o cliente tem ou não presença digital.
                Boolean
            
                Rank
                Total de compras, tipos de cartões usados e CEPs relacionados ao cliente
                String
            
                VarietyIndex
                Qualidade e variedade do que o cliente compra.
                Int
            
                BehaviourIndex
                Formas de pagamento utilizadas e frequência de compra do cliente.
                Int
            
                RapportIndex
                Scores dos CPF relacionados ao cliente.
                Int
            
                ProfileIndex
                Tipo de endereço, tipo de device, categoria do cartão do cliente.
                Int
            
                StatusIndex
                Características fixas como data e local de nascimento do cliente.
                Int
            
                PostalIndex
                Valor e frequência de compras nos CEPs relacionados ao cliente.
                Int

Consultar transação

Consulta a transação e retorna as informações de apoio a análise de crédito.

Request

GET https://bnpl-backgroundtrust.clear.sale/api/v1/credit/transactions/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

GET https://bnpl-backgroundtrust-hml.clear.sale/api/v1/credit/transactions/{id} HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

Response

A transação foi recuperada com sucesso.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
	"message": "",
	"success": true,
	"result": {
		"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"date": "2023-06-29T19:16:46.431Z",
		"document": "12345678900",
		"score": 500,
		"digital": true,
		"rank": "g",
		"varietyIndex": 100,
		"behaviourIndex": 200,
		"profileIndex": 300,
		"statusIndex": 400,
		"postalIndex": 500,
		"rapportIndex": 600
	}
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar esse recurso.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

A transação não foi encontrada ou expirou.

HTTP/1.1 404 NotFound
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Ocorreu algum erro interno durante a criação da requisição.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de solicitação e resposta

Request
Response

    
                Nome
                Descrição
                Tipo
                Tamanho
                Obrigatório
            
                Id
                Identificador único da transação.
                Guid
                
                Sim

Nome	Descrição	Tipo	Tamanho	Obrigatório
Id	Identificador único da transação.	Guid		Sim

    
                Nome
                Descrição
                Tipo
            
                Document
                Número do CPF do consumidor.
                String
            
                Score
                Pontuação relacionada ao número do documento.
                Int
            
                Digital
                Parâmetro de classificação que indica se o cliente tem ou não presença digital.
                Boolean
            
                Rank
                Total de compras, tipos de cartões usados e CEPs relacionados ao cliente
                String
            
                VarietyIndex
                Qualidade e variedade do que o cliente compra.
                Int
            
                BehaviourIndex
                Formas de pagamento utilizadas e frequência de compra do cliente.
                Int
            
                RapportIndex
                Scores dos CPF relacionados ao cliente.
                Int
            
                ProfileIndex
                Tipo de endereço, tipo de device, categoria do cartão do cliente.
                Int
            
                StatusIndex
                Características fixas como data e local de nascimento do cliente.
                Int
            
                PostalIndex
                Valor e frequência de compras nos CEPs relacionados ao cliente.
                Int

Consultar lista de transações

Consulta uma lista paginada de transações e retorna informações básicas sobre elas.

Request

GET https://bnpl-backgroundtrust.clear.sale/api/v1/credit/transactions?page=0&count=100 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

GET https://bnpl-backgroundtrust-hml.clear.sale/api/v1/credit/transactions?page=0&count=100 HTTP/1.1
Content-Type: application/json
Authorization: Bearer {Token}

Response

A transação foi recuperada com sucesso.

HTTP/1.1 200 Ok
Content-Type: application/json; charset=utf-8
{
    "message": "",
    "success": true,
    "result": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "date": "2023-06-29T19:16:46.431Z",
        "document": "12345678900",
        "url": "/api/v1/credit/transactions/3fa85f64-5717-4562-b3fc-2c963f66afa6"
    }
}

Requisição com token expirado ou inválido.

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

Unauthorized request

O usuário não tem permissão para acessar esse recurso.

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8

Forbidden request

A transação não foi encontrada ou expirou.

HTTP/1.1 404 NotFound
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Ocorreu algum erro interno durante a criação da requisição.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; charset=utf-8
{
  "message": "Mensagem de erro",
  "success": false,
  "result": ""
}

Informações sobre os parâmetros de solicitação e resposta

Request
Response

    
        
                Nome
                Descrição
                Tipo
                Valor padrão
                Obrigatório
            

        
                Page
                Índice da página a ser retornado.
                Int
                0
                Não
            

                Count
                Total de registro a serem retornados.
                Int
                100
                Não
            

    

Nome	Descrição	Tipo	Valor padrão	Obrigatório
Page	Índice da página a ser retornado.	Int	0	Não
Count	Total de registro a serem retornados.	Int	100	Não

    
                Nome
                Descrição
                Tipo
            
                Id
                Identificador único da transação.
                Guid
            
                Date
                Data em que a transação foi criada.
                Date Time
            
                Document
                Número do CPF do consumidor.
                String
            
                Url
                Endereço relativo para consultar a transação de forma unitária.
                String

Nome	Descrição	Tipo
Id	Identificador único da transação.	Guid
Date	Data em que a transação foi criada.	Date Time
Document	Número do CPF do consumidor.	String
Url	Endereço relativo para consultar a transação de forma unitária.	String

Avisos e recomendações

📌 Recomendação

Performance - Uso do ambiente de homologação

O Ambiente de homologação deve ser utilizado somente para fims de desenvolvimento, pois o mesmo pode apresentar alguma lentidão, e por restringir as transações a determinados números de CPF.

📌 Recomendação

Segurança - Gerenciamento do token de autorização

Todas as requisições submetidas à nossa API devem conter um token de autenticação gerado através de um usuário e senha que devem ser fornecidos pela ClearSale. Neste processo, além do token retornamos seu tempo de expiração em segundos e é necessário que contemple no seu desenvolvimento o gerenciamento da vida útil do token com base nesse tempo de expiração.

📢 Aviso Importante

Segurança - Bloqueio de Ips

Aplicamos uma configuração de restrição de IP em nossos serviços para que somente um escopo conhecido de endereços cadastrados possa ter seu acesso garantido, assim, em produção, é necessário realizar previamente o cadastros dos IPs.

📌 Recomendação

Integração - Números de CPF para testes em homologação no contexto de crédito

Para realizar testes e validações por faixa de score principal, no contexto de crédito utilize os respectivos CPF:

000.235.082-30 para score na faixa 100
003.879.762-30 para score na faixa 200
366.708.678-40 para score na faixa 300
438.415.112-87 para score na faixa 400
032.995.682-56 para score na faixa 500
274.917.408-20 para score na faixa 600
756.097.622-00 para score na faixa 700
013.563.708-29 para score na faixa 800
380.068.688-08 para score na faixa 900

📌 Recomendação

Integração - Números de CPF para testes em homologação no contexto de fraude

Para realizar testes e validações por faixa de score principal, no contexto de fraude utilize os respectivos CPF:

XXX.XXX.XXX-X0 para score na faixa 0~10
XXX.XXX.XXX-X1 para score na faixa 10~20
XXX.XXX.XXX-X2 para score na faixa 20~30
XXX.XXX.XXX-X3 para score na faixa 30~40
XXX.XXX.XXX-X4 para score na faixa 40~50
XXX.XXX.XXX-X5 para score na faixa 50~60
XXX.XXX.XXX-X6 para score na faixa 60~70
XXX.XXX.XXX-X7 para score na faixa 70~80
XXX.XXX.XXX-X8 para score na faixa 80~90
XXX.XXX.XXX-X9 para score na faixa 90~100

Dúvidas ou problemas técnicos

Em caso de dúvidas ou problemas técnicos, fale com a gente através do e-mail bianca.costa@clear.sale