Integração
Documentação para a integração de pedidos (transacional) da Connect.
POST Integration/{integrationId}
{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:
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 |
| 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 |
| 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 |
| 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": "0f3a0a44-5e7b-4cdd-a2d0-e0b385fc049e",
"date": "2025-09-25 15:42:34",
"email": "[email protected]",
"status": 1,
"ipAddress": "192.168.0.45",
"origin": "Web",
"observation": "Purchase completed successfully"
},
"transactionValue": {
"totalValue": 249.90
},
"device": {
"fingerprint": {
"sessionId": "0f3a0a44-5e7b-4cdd-a2d0-e0b385fc049e"
}
},
"billing": {
"type": 1,
"name": "John Doe",
"email": "[email protected]",
"gender": "M",
"birthdate": "1988-04-12",
"documents": [
{
"type": 1,
"number": "01234567890",
"documentTypeCustomer": "CPF",
"authority": "SSP",
"authorityState": "SP",
"issueDate": "2010-05-20"
}
],
"address": {
"type": "Avenida",
"addressId": "ADDR-001",
"street": "Av. Paulista",
"number": "1000",
"district": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"zipcode": "01310-100",
"country": "Brazil",
"additionalInformation": "Apartment 45",
"reference": "Near MASP Museum",
"latitude": "-23.561684",
"longitude": "-46.655981",
"fullAddress": "Av. Paulista, 1000 - Bela Vista, São Paulo/SP"
},
"phones": [
{
"type": 1,
"countryCode": "55",
"areaCode": "11",
"number": "912345678",
"extension": ""
}
]
},
"shipping": {
"type": 1,
"price": 29.90,
"name": "Jane Doe",
"email": "[email protected]",
"gender": "F",
"birthdate": "1990-07-22",
"clientId": "CLIENT-789",
"deliveryType": 2,
"deliveryTime": "3 business days",
"documents": [
{
"type": 1,
"number": "98765432100",
"documentTypeCustomer": "CPF",
"authority": "SSP",
"authorityState": "RJ",
"issueDate": "2012-08-15"
}
],
"address": {
"type": "Rua",
"addressId": "ADDR-002",
"street": "Rua das Flores",
"number": "250",
"district": "Centro",
"city": "Rio de Janeiro",
"state": "RJ",
"zipcode": "20000-000",
"country": "Brazil",
"additionalInformation": "House",
"reference": "Near Central Station",
"latitude": "-22.9035",
"longitude": "-43.2096",
"fullAddress": "Rua das Flores, 250 - Centro, Rio de Janeiro/RJ"
},
"phones": [
{
"type": 1,
"countryCode": "55",
"areaCode": "21",
"number": "998765432",
"extension": ""
}
]
},
"items": [
{
"code": "ITEM-001",
"name": "Wireless Headphones",
"description": "Bluetooth over-ear headphones with noise cancellation",
"categoryId": 101,
"categoryName": "Electronics",
"barCode": "7891234567890",
"value": 220.00,
"quantity": 1,
"isGift": false,
"sellerName": "TechStore",
"sellerSegment": "Electronics",
"isMarketPlace": "true",
"shippingCompany": "FastDelivery",
"sellerDocument": {
"type": 2,
"number": "11222333444455",
"documentTypeCustomer": "CNPJ",
"authority": "Junta Comercial",
"authorityState": "SP",
"issueDate": "2005-03-10"
}
}
],
"payments": [
{
"type": 1,
"value": 249.90,
"currency": 0,
"sequential": 1,
"paymentDate": "2025-09-25 15:42:34",
"installments": 3,
"payableType": "CreditCard",
"interestRate": 2.5,
"interestValue": 5.00,
"visaCheckoutUserId": "VISA-USER-123",
"digitalWalletCode": "WALLET-456",
"voucherOrderOrigin": "PROMO2025",
"subAcquirer": "SubBank",
"bankAuthentication": "Auth123",
"card": {
"ownerName": "John Doe",
"number": "123456******1234",
"hash": "12345678945612301234569874563210",
"bin": "123456",
"end": "1234",
"type": 1,
"expirationDate": "04/26",
"document": {
"type": 1,
"number": "01234567890",
"documentTypeCustomer": "CPF",
"authority": "SSP",
"authorityState": "SP",
"issueDate": "2010-05-20"
}
}
}
],
"airTravel": {
"passengers": [
{
"name": "Carlos Silva",
"documentType": 1,
"documentNumber": "01234567890",
"companyMileCard": "LATAM",
"mileCard": "LATAM-12345",
"gender": "M",
"birthDate": "1985-11-10",
"cpf": "01234567890"
}
],
"connections": [
{
"company": "LATAM Airlines",
"flightNumber": 3456,
"date": "2025-09-25T15:42:34.935Z",
"seatClass": "Economy",
"origin": "GRU",
"destination": "MIA",
"boarding": "2025-09-25T14:00:00.000Z",
"arriving": "2025-09-25T22:00:00.000Z",
"fareClass": "Y"
}
]
},
"paymentLink": {
"flagInternationalTransaction": "true",
"linkURL": "https://pay.example.com/checkout/TXN-987654",
"linkDevice": "Mobile",
"cluster": "Cluster-A"
},
"seller": {
"sellerID": "SELLER-001",
"sellerScore": "4.8",
"sellerCNAE": "4751200",
"sellerAccreditationDate": "2025-12-12T13:29:22.039Z",
"sellerMerchantEmail": "[email protected]",
"sellerMerchantDocument": "11222333444455",
"sellerMerchantDDD": "11",
"sellerMerchantPhoneNumber": "34567890",
"sellerAccessionDate": "2025-12-12T13:29:22.039Z",
"sellerPaymentDays": 30,
"sellerPartnersName": "Tech Partners Ltda",
"sellerCluster": "Electronics"
}
}Updated about 2 months ago
