Atribuição de receita

Conecte pedidos verificados ao tráfego e às campanhas por trás deles.

Os pedidos chegam ao Seean de duas formas: um conector nativo recebe os webhooks assinados de um provedor de pagamento, ou seu servidor envia pedidos e reembolsos verificados para a API de pedidos do Seean. Cada site relata em uma única moeda que você escolhe. Quando um pedido nomeia um visitante que o Seean conhece, a atribuição (toques, primeira e última fonte, página de destino, tempo até a compra) é derivada no servidor das visitas rastreadas desse visitante nos 90 dias anteriores ao pedido. Os campos fornecidos pela sua integração são usados apenas para visitantes sem visitas rastreadas.

Conectando um provedor de pagamento

Abra Settings → Integrations → Payment providers (Configurações → Integrações → Provedores de pagamento) no seu próprio site e selecione Enable (Ativar) em Creem, Mollie, Paddle, Polar, RevenueCat, Revolut, Shopify, Stripe, Superwall ou Whop. O painel lista os passos de configuração, a URL de webhook do site para esse provedor (https://events.seean.io/api/connect/<provider>/<site ID>) e os eventos a ativar; cole o segredo de assinatura do provedor e o Seean verifica cada entrega antes de armazená-la. Para Stripe, Polar e Paddle, Quick connect (Conexão rápida) cria o webhook a partir de uma chave de API que você cola uma vez; a chave não é armazenada. Após Save secret (Salvar segredo), o campo é limpo por segurança e a linha abaixo dele mostra Secret saved (ends in …) (Segredo salvo, termina em …) com os últimos quatro caracteres, para que você confirme que o segredo certo está armazenado; cole um novo valor apenas para substituí-lo. Os pedidos pagos e reembolsos então chegam automaticamente, e a linha de status mostra o último evento e qualquer erro. Uma conexão ou desconexão malsucedida mostra o motivo do servidor, inclusive os segundos de espera quando a requisição foi limitada por taxa. Os guias dos provedores abaixo trazem os passos de cada provedor, o trecho de atribuição, o comportamento de reembolso e moeda e os limites.

O Stripe oferece ainda uma seção separada, só para proprietários, Optional Stripe payment reads (Leituras opcionais de pagamentos do Stripe) após a conexão. Um controle de consentimento inicialmente desmarcado autoriza explicitamente a retenção de uma chave de leitura restrita para a fatura, os pagamentos e os reembolsos iniciais exatos do Checkout — não renovações nem preenchimento retroativo. A chave nunca é pré-preenchida nem retornada; apenas o proprietário vê o status de ativação, o modo teste/produção, a conta e o sufixo. Substituir exige novo consentimento. Remove read key (Remover chave de leitura) deixa intactos o webhook, os pedidos e os vínculos de pagamento existentes. A reconexão rápida/manual remove o acesso de leitura retido, enquanto a chave da conexão rápida continua sendo usada uma vez e descartada. Os controles em demonstração/ocupado ficam desativados; ações bem-sucedidas e trocas de provedor limpam a chave de leitura digitada. Veja o guia do Stripe para permissões, verificações de reembolso bem-sucedido, vínculo entre evento assinado/reenvio e recuperação explícita limitada de sessão única. Esta entrega de código não confirma a implantação em produção nem a recuperação histórica ao vivo.

Recuperação de entregas

Um conector nativo retorna 503 quando um reembolso chega antes do seu pedido (por até um dia após a criação do reembolso; depois disso o reembolso é confirmado e ignorado), quando uma consulta de pedido do Revolut falha ou quando a ingestão está temporariamente indisponível. Limites de taxa retornam 429. Essas respostas deixam a entrega elegível para as novas tentativas do provedor; o Seean não mantém uma segunda fila de webhooks. Depois que o pedido original é armazenado, reenviar o reembolso com o mesmo ID de reembolso o aplica uma única vez.

Verifique em Settings → Integrations → Payment providers o horário da última entrega e o erro de mapeamento ou consulta registrado. Corrija credenciais ou dados de pagamento inválidos na origem. Uma entrega bem-sucedida posterior limpa o último erro, então verifique também as entregas com falha no painel do provedor. Eventos não suportados e erros permanentes de payload/moeda são confirmados com 200; pedidos rejeitados não são armazenados.

Os cronogramas de nova tentativa e a expiração são controlados por cada provedor. Se as tentativas de entrega expirarem, use os controles de reenvio do provedor quando disponíveis, ou envie o pedido/reembolso verificado pela Order API com os identificadores originais. Falhas confirmadas anteriormente não são reenviadas automaticamente por essa mudança. As leituras opcionais do Stripe podem estabelecer vínculos de pagamento inicial a partir de eventos de Checkout assinados recém-entregues ou reenvios exatos; ativar a chave não inicia a recuperação histórica. Proprietários autenticados podem solicitar separadamente uma simulação de conciliação de sessão única e depois uma aplicação explícita por meio de uma integração personalizada; não há execução automática nem em todo o site. Arranjos não suportados com várias faturas/créditos e referências ausentes exigem revisão. Nunca crie um novo ID de pedido apenas para repetir um pagamento.

Enviando pedidos do seu servidor

Abra Settings → Integrations → Revenue e expanda Custom server integration (Order API) (Integração de servidor personalizada) para escolher a moeda de relatório e criar um segredo da API de pedidos. Use seu servidor ou o manipulador de webhook de pagamento para enviar pedidos verificados ao endpoint exibido. Mantenha o segredo no seu servidor; não o inclua no código do navegador. Esta é uma integração personalizada, não uma conexão automática com todos os provedores de checkout.

O rastreador expõe window.seean.attribution() com o ID do visitante, o caminho de destino, o caminho de conversão e a campanha. Envie esses campos ao seu servidor com o pedido: o ID do visitante é o que vincula o pedido às visitas do comprador. Sem ele, o pedido é registrado como não atribuído. Encaminhe eventos de pagamento somente depois de verificá-los com seu provedor.

Moeda de relatório

Cada site tem uma única moeda de relatório. Abra o menu abaixo de Reporting currency (Moeda de relatório) no cartão de integração de Receita e escolha um código ISO 4217 (USD por padrão); a seleção é salva automaticamente. Os valores são enviados nas unidades menores dessa moeda: 2900 é USD 29.00, o JPY não tem unidade menor, então 2900 é JPY 2,900, e o KWD usa três decimais, então 2900 é KWD 2.900. Um pedido em qualquer outra moeda é rejeitado com HTTP 400 e a mensagem Order currency EUR does not match the website's reporting currency USD (com os códigos envolvidos). O Seean não converte moedas.

Alterar a moeda de relatório não converte os pedidos que você já enviou. As análises os contam como excluídos, e a página de Receita mostra um aviso como “3 orders use another currency and are excluded from the USD totals.” Apenas os pedidos na moeda de relatório atual formam os totais.

Reembolsos

Os reembolsos são um livro-razão por pedido. Um reembolso pode cobrir todo o valor restante ou um amount parcial, carrega opcionalmente seu refundId para que novas tentativas sejam deduplicadas e pode carregar seu próprio carimbo de data/hora. Um reembolso que excede o valor restante é rejeitado com HTTP 400; um pedido aceita no máximo 50 reembolsos. Quando o total reembolsado atinge o valor do pedido, o pedido é marcado como reembolsado.

Os reembolsos reduzem a receita líquida no período do pedido original, não no período da data do reembolso. Um pedido de junho reembolsado em julho reduz o líquido de junho; julho não mostra nada a respeito. Revise o intervalo que contém o pedido.

Atribuição derivada

Para um pedido com visitante conhecido, o Seean lê as visitas desse visitante nos 90 dias anteriores ao carimbo de data/hora do pedido:

• Toques: o número de visitas nessa janela.
• Primeira fonte e Última fonte: o referrer ou utm_source da primeira e da última visita; Direct quando não há nenhum.
• Página de destino: a página de entrada da primeira visita.
• Tempo até a compra: do início da primeira visita até o pedido.
• Campanha: a campanha fornecida pela sua integração; caso contrário, o utm_campaign da visita marcada mais recente.

Se o visitante não tem nenhuma visita rastreada na janela, são usados a primeira fonte, a última fonte, os toques e o tempo até a compra fornecidos pela sua integração, e o pedido conta como atribuído apenas quando nomeia um visitante e um caminho de destino. Pedidos enviados sem ID de visitante são Unattributed (Não atribuídos). Pedidos registrados antes de a atribuição derivada existir são preenchidos uma vez a partir das visitas rastreadas do visitante; uma campanha fornecida pela sua integração é mantida.

Limites da atribuição

A ingestão de pedidos aceita históricos de até 2.000 eventos correspondentes dentro da janela de 90 dias. Ela examina no máximo 2.001 linhas para detectar estouro, com um orçamento de leitura de 1 MiB. Uma jornada completa salva pode ocupar até 64 KiB. Esses limites se aplicam ao histórico do visitante de cada pedido, não ao tráfego total de um site. O Seean salva todos os toques quando o histórico completo cabe; ele não descarta mais as visitas após a trigésima.

Se o histórico exceder um limite, o pedido e os reembolsos ainda são registrados com exatidão. O relatório de Receita mostra um aviso de histórico incompleto e uma linha de detalhamento Incomplete history (Histórico incompleto) em vez de atribuir crédito a partir de parte da jornada. Esses pedidos não contribuem para a receita atribuída nem para o tempo médio até a compra; permanecem nos totais monetários e no denominador da taxa de atribuição. O relatório conta os pedidos afetados para a moeda e o período selecionados, inclusive os totalmente reembolsados. Mudar a janela não recupera um histórico que não pôde ser capturado na ingestão.

Jornadas legadas encurtadas também são marcadas como incompletas até que seu histórico completo possa ser recuperado. Os resultados de relatório salvos são preservados. Históricos sem visitas rastreadas mantêm a atribuição fornecida pela integração descrita acima; eles são distintos de um histórico que excedeu um limite. O enriquecimento automático além desses limites não está disponível atualmente.

Ignore visitas de checkout e de agradecimento

Um retorno do provedor de pagamento muitas vezes inicia uma nova visita na sua página de agradecimento ou de checkout, que receberia o crédito de último toque. Em Settings → Exclusions → Revenue attribution only (Configurações → Exclusões → Apenas atribuição de receita), administradores e proprietários adicionam até 20 regras de caminho com a sintaxe de exclusão de tráfego (/thanks exatamente, ou /checkout/* para um prefixo). Visitas que entram por um caminho correspondente são removidas dos toques do pedido antes da aplicação da janela e do modelo; se nenhum toque restar, o pedido fica Unattributed. Nada é excluído: tráfego, páginas da Visão geral e todos os outros relatórios mantêm essas visitas, e a página de conversão ainda mostra o caminho fornecido pela sua integração. As regras se aplicam apenas a novos cálculos - os relatórios de Receita e Visão geral iniciam uma nova análise quando uma regra muda, enquanto resultados já salvos, relatórios programados já calculados e resultados da API permanecem como estavam; a próxima requisição à API calcula com as novas regras. Pedidos sem histórico de visitas (enviados sem ID de visitante, ou anteriores à atribuição derivada) não podem ser filtrados; o relatório os conta sob o aviso de regras.

Relatório de receita

Abra Revenue (Receita) na barra lateral do site. Suas tabelas mantêm cada valor em uma linha; em telas estreitas, uma tabela rola para o lado dentro do cartão e jornadas de compra longas são encurtadas com reticências (passe o mouse para ver o caminho completo). A barra de ferramentas tem o intervalo de datas mais os controles de atribuição:

• Attribution model (Modelo de atribuição): First touch (Primeiro toque) credita a primeira visita na janela, Last touch (Último toque) a visita que levou ao pedido, Linear divide o pedido igualmente entre suas visitas.
• Attribution lookback (Janela de atribuição): 7, 14, 30 ou 90 dias antes do pedido. Uma visita mais antiga que a janela não é um toque. Visitas completas salvas são usadas para o crédito do modelo, sujeitas aos limites da atribuição acima.
• Padrão do site: a página abre com o modelo e a janela salvos do site (último toque, 30 dias até que um seja salvo). Quando sua seleção difere, administradores e proprietários veem Save as website default (Salvar como padrão do site); o padrão é compartilhado com o crédito de receita da Visão geral, a API de análise e o get_revenue do MCP, e com todos os colegas. Uma seleção na URL sempre prevalece para essa visualização. Overview: net / gross (Visão geral: líquida / bruta) escolhe o que o KPI da Visão geral mostra (veja KPIs); o site de demonstração não pode alterar essas configurações.

A faixa superior mostra bruto, reembolsos (com a contagem de reembolsos), líquido, receita atribuída, taxa de atribuição e tempo médio até a compra. Attribution breakdown (Detalhamento da atribuição) tem cinco abas: Landing pages, Converting pages, First source, Last source e Sources (Páginas de destino, Páginas de conversão, Primeira fonte, Última fonte e Fontes). Fontes credita cada fonte sob o modelo selecionado, então com Linear um pedido aparece uma vez sob cada uma de suas fontes com uma parcela do seu valor líquido. Revenue by product (Receita por produto) lista pedidos, receita, participação e a parte atribuída. Touches before purchase (Toques antes da compra) agrupa os pedidos pela contagem derivada de toques. Purchase journeys (Jornadas de compra) agrupa os pedidos pagos pela página de entrada de cada visita dentro da janela, da mais antiga para a mais recente (/ → /pricing → /checkout): repetições consecutivas são agrupadas, apenas os últimos seis passos são mantidos após reticências, um caminho fornecido pela sua integração substitui a jornada derivada, e pedidos sem histórico de visitas mostram sua página de destino. As jornadas são páginas de entrada das visitas, não todas as páginas vistas.

Orders (Pedidos) lista os pedidos do período do mais recente para o mais antigo, vinte por vez com Load more (Carregar mais), apenas na moeda de relatório: horário (passe o mouse para o momento exato no seu fuso horário de exibição), produto com os selos Refunded (Reembolsado) ou Partially refunded −amount (Reembolsado parcialmente −valor), primeira fonte, jornada e valor sob o modelo e a janela selecionados. Pedidos com histórico incompleto mostram Incomplete history. Refunds (Reembolsos) lista todos os reembolsos desses pedidos - horário do reembolso, ID do pedido (ou horário do pedido), produto, ID do reembolso e valor - também vinte por vez; um reembolso total registrado antes de existirem livros-razão de reembolso aparece uma vez como legacy. Os reembolsos sempre contam no período do seu pedido, tanto aqui quanto nos totais. Visualizadores podem ler as duas listas; as exportações brutas ficam em Settings → Data.

Mudar o modelo ou a janela inicia uma nova análise para o mesmo intervalo; os resultados existentes e os pedidos armazenados não são reescritos.

Compare períodos

O botão de comparação ao lado do intervalo de datas oferece as mesmas opções da Visão geral: Previous period, Previous week, Previous month, Previous quarter, Previous year, Custom range… e No comparison (veja intervalos de datas e filtros). Com uma comparação ativa, cada KPI da faixa superior mostra sua variação percentual em relação ao intervalo de comparação em vez da contagem: bruto, reembolsos, líquido, receita atribuída, taxa de atribuição e tempo até a compra. Um aumento nos reembolsos ou no tempo até a compra é mostrado como queda. Previous period é calculado na mesma análise; as outras opções iniciam uma análise de receita adicional com o mesmo modelo, janela e moeda de relatório. As tabelas de detalhamento, produtos, toques, jornadas, pedidos e reembolsos permanecem visualizações do período atual, e All time não tem comparação.

Repasse da atribuição

Seja um conector ou seu servidor quem registra o pedido, o vínculo com a visita é o ID do visitante. Com um conector, anexe seean_visitor_id (e opcionalmente seean_landing_path, seean_converting_path, seean_campaign) de window.seean.attribution() aos metadados de checkout, dados personalizados, atributos do carrinho ou atributos de assinante do provedor, como o guia do provedor mostra; o Seean lê essas chaves do evento verificado. O token público de rastreamento nunca autoriza a ingestão de pedidos.

Para uma integração personalizada, capture window.seean?.attribution?.() quando disponível durante a criação do checkout e envie apenas os campos suportados ao seu servidor. Armazene-os com a referência do checkout/pedido para que o evento de pagamento verificado posterior possa usá-los. O auxiliar pode estar ausente antes do carregamento ou não retornar atribuição quando a coleta está desativada. Aceite um pedido não atribuído nesse caso; não invente valores de visitante ou campanha.

Depois que o rastreador carregar, aguarde window.seean?.ready antes de ler a atribuição. Isso termina após a tentativa inicial de coleta ou seu tempo limite; não garante que um ID de visitante exista. Use isso dentro do seu manipulador assíncrono de checkout e permita que o checkout continue sem atribuição. Cada exemplo de provedor inclui a espera.

O hash padrão do visitante muda à meia-noite UTC e tem escopo de um único site. A janela de 90 dias busca registros que carregam o identificador capturado; ela não une os diferentes hashes diários desse visitante. Preserve a atribuição do momento do checkout para webhooks de pagamento atrasados. Um retorno posterior em um novo dia UTC tem uma nova identidade, então jornadas de vários dias não são reconstruídas. Pedidos legados e resultados salvos mantêm seus identificadores e valores originais.

Mantenha identificadores externos de pedido estáveis entre novas tentativas. Encaminhe pagamentos recorrentes como os pedidos pagos distintos que representam, e mapeie cada reembolso ao ID externo do pedido original com o ID de reembolso do provedor. Sua integração deve levar em conta a ordem dos eventos e as duplicatas do provedor. Converta os valores do provedor para as unidades menores da moeda de relatório do site apenas quando o pagamento foi de fato cobrado nessa moeda; o Seean rejeita outras moedas em vez de convertê-las.

Verifique sua integração

Use os recursos de teste do seu provedor e um site de teste separado no Seean quando possível. Verifique um pedido pago, uma repetição idêntica, um reembolso parcial, um reembolso total e um pedido sem atribuição. Confira o relatório de Receita do site com os valores exatos e a atribuição derivada. Uma requisição bem-sucedida do rastreador ou uma visita à página de confirmação não prova que o pedido foi ingerido.

Referência de integração

Siga Order API e reembolsos para payloads, manejo da chave do servidor, regras de moeda, regras de reembolso e comportamento de novas tentativas. A disponibilidade de provedores resume quais provedores têm conector nativo.

Guias dos provedores

Cada guia cobre os passos de configuração do provedor, o trecho de atribuição para seu checkout, o que é registrado, reembolsos, moeda, verificação e limites.

O histórico de visitas rastreadas é capturado uma vez quando um novo pedido é aceito, pela Order API ou por um conector de provedor suportado. Uma falha temporária na consulta do histórico retorna uma resposta que permite nova tentativa; uma duplicata aceita mantém a atribuição original e o valor exato. Veja novas tentativas da Order API.

• Creem

  Connect Creem to Seean with the webhook secret, pass the visitor ID as checkout metadata and receive completed checkouts and refunds.

• Mollie

  Connect Mollie to Seean through signed next-generation webhooks, pass the visitor ID as payment metadata and receive paid payments and refunds.

• Paddle

  Connect Paddle to Seean with the notification secret key, pass the visitor ID as checkout custom data and receive completed transactions and approved refunds.

• Polar

  Connect Polar to Seean with the webhook secret, pass the visitor ID as checkout metadata and receive paid orders, renewals and refunds.

• RevenueCat

  Connect RevenueCat to Seean with the webhook authorization value, pass the visitor ID as Web Billing metadata or a subscriber attribute and receive purchases, renewals and refunds.

• Revolut

  Connect the Revolut Merchant API to Seean with the webhook signing secret and Merchant API secret key, pass the visitor ID as order metadata and receive completed orders.

• Shopify

  Connect a Shopify store to Seean with the webhook signing secret, write the visitor ID as a cart attribute and receive paid orders and refunds.

• Stripe

  Connect Stripe Checkout to Seean with the webhook signing secret, pass the visitor ID as session metadata and receive paid orders and refunds.

• Superwall

  Connect Superwall to Seean with the webhook signing secret, set the visitor ID as a user attribute and receive purchases and renewals.

• Whop

  Connect Whop to Seean with the webhook signing secret, pass the visitor ID as checkout metadata and receive successful payments and refunds.

Algo não ficou claro? Fale com o suporte.