Insights

Funcionamento do Módulo `Insights`

O módulo Insights opera de forma síncrona, realizando a análise dos dados imediatamente após o recebimento de uma solicitação. Esse processo envolve o cruzamento de múltiplas informações relevantes, com o objetivo de calcular o score, determinar o status e os insights da análise.

A resposta da análise é retornada em questão de segundos, permitindo decisões rápidas e integradas ao fluxo da aplicação, sem a necessidade de processamento assíncrono ou espera prolongada.

Schema Request

Representa a requisição para integração.

Campos	Descrição	Tipo	Obrigatório
transaction	Informações da transação	Transaction	Sim
transactionValue	Informações do valor da transação	Transaction Value	Não
device	Informações do dispositivo	Device	Não
billing	Informações de cobrança	Billing	Sim
shipping	Informações de envio	Shipping	Não
items	Lista de itens da transação	Item Array	Não
payments	Lista de métodos de pagamento	Payment Array	Não
airTravel	Informações sobre a viagem aérea	Air Travel	Não

Transaction

Representa os dados da transação.

Campos	Descrição	Tipo	Obrigatório
code	Código único da transação	String	Sim
date	Data da transação	DateTime	Sim
email	E-mail associado à transação	String	Sim
status	Status da transação	Integer	Não
ipAddress	Endereço IP do cliente	String	Não
origin	Origem da transação: APP, WEBSITE, TELEVENDAS, etc	String	Não
observation	Observações adicionais	String	Não

Transaction Value

Representa o valor total da transação.

Campos	Descrição	Tipo	Obrigatório
totalValue	Valor total da transação	Float	Sim

Device

Representa informações do dispositivo utilizado na transação.

Campos	Descrição	Tipo	Obrigatório
fingerprint	Identificador único do dispositivo	Fingerprint	Sim

Fingerprint

Representa as informações de identificação do dispositivo utilizado na transação.

Campos	Descrição	Tipo	Obrigatório
sessionId	Identificador único da sessão do dispositivo	Guid	Sim

Billing

Representa as informações de cobrança.

Campos	Descrição	Tipo	Obrigatório
type	Tipo de pessoa	Integer	Não
name	Nome do cliente	String	Sim
email	E-mail do cliente	String	Não
gender	Gênero do cliente	String	Não
birthdate	Data de nascimento	DateTime	Não
documents	Documentos associados ao cliente	Document Array	Sim
address	Endereço de cobrança	Address	Não
phones	Telefones associados ao cliente	Phone Array	Sim

Shipping

Representa as informações de envio.

Campos	Descrição	Tipo	Obrigatório
type	Tipo de pessoa	Integer	Não
price	Preço do envio	Float	Sim
name	Nome do destinatário	String	Sim
email	E-mail do destinatário	String	Não
gender	Gênero do destinatário	String	Não
birthdate	Data de nascimento do destinatário	DateTime	Não
clientId	Identificador interno do cliente (quem fez a transação)	String	Não
deliveryType	Tipo de entrega	Integer	Sim
deliveryTime	Tempo estimado de entrega	String	Não
documents	Documentos associados ao destinatário	Document Array	Não
address	Endereço de envio	Address	Não
phones	Telefones associados	Phone Array	Não

Item

Representa um item da transação.

Campos	Descrição	Tipo	Obrigatório
code	Código do item interno do Cliente	String	Não
name	Nome do item	String	Não
description	Descrição do item	String	Não
categoryId	ID da categoria do item interno do Cliente	Integer	Não
categoryName	Nome da categoria do item (tabela de exemplo no Glossário)	String	Não
barCode	Código de barras do item	String	Não
value	Valor do item	Float	Sim
quantity	Quantidade do item	Integer	Sim
isGift	Indica se o item é um presente	Boolean	Não
sellerName	Nome do vendedor	String	Não
sellerSegment	Segmento do vendedor	String	Não
isMarketPlace	Indica se é um marketplace	String	Não
shippingCompany	Empresa de envio	String	Não
sellerDocument	Documento do vendedor	Document	Sim

Payment

Representa um método de pagamento.

Campos	Descrição	Tipo	Obrigatório
type	Tipo de pagamento	Integer	Sim
value	Valor do pagamento	Float	Sim
currency	Moeda utilizada	Integer	Não
sequential	Número sequencial do pagamento	Integer	Não
paymentDate	Data do pagamento	DateTime	Não
installments	Número de parcelas	Integer	Não
payableType	Categoria do pagamento dentro do segmento: VOUCHER, SUBSCRIPTION, etc	String	Não
interestRate	Taxa de juros aplicada ao pagamento	Float	Não
interestValue	Valor dos juros aplicados	Float	Não
visaCheckoutUserId	Identificador do usuário no Visa Checkout	String	Não
digitalWalletCode	Código da carteira digital utilizada	String	Não
voucherOrderOrigin	Origem do pedido do voucher	String	Não
subAcquirer	Subadquirente responsável pelo pagamento	String	Não
bankAuthentication	Informações de autenticação bancária	String	Não
card	Informações do cartão de crédito	Card	Sim

Card

Representa as informações de um cartão de crédito.

Campos	Descrição	Tipo	Obrigatório
ownerName	Nome do titular do cartão	String	Sim
number	Número do cartão	String	Não
hash	Hash do número do cartão	String	Não
bin	BIN (Bank Identification Number) do cartão	String	Sim
end	Últimos dígitos do cartão	String	Sim
type	Tipo do cartão	Integer	Não
expirationDate	Data de expiração do cartão	String	Não
document	Documento associado ao cartão	Document	Não

Document

Representa um documento associado a uma entidade.

Campos	Descrição	Tipo	Obrigatório
type	Tipo do documento	Integer	Sim
number	Número do documento	String	Sim
documentTypeCustomer	Tipo de cliente associado ao documento	String	Não
authority	Autoridade emissora do documento	String	Não
authorityState	Estado da autoridade emissora	String	Não
issueDate	Data de emissão do documento	String	Não

Address

Representa um endereço.

Campos	Descrição	Tipo	Obrigatório
type	Tipo do endereço	String	Sim
addressId	Identificador do endereço	String	Não
street	Nome da rua	String	Sim
number	Número do endereço	String	Sim
district	Bairro	String	Não
city	Cidade	String	Sim
state	Estado	String	Sim
zipcode	Código postal (00000-000)	String	Sim
country	País	String	Sim
additionalInformation	Informações adicionais	String	Não
reference	Referência do endereço	String	Não
latitude	Latitude do endereço	String	Não
longitude	Longitude do endereço	String	Não

Phone

Representa as informações de um telefone associado a uma entidade.

Campos	Descrição	Tipo	Obrigatório
type	Tipo do telefone	Integer	Não
countryCode	Código do país do telefone	String	Não
areaCode	Código de área do telefone	String	Sim
number	Número do telefone	String	Sim
extension	Ramal associado ao telefone	String	Não

AirTravel

Representa as informações da viagem aérea

Campos	Descrição	Tipo	Obrigatório
passengers	Lista de passageiros da viagem aérea	Passenger Array	Sim
connections	Lista de conexões/trechos do itinerário	Connection Array	Sim

Passenger

Representa as informações do passageiro

Campos	Descrição	Tipo	Obrigatório
name	Nome do passageiro	String	Sim
documentType	Tipo do documento	Integer	Sim
documentNumber	Número do documento	String	Sim
companyMileCard	Cartão de milhagem da empresa	String	Não
MileCard	Cartão de milhagem pessoal	String	Não
gender	Gênero do passageiro	String	Não
birthDate	Data de nascimento	DateTime	Não
cpf	CPF do passageiro	String	Não

Connection

Representa as informações da conexão

Campo	Descrição	Tipo	Obrigatório
company	Companhia aérea	String	Não
flightNumber	Número do voo	Integer	Não
date	Data do voo	DateTime	Sim
seatClass	Classe do assento	String	Não
origin	Aeroporto de origem	String	Sim
destination	Aeroporto de destino	String	Sim
boarding	Data/hora de embarque	DateTime	Sim
arriving	Data/hora de chegada	DateTime	Sim
fareClass	Classe tarifária	String	Não

Exemplo Request

POST https://homologapix.clearsale.com.br/connect/v1/Integration/{{integrationId}}
Accept: application/json
Content-Type: application/json

{
  "transaction": {
    "code": "string",
    "date": "2025-09-25T15:42:34.935Z",
    "email": "string",
    "status": 0,
    "ipAddress": "string",
    "origin": "string",
    "observation": "string"
  },
  "transactionValue": {
    "totalValue": 0
  },
  "device": {
    "fingerprint": {
      "sessionId": "string"
    }
  },
  "billing": {
    "type": 0,
    "name": "string",
    "email": "string",
    "gender": "string",
    "birthdate": "2025-09-25T15:42:34.935Z",
    "documents": [
      {
        "type": 0,
        "number": "string",
        "documentTypeCustomer": "string",
        "authority": "string",
        "authorityState": "string",
        "issueDate": "string"
      }
    ],
    "address": {
      "type": "string",
      "addressId": "string",
      "street": "string",
      "number": "string",
      "district": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "country": "string",
      "additionalInformation": "string",
      "reference": "string",
      "latitude": "string",
      "longitude": "string"
    },
    "phones": [
      {
        "type": 0,
        "countryCode": "string",
        "areaCode": "string",
        "number": "string",
        "extension": "string"
      }
    ]
  },
  "shipping": {
    "type": 0,
    "price": 0,
    "name": "string",
    "email": "string",
    "gender": "string",
    "birthdate": "2025-09-25T15:42:34.935Z",
    "clientId": "string",
    "deliveryType": 0,
    "deliveryTime": "string",
    "documents": [
      {
        "type": 0,
        "number": "string",
        "documentTypeCustomer": "string",
        "authority": "string",
        "authorityState": "string",
        "issueDate": "string"
      }
    ],
    "address": {
      "type": "string",
      "addressId": "string",
      "street": "string",
      "number": "string",
      "district": "string",
      "city": "string",
      "state": "string",
      "zipcode": "string",
      "country": "string",
      "additionalInformation": "string",
      "reference": "string",
      "latitude": "string",
      "longitude": "string"
    },
    "phones": [
      {
        "type": 0,
        "countryCode": "string",
        "areaCode": "string",
        "number": "string",
        "extension": "string"
      }
    ]
  },
  "items": [
    {
      "code": "string",
      "name": "string",
      "description": "string",
      "categoryId": 0,
      "categoryName": "string",
      "barCode": "string",
      "value": 0,
      "quantity": 0,
      "isGift": true,
      "sellerName": "string",
      "sellerSegment": "string",
      "isMarketPlace": "string",
      "shippingCompany": "string",
      "sellerDocument": {
        "type": 0,
        "number": "string",
        "documentTypeCustomer": "string",
        "authority": "string",
        "authorityState": "string",
        "issueDate": "string"
      }
    }
  ],
  "payments": [
    {
      "type": 0,
      "value": 0,
      "currency": 0,
      "sequential": 0,
      "paymentDate": "2025-09-25T15:42:34.935Z",
      "installments": 0,
      "payableType": "string",
      "interestRate": 0,
      "interestValue": 0,
      "visaCheckoutUserId": "string",
      "digitalWalletCode": "string",
      "voucherOrderOrigin": "string",
      "subAcquirer": "string",
      "bankAuthentication": "string",
      "card": {
        "ownerName": "string",
        "number": "string",
        "hash": "string",
        "bin": "string",
        "end": "string",
        "type": 0,
        "expirationDate": "string",
        "document": {
          "type": 0,
          "number": "string",
          "documentTypeCustomer": "string",
          "authority": "string",
          "authorityState": "string",
          "issueDate": "string"
        }
      }
    }
  ],
  "airTravel": {
    "passengers": [
      {
        "name": "string",
        "documentType": 0,
        "documentNumber": "string",
        "companyMileCard": "string",
        "mileCard": "string",
        "gender": "string",
        "birthDate": "2025-09-25T15:42:34.935Z",
        "cpf": "string"
      }
    ],
    "connections": [
      {
        "company": "string",
        "flightNumber": 0,
        "date": "2025-09-25T15:42:34.935Z",
        "seatClass": "string",
        "origin": "string",
        "destination": "string",
        "boarding": "2025-09-25T15:42:34.935Z",
        "arriving": "2025-09-25T15:42:34.935Z",
        "fareClass": "string"
      }
    ]
  }
}

POST Response

Representa a resposta de execução da integração. Caso tenha contratado mais de um módulo, pode receber todos de uma vez. O que não tiver contratado, não será retornado.

Result

Campos	Descrição	Tipo	Obrigatório
executionId	ID da execução	Guid	Sim
analysisId	ID da análise	Guid	Sim
transactionId	ID da transação	String	Sim
insights	Resultados de insights	Insights Result	Não

Insights Result

Representa os insights gerados pela análise.

Campos	Descrição	Tipo	Obrigatório
status	Status dos insights	String	Sim
result	Lista de insights gerados	Insight Array	Não

Insight

Representa um insight gerado pela análise.

Campos	Descrição	Tipo	Obrigatório
code	Código do insight	String	Sim
description	Descrição do insight	String	Sim
type	Tipo do insight	String	Sim
category	Categoria do insight	String	Sim
relevance	Relevância do insight	String	Sim
relatedTo	Entidade ou elemento relacionado ao insight	String Array	Sim

JSON

{
  "executionId": "string",
  "analysisId": "string",
  "transactionId": "string",
  "insights": {
    "status": "string",
    "result": [
      {
        "code": "string",
        "description": "string",
        "type": "string",
        "category": "string",
        "relevance": "string",
        "relatedTo": [
          "string"
        ]
      }
    ]
  }
}

GET Response

Representa a resposta de execução da consulta da análise.

Result

Campos	Descrição	Tipo	Obrigatório
analysisId	ID da análise	Guid	Sim
transactionId	ID da transação	String	Sim
insights	Resultados de insights	Insights Result	Não

Insights Result

Representa os insights gerados pela análise.

Campos	Descrição	Tipo	Obrigatório
status	Status dos insights	String	Sim
result	Lista de insights gerados	Insight Array	Não

Insight

Representa um insight gerado pela análise.

Campos	Descrição	Tipo	Obrigatório
code	Código do insight	String	Sim
description	Descrição do insight	String	Sim
type	Tipo do insight	String	Sim
category	Categoria do insight	String	Sim
relevance	Relevância do insight	String	Sim
relatedTo	Entidade ou elemento relacionado ao insight	String Array	Sim

JSON

{
  "analysisId": "string",
  "transactionId": "string",
  "insights": {
    "status": "string",
    "result": [
      {
        "code": "string",
        "description": "string",
        "type": "string",
        "category": "string",
        "relevance": "string",
        "relatedTo": [
          "string"
        ]
      }
    ]
  }
}

Response com erro

Representa os detalhes de um problema retornado pela API em caso de erro.

Campos	Descrição	Tipo	Obrigatório
type	URI que identifica o tipo de problema específico. Pode ser usado para categorizar o erro.	String	Não
title	Título descritivo do problema	String	Sim
status	Código de status HTTP associado ao problema	Integer	Sim
errors	Erros de validação	Object	Sim
instance	URI que identifica a instância específica do problema	String	Não

JSON

{
  "errors": {
    "string": [
      "string"
    ]
  },
  "type": "string",
  "title": "string",
  "status": 0,
  "traceId": "string"
}

Funcionamento do Módulo Insights

Schema Request

Transaction

Transaction Value

Device

Fingerprint

Billing

Shipping

Item

Payment

Card

Document

Address

Phone

AirTravel

Passenger

Connection

Exemplo Request

POST Response

Result

Insights Result

Insight

JSON

GET Response

Result

Insights Result

Insight

JSON

Response com erro

JSON

Funcionamento do Módulo `Insights`