POST Integration/`{integrationId}`

A rota /Integration/integrationId permite integrar informações específicas de uma transação identificada pelo integrationId.

Ela recebe dados detalhados sobre a transação, como valores, dispositivos, informações de cobrança e envio, além de itens e pagamentos. Após o processamento, a rota retorna uma análise com resultados, incluindo decisões, verificações biométricas e insights. É necessário autenticar-se com um token de segurança para utilizá-la.

Autenticação do Endpoint

O endpoint exige autenticação, o cliente deve fornecer as credenciais necessárias para que o sistema consiga realizar a autenticação e enviar os dados com sucesso.

O tipo de autenticação suportado é o Bearer Token (JWT).

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

📘
Informações sobre o processo de autenticação e obtenção do token podem ser consultados em Autenticação.

Identificação de Integração por Módulo

Cada módulo do sistema possui um integrationId específico que o identifica de forma única, são eles:

Módulo	Tipo
Decision	Síncrono
Score	Síncrono
MFA	Assíncrono
Biolink	Assíncrono
Insights	Síncrono

Observação: É possível compor múltiplos módulos, o que proporciona maior flexibilidade e granularidade na integração entre funcionalidades, permitindo atender a cenários mais complexos de forma eficiente.

Módulos Síncronos e Assíncronos

Funcionamento de Módulos Síncronos

Os módulos síncronos, realizam 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 e determinar o status da requisição.

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.

Funcionamento de Módulos Assíncronos

Os módulos assíncronos processam as solicitações de forma não imediata, permitindo que a análise dos dados ocorra em segundo plano após o recebimento da requisição. Durante esse processo, são cruzadas diversas informações relevantes para o cálculo do score e a definição do status da solicitação.

Após a conclusão do processamento, o sistema realiza uma notificação automática via webhook, enviando os resultados para o endpoint previamente disponibilizado pelo cliente.

📘
Endereço dos nossos serviços:
Homologação:
POST https://homologapix.clearsale.com.br/connect/v1/integration/integrationId
Produção:
POST https://apix.clearsale.com.br/connect/v1/integration/integrationId

Configuração para Ambiente de Homologação

O ambiente de Homologação é utilizado para testes de integração entre sistemas. Por padrão, os retornos são gerados com valores fixos, mas é possível solicitar configurações customizadas nos módulos que oferecem essa opção.

A definição do score e do status é baseada no dígito final do campo numérico presente no documento de billing, permitindo simular diferentes cenários de forma controlada.

Módulos Disponíveis

Decision (padrão e customizado)
Score (padrão e customizado)
MFA (padrão)
Biolink (padrão e customizado)
Insights (padrão)

Configuração Padrão do Score

Documento (dígito final)	Faixa de Score (Gerado aleatoriamente)
0	0.0000 – 0.1000
1	0.1001 – 0.2000
2	0.2001 – 0.3000
3	0.3001 – 0.4000
4	0.4001 – 0.5000
5	0.5001 – 0.6000
6	0.6001 – 0.7000
7	0.7001 – 0.8000
8	0.8001 – 0.9000
9	0.9001 – 0.9999

Configuração Padrão do Status

Documento (dígito final)	Status
0	APA – Aprovação Automática
1	RPA – Reprovação Automática
2	AMA – Em Fila
3	FRD – Fraude Confirmada
4	APM – Aprovado
5	APP – Aprovado por Política
6	AME – Análise Manual Externa
7	APB – Aprovado por Biometria
8	APS - Aprovado por SMS
9	ACT - Aprovado por Contingência

Configuração de Webhook

Para os módulos MFA e Biolink, é possível configurar um webhook para receber notificações ou resultados diretamente em um endpoint definido pelo cliente.

Essa funcionalidade permite:

Integração em tempo real com sistemas internos.
Automação de processos baseados nos eventos retornados.
Maior controle sobre os testes e respostas do ambiente de homologação.

Para habilitar o webhook, informe:

URL do endpoint que receberá as requisições.
Formato esperado JSON.
Autenticação, caso necessária (Basic, ApiKey, Jwt).

Schema Request

Representa a requisição geral para integração. A obrigatoriedade de alguns campos pode variar, e essas particularidades serão detalhadas no tópico específico de cada módulo.

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
paymentLink	Informaçãoes sobre link de pagamento	PaymentLink	Não
seller	Informações sobre o seller/parceiro	Seller	Não

Transaction

Representa os dados da transação.

Campos	Descrição	Tipo	Tamanho	Obrigatório
code	Código único da transação	String	50	Sim
date	Data da transação	DateTime	-	Sim
email	E-mail associado à transação	String	150	Não
status	Status da transação	Integer	-	Não
ipAddress	Endereço IP do cliente	String	150	Não
origin	Origem da transação: APP, WEBSITE, TELEVENDAS, etc	String	150	Não
observation	Observações adicionais	String	8000	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	Tamanho	Obrigatório
type	Tipo de pessoa	Integer	-	Não
name	Nome do cliente	String	500	Sim
email	E-mail do cliente	String	150	Não
gender	Gênero do cliente	String	1	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	Tamanho	Obrigatório
type	Tipo de pessoa	Integer	-	Não
price	Preço do envio	Float	-	Não
name	Nome do destinatário	String	500	Sim
email	E-mail do destinatário	String	150	Não
gender	Gênero do destinatário	String	1	Não
birthdate	Data de nascimento do destinatário	DateTime	-	Não
clientId	Identificador interno do cliente (quem fez a transação)	String	200	Não
deliveryType	Tipo de entrega	Integer	-	Sim
deliveryTime	Tempo estimado de entrega	String	100	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	Tamanho	Obrigatório
code	Código do item interno do Cliente	String	50	Não
name	Nome do item	String	150	Não
description	Descrição do item	String	500	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	200	Não
barCode	Código de barras do item	String	30	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	150	Não
sellerSegment	Segmento do vendedor	String	150	Não
isMarketPlace	Indica se é um marketplace	String		Não
shippingCompany	Empresa de envio	String	150	Não
sellerDocument	Documento do vendedor	Document	-	Não

Payment

Representa um método de pagamento.

Campos	Descrição	Tipo	Tamanho	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	150	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	200	Não
digitalWalletCode	Código da carteira digital utilizada	String	200	Não
voucherOrderOrigin	Origem do pedido do voucher	String	200	Não
subAcquirer	Subadquirente responsável pelo pagamento	String	200	Não
bankAuthentication	Informações de autenticação bancária	String	200	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	Tamanho	Obrigatório
ownerName	Nome do titular do cartão	String	150	Sim
number	Número do cartão	String	200	Não
hash	Hash do número do cartão	String	50	Não
bin	BIN (Bank Identification Number) do cartão	String	12	Sim
end	Últimos dígitos do cartão	String	4	Sim
type	Tipo do cartão	Integer	-	Não
expirationDate	Data de expiração do cartão	String	50	Não
document	Documento associado ao cartão	Document	-	Não

Document

Representa um documento associado a uma entidade.

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

Address

⚠️
Regra de obrigatoriedade:
Quando o campo fullAddress é informado, os demais campos do objeto Address tornam-se opcionais. Caso o fullAddress não seja informado, os campos type, street, number, city, state, zipCode e country tornam-se obrigatórios.

Representa um endereço.

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

Phone

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

Campos	Descrição	Tipo	Tamanho	Obrigatório
type	Tipo do telefone	Integer	-	Não
countryCode	Código do país do telefone	String	5	Não
areaCode	Código de área do telefone	String	5	Sim
number	Número do telefone	String	15	Sim
extension	Ramal associado ao telefone	String	10	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	Tamanho	Obrigatório
name	Nome do passageiro	String	100	Sim
documentType	Tipo do documento	Integer	-	Sim
documentNumber	Número do documento	String	50	Sim
companyMileCard	Cartão de milhagem da empresa	String	50	Não
MileCard	Cartão de milhagem pessoal	String	50	Não
gender	Gênero do passageiro	String	1	Não
birthDate	Data de nascimento	DateTime	-	Não
cpf	CPF do passageiro	String	11	Não

Connection

Representa as informações da conexão

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

PaymentLink

Representa as informações de link de pagamento

Campo	Descrição	Tipo	Tamanho	Obrigatório
flagInternationalTransaction	Flag de pedido internacional	String	200	Não
linkURL	Url do link	String	200	Não
linkDevice	Dispositivo gerador do link	String	200	Não
cluster	Cluster/segmentação	String	200	Não

Seller

Representa as informação do vendedor/parceiro

Campo	Descrição	Tipo	Tamanho	Obrigatório
sellerID	Identificador da loja/lojista	String	200	Não
sellerScore	Score do vendedor/parceiro	String	200	Não
sellerCNAE	Código de ramo de atividade (CNAE) do vendedor/parceiro	String	200	Não
sellerAccreditationDate	Data de credenciamento do vendedor/parceiro	DateTime	-	Não
sellerMerchantEmail	Email do representante do vendedor/parceiro	String	150	Não
sellerMerchantDocument	Documento do representante do vendedor/parceiro	String	50	Não
sellerMerchantDDD	DDD do telefone do representando do vendedor/parceiro	String	10	Não
sellerMerchantPhoneNumber	Número do telefone do representante do vendedor/parceiro	String	15	Não
sellerAccessionDate	Data de adesão no link do vendedor/parceiro	DateTime	-	Não
sellerPaymentDays	Número de dias para o pagamento ao vendedor/parceiro	Interger	-	Não
sellerPartnersName	Informações dos sócios do CNPJ	String	200	Não
sellerCluster	Cluster/segmentação de vendedores	String	200	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",
      "fullAddress": "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",
      "fullAddress": "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"
      }
    ]
  },
  "paymentLink": {
    "flagInternationalTransaction": "string",
    "linkURL": "string",
    "linkDevice": "string",
    "cluster": "string"
  },
  "seller": {
    "sellerID": "string",
    "sellerScore": "string",
    "sellerCNAE": "string",
    "sellerAccreditationDate": "2025-12-12T13:29:22.039Z",
    "sellerMerchantEmail": "string",
    "sellerMerchantDocument": "string",
    "sellerMerchantDDD": "string",
    "sellerMerchantPhoneNumber": "string",
    "sellerAccessionDate": "2025-12-12T13:29:22.039Z",
    "sellerPaymentDays": 0,
    "sellerPartnersName": "string",
    "sellerCluster": "string"
  }
}

POST Integration/{integrationId}

Autenticação do Endpoint

Identificação de Integração por Módulo

Módulos Síncronos e Assíncronos

Funcionamento de Módulos Síncronos

Funcionamento de Módulos Assíncronos

Configuração para Ambiente de Homologação

Módulos Disponíveis

Configuração Padrão do Score

Configuração Padrão do Status

Configuração de Webhook

Schema Request

Transaction

Transaction Value

Device

Fingerprint

Billing

Shipping

Item

Payment

Card

Document

Address

Phone

AirTravel

Passenger

Connection

PaymentLink

Seller

Exemplo Request

POST Integration/`{integrationId}`