ClpzCheckout
Documentacao de Integracao

Guia completo para plataformas de rastreamento que desejam integrar com o ClpzCheckout. Capture UTMs, receba eventos de venda em tempo real e atribua conversoes com precisao.

PIX PaymentsUTM TrackingReal-time EventsMulti-platform

O que e o ClpzCheckout?

O ClpzCheckout e uma plataforma de checkout otimizada para vendas via PIX no Brasil. Cada vendedor cria checkouts personalizados para seus produtos, e o sistema gerencia todo o fluxo de pagamento, captura de dados do cliente e rastreamento de conversoes.

Como funciona a integracao com trackers?

O ClpzCheckout utiliza um modelo push-based: quando eventos ocorrem (PIX gerado, venda confirmada, reembolso), o sistema envia automaticamente os dados para as plataformas de rastreamento configuradas pelo vendedor.

Vendedor configura

Adiciona o token da plataforma no painel

Visitante acessa

UTMs sao capturados automaticamente da URL

Evento ocorre

PIX gerado ou pagamento confirmado

Dados enviados

POST HTTP com pedido + UTMs para sua API

Plataformas integradas

UTMifyAtivo

Atribuicao de vendas via UTMs

api.utmify.com.br

XtrackyAtivo

Rastreamento avancado de conversoes

api.xtracky.com

Sua plataforma?Aberto

Envie sua documentacao para integrarmos

—

Fluxo de Dados

O diagrama abaixo mostra o caminho completo dos dados, desde a chegada do visitante ate o envio dos eventos para as plataformas de rastreamento.

Visitante acessa o checkout

O visitante acessa a URL do checkout (ex: seudominio.com/oferta?utm_source=facebook&utm_medium=cpc). Os parametros UTM sao extraidos automaticamente da URL.

Dados do visitante registrados

Fingerprint, IP, dispositivo, navegador, sistema operacional, idioma e referrer sao capturados. Todos os parametros UTM (source, medium, campaign, content, term) e o parametro src sao armazenados.

Cliente preenche o formulario

Nome, email, CPF (e opcionalmente telefone e endereco) sao coletados. Os dados do cliente sao vinculados ao registro do visitante.

PIX gerado

EVENTO DISPARADO

O codigo PIX e gerado pela gateway de pagamento. O pedido e criado com status 'pending'. Evento waiting_payment e enviado para todas as plataformas de rastreamento ativas.

Pagamento confirmado

EVENTO DISPARADO

A gateway de pagamento confirma o PIX via webhook. O status do pedido muda para 'paid'. Evento paid e enviado para todas as plataformas de rastreamento ativas, incluindo todos os parametros UTM do visitante.

Dados entregues ao tracker

Sua plataforma recebe um POST HTTP com todos os dados do pedido, cliente e parametros UTM. Voce pode atribuir a conversao a campanha/anuncio correto.

Confirmacao de pagamento

O ClpzCheckout utiliza dois mecanismos redundantes para garantir que nenhum pagamento seja perdido:

Webhook (primario)

A gateway de pagamento envia uma notificacao automatica quando o PIX e pago. O webhook e verificado com assinatura criptografica HMAC-SHA256.

Polling (fallback)

O checkout do cliente verifica o status a cada 3 segundos. Caso o webhook falhe, o polling garante que o pagamento seja detectado e os eventos sejam disparados.

Eventos

Cada evento e enviado como um POST HTTP para a API da sua plataforma no momento em que ocorre. Os eventos sao enviados de forma assincrona e independente — falhas em uma plataforma nao afetam outras.

⏳

Aguardando Pagamentowaiting_payment

Cliente gera o codigo PIX no checkout

✓

Venda Aprovadapaid

Pagamento PIX confirmado pela gateway

Pagamento Falhoufailed

PIX expirou ou pagamento foi recusado

↩

Reembolsorefunded

Pedido foi reembolsado pelo vendedor

Deduplicacao

Cada evento e enviado uma unica vez por pedido. O ClpzCheckout garante que o mesmo orderId + status nao sera reenviado, mesmo em cenarios de redundancia (webhook + polling).

Campos de Dados

Abaixo estao todos os campos enviados nos eventos. O formato exato pode variar por plataforma (veja as secoes especificas), mas os dados sao equivalentes.

Campo	Tipo	Obrig.	Descricao	Exemplo
`orderId`	string	Sim	Identificador unico do pedido (CUID)	`cm4abc123def456`
`status`	string	Sim	Status do evento	`paid`
`amount`	integer	Sim	Valor total em centavos (BRL). Ex: R$ 99,90 = 9990	`9990`
`customerName`	string	Sim	Nome completo do comprador	`Joao Silva`
`customerEmail`	string	Sim	Email do comprador	`joao@email.com`
`customerPhone`	string	Nao	Telefone do comprador (se coletado)	`+5511999999999`
`customerCpf`	string	Sim	CPF do comprador (somente numeros)	`12345678900`
`productId`	string	Sim	Identificador unico do produto	`cm4prod123`
`productName`	string	Sim	Nome do produto vendido	`Curso de Marketing Digital`
`checkoutTitle`	string	Sim	Titulo do checkout configurado pelo vendedor	`Oferta Black Friday`
`paymentMethod`	string	Sim	Metodo de pagamento utilizado	`pix`
`createdAt`	ISO 8601	Sim	Data e hora de criacao do pedido	`2025-03-11T14:30:00.000Z`
`approvedDate`	ISO 8601	Nao	Data e hora da aprovacao (apenas em eventos paid)	`2025-03-11T14:35:22.000Z`
`refundedAt`	ISO 8601	Nao	Data e hora do reembolso (apenas em eventos refunded)	`2025-03-12T10:00:00.000Z`

Parametros UTM

O ClpzCheckout captura automaticamente todos os parametros UTM da URL do checkout quando o visitante acessa a pagina. Esses parametros sao armazenados junto ao registro do visitante e enviados em todos os eventos de rastreamento.

Como os UTMs sao capturados

// URL do checkout com UTMs:
https://seudominio.com/oferta?utm_source=facebook&utm_medium=cpc&utm_campaign=bfriday&src=link_bio

// ClpzCheckout extrai automaticamente:
{ utm_source: "facebook", utm_medium: "cpc", utm_campaign: "bfriday", src: "link_bio" }

Parametros suportados

utm_sourceOrigem do trafego (ex: facebook, google, instagram)facebook

utm_mediumMidia da campanha (ex: cpc, email, social)cpc

utm_campaignNome da campanhablackfriday2025

utm_contentVariacao do anuncio ou conteudovideo_v2

utm_termPalavra-chave (geralmente em search ads)curso+marketing

srcParametro source generico (capturado da URL)link_bio

Persistencia

Os parametros UTM sao capturados na primeira visita e permanecem vinculados ao visitante durante toda a sessao. Mesmo que o usuario navegue ou recarregue a pagina, os UTMs originais sao mantidos e enviados junto com os eventos.

Integracao UTMify

Integrado

EndpointPOST https://api.utmify.com.br/api-credentials/orders

AutenticacaoHeader x-api-token: {token-do-usuario}

Identificadorplatform: "ClpzCheckout"

Content-Typeapplication/json

Mapeamento de status

waiting_payment→waiting_payment

paid→paid

refused→refused

refunded→refunded

Exemplo de payload

{
  "isTest": false,
  "status": "paid",
  "orderId": "cm4abc123def456",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "phone": "+5511999999999",
    "country": "BR",
    "document": "12345678900"
  },
  "platform": "ClpzCheckout",
  "products": [
    {
      "id": "cm4prod123",
      "name": "Curso de Marketing Digital",
      "planId": "cm4prod123",
      "planName": "Oferta Black Friday",
      "quantity": 1,
      "priceInCents": "9990"
    }
  ],
  "createdAt": "2025-03-11T14:30:00.000Z",
  "commission": {
    "gatewayFeeInCents": "0",
    "totalPriceInCents": "9990",
    "userCommissionInCents": "9990"
  },
  "approvedDate": "2025-03-11T14:35:22.000Z",
  "refundedAt": null,
  "paymentMethod": "pix",
  "trackingParameters": {
    "sck": null,
    "src": "link_bio",
    "utm_source": "facebook",
    "utm_medium": "cpc",
    "utm_campaign": "blackfriday2025",
    "utm_content": "video_v2",
    "utm_term": null
  }
}

Integracao Xtracky

Integrado

EndpointPOST https://api.xtracky.com/api/integrations/api

AutenticacaoHeader Authorization: Bearer {data-token}

Identificadorplatform: "CLPZCHECKOUT"

Content-Typeapplication/json

Mapeamento de status

waiting_payment→waiting_payment

paid→paid

refused→failed

refunded→refunded

Campos enviados

orderId←orderId

amount←amount (centavos)

status←status (mapeado)

utm_source←utm_source do visitante (fallback: src)

leadName←customerName

leadEmail←customerEmail

leadPhone←customerPhone

leadDocument←customerCpf

Exemplo de payload

{
  "orderId": "cm4abc123def456",
  "amount": 9990,
  "status": "paid",
  "utm_source": "facebook",
  "platform": "CLPZCHECKOUT",
  "leadName": "Joao Silva",
  "leadEmail": "joao@email.com",
  "leadPhone": "+5511999999999",
  "leadDocument": "12345678900"
}

Nova Integracao

Quer integrar sua plataforma de rastreamento com o ClpzCheckout? Seguimos um processo simples para adicionar novas integracoes.

Requisitos tecnicos

ProtocoloPOST HTTP com body JSON

Content-Typeapplication/json

AutenticacaoAPI Token via header (x-api-token, Authorization Bearer, ou header customizado)

Campos minimosorderId, amount, status

RecomendadoscustomerName, customerEmail, customerCpf, utm_source, utm_medium, utm_campaign

DeduplicacaoRecomendado suportar deduplicacao por orderId para evitar eventos duplicados

Exemplo generico

// Requisicao HTTP esperada pela sua plataforma:

POST https://sua-api.com/webhook/clpzcheckout
Content-Type: application/json
Authorization: Bearer {token-do-usuario}

{
  "orderId": "cm4abc123def456",
  "amount": 9990,
  "status": "paid",
  "customerName": "Joao Silva",
  "customerEmail": "joao@email.com",
  "customerCpf": "12345678900",
  "customerPhone": "+5511999999999",
  "productId": "cm4prod123",
  "productName": "Curso de Marketing Digital",
  "paymentMethod": "pix",
  "createdAt": "2025-03-11T14:30:00.000Z",
  "approvedDate": "2025-03-11T14:35:22.000Z",
  "utm_source": "facebook",
  "utm_medium": "cpc",
  "utm_campaign": "blackfriday2025",
  "utm_content": "video_v2",
  "utm_term": null,
  "src": "link_bio"
}

O que precisamos da sua plataforma

1URL do endpoint que recebe webhooks/postbacks

2Metodo de autenticacao (tipo de token, nome do header)

3Lista de campos aceitos com tipos e descricoes

4Mapeamento de status de pagamento esperado

5Exemplo de payload aceito pelo endpoint

6Documentacao publica da API (se disponivel)

API JSON

Toda a documentacao tambem esta disponivel em formato JSON via API publica. Use este endpoint para consumir a documentacao programaticamente.

GET https://clpzcheckout.cloud/api/docs

MetodoGET

AutenticacaoNenhuma (endpoint publico)

CORSAccess-Control-Allow-Origin: *

Cachepublic, max-age=3600 (1 hora)

Content-Typeapplication/json

O JSON retornado contem: definicoes de eventos, campos de dados, configuracoes por plataforma (UTMify, Xtracky), exemplos de payload e requisitos para novas integracoes.

ClpzCheckoutDocumentacao de Integracao

O que e o ClpzCheckout?

Como funciona a integracao com trackers?

Plataformas integradas

Fluxo de Dados

Confirmacao de pagamento

Eventos

Campos de Dados

Parametros UTM

Como os UTMs sao capturados

Parametros suportados

Integracao UTMify

Mapeamento de status

Exemplo de payload

Integracao Xtracky

Mapeamento de status

Campos enviados

Exemplo de payload

Nova Integracao

Requisitos tecnicos

Exemplo generico

O que precisamos da sua plataforma

API JSON

ClpzCheckout
Documentacao de Integracao