​

Atribuição

• Respostas — a resposta de um cliente a “Como nos encontrou?”, vinda do popup de inquérito do Finseo, dos seus próprios formulários, de uma ferramenta de inquéritos ou do seu CRM.
• Conversões — compras e leads com um ID de transação e um valor, vindos do seu tracking existente (Google/Meta), do Stripe, do seu sistema de loja ou de um webhook.

​

Configuração guiada

​

O Snippet do Finseo

<script src="https://app.finseo.ai/api/attribution/widget/YOUR_PROJECT_ID" async></script>

​

1. Captura respostas dos seus formulários existentes

​

2. Mostra o popup de inquérito

• Pergunta e canais — os canais padrão incluem AI Search, Google/Bing, Redes sociais, Anúncios online, Recomendação, Conteúdo e Outro (com texto livre). Também pode usar canais de IA detalhados (ChatGPT, Perplexity, Claude, Gemini, Copilot).
• Trigger — no carregamento da página, após a submissão de um formulário, após uma compra detetada, ou manual via JavaScript.
• Estilo — cor de destaque, posição, raio dos cantos, tipo de letra (do sistema ou herdado do seu site) e baralhamento opcional das respostas para evitar enviesamento de posição (“Outro” fica sempre em último).

​

3. Aproveita o seu tracking de conversões existente

​

API de JavaScript

// Show the survey popup programmatically (e.g. after signup)
window.finseoAttribution.show();

// Report a conversion from your own code
window.finseoAttribution.trackConversion({
  transactionId: "ORDER-12345",
  value: 1234.56,
  currency: "EUR",
  email: "kunde@example.com" // optional merge key
});

​

Como respostas e conversões se fundem

• Chaves de fusão: ID de transação (respondentExternalId ↔ transactionId) ou email. Uma correspondência por ID de transação ganha sempre a uma correspondência por email.
• Janelas: uma nova conversão procura uma resposta ao inquérito até 90 dias para trás (trials de SaaS convertem muitas vezes semanas após o registo). Uma nova resposta ao inquérito só procura uma conversão por associar até 48 horas para trás, para que uma resposta recente nunca seja ligada a uma encomenda antiga sem relação.
• Valores de negócio: se a resposta não tiver valor de negócio, o montante da conversão fundida preenche-o — a receita nunca é contada duas vezes.
• Tipos de conversão: checkouts do Stripe com total de $0 são guardados como trials, faturas recorrentes como renovações. Apenas as compras normais contam como novos clientes a aguardar atribuição.
• Receita não atribuída: as conversões que nunca receberam uma resposta ao inquérito são mostradas como KPI próprio, para que veja sempre quanta receita continua por explicar.

​

Privacidade por defeito

​

Importar respostas de ferramentas de inquéritos

​

Enviar dados com um webhook

https://app.finseo.ai/api/attribution/webhook/PROJECT_ID?token=WEBHOOK_TOKEN

curl --request POST \
  --url "https://app.finseo.ai/api/attribution/webhook/PROJECT_ID?token=wh_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "channelId": "AI Search",
    "respondentEmail": "kunde@example.com",
    "respondentName": "Max Mustermann",
    "respondentExternalId": "BESTELLUNG-12345",
    "dealValue": 1234.56,
    "dealCurrency": "EUR",
    "metadata": {
      "produkt": "Produkt XY",
      "sku": "ABC-123",
      "menge": 2
    }
  }'

{
  "success": true,
  "id": "response-id",
  "source": "raw"
}

​

Payloads só de encomenda tornam-se conversões

{
  "success": true,
  "type": "conversion",
  "id": "conversion-id",
  "matched": true
}

​

Referência de campos

​

Mapear campos recebidos

1. Abra Attribution.
2. Vá a Workflows.
3. Envie um webhook de teste a partir do seu sistema de origem.
4. Abra o workflow criado.
5. Mapeie os campos recebidos para atribuição, email, nome, valor do negócio, moeda, ID do formulário ou regras.
6. Guarde o mapeamento.

{
  "attribution": "lead.source",
  "email": "lead.email",
  "name": "lead.full_name",
  "dealValue": "order.total",
  "dealCurrency": "order.currency",
  "formId": "form.id"
}

​

Formatos de origem suportados

• HubSpot: payloads legacy de webhooks de contactos com properties, ou corpos JSON personalizados do Operations Hub.
• Typeform: form_response.answers, incluindo campos choice, choices, text e email.
• Tally: payloads data.fields.
• Salesforce: JSON do Flow HTTP Callout, por exemplo LeadSource, Email, Name, Amount e CurrencyIsoCode.
• Jotform: multipart/form-data com rawRequest ou campos como q3_howDid, formID e submissionID.
• Stripe: payloads de eventos (checkout.session.completed, invoice.paid, …) — guardados como conversões, com conversão automática de cêntimos e classificação de trials/renovações.
• WooCommerce: webhooks de encomendas, incluindo o meta do Order Attribution como origem de marketing.
• Shopware: payloads de encomendas do Flow Builder com orderNumber, amountTotal e o email do cliente.
• Raw JSON: payloads diretos com campos como channelId, respondentEmail, dealValue e metadata.

​

Exemplos

{
  "channelId": "ChatGPT",
  "respondentEmail": "jane@company.com",
  "respondentName": "Jane Smith",
  "respondentExternalId": "lead_98421",
  "dealValue": 12000,
  "dealCurrency": "EUR",
  "metadata": {
    "country": "DE",
    "plan": "Enterprise"
  }
}

{
  "channelId": "Perplexity",
  "respondentEmail": "kunde@example.com",
  "respondentExternalId": "ORDER-12345",
  "dealValue": 1234.56,
  "dealCurrency": "EUR",
  "metadata": {
    "produkt": "Produkt XY",
    "sku": "ABC-123",
    "menge": 2,
    "shop": "DE"
  }
}

{
  "LeadSource": "Claude",
  "Email": "buyer@example.com",
  "Name": "Alex Buyer",
  "Id": "00Qxx0000012345",
  "Amount": 8500,
  "CurrencyIsoCode": "USD"
}

​

Importação diária em lote

curl --request POST \
  --url "https://api.finseo.ai/v1/projects/PROJECT_ID/attribution/bulk" \
  --header "Authorization: Bearer sk_live_xxxxxxxx" \
  --header "Content-Type: application/json" \
  --data '{
    "responses": [
      {
        "channelId": "AI Search",
        "respondentEmail": "kunde@example.com",
        "respondentExternalId": "BESTELLUNG-12345",
        "dealValue": 1234.56,
        "dealCurrency": "EUR"
      }
    ]
  }'

​

Receber eventos de atribuição

{
  "event": "attribution.response.created",
  "data": {
    "id": "response-id",
    "channel_id": "ai_chatgpt",
    "channel_label": "ChatGPT",
    "channel_category": "ai_search",
    "respondent_email": "kunde@example.com",
    "respondent_name": "Max Mustermann",
    "deal_value": 1234.56,
    "deal_currency": "EUR",
    "source": "webhook",
    "created_at": "2026-07-07T10:00:00Z"
  },
  "project_id": "PROJECT_ID",
  "timestamp": "2026-07-07T10:00:01Z"
}

​

Limites de pedidos

• Endpoint de webhook: 120 pedidos por minuto por projeto.
• Endpoint de recolha do snippet: 60 pedidos por minuto por IP de visitante.

​

Resolução de problemas

​

Boas práticas

• Coloque a pergunta de atribuição perto da conversão, como no registo, no pedido de demo, no checkout ou na qualificação do lead.
• Mantenha as opções de resposta estáveis entre países. Traduza as etiquetas para os utilizadores se necessário, mas mantenha os valores dos webhooks consistentes.
• Envie a moeda original do pagamento em dealCurrency; o Finseo consegue na mesma agregar e mapear os valores.
• Inclua um respondentExternalId estável, como o ID da encomenda, o ID do lead no CRM, o ID do contacto ou o ID do negócio.
• Coloque produto, SKU, mercado, campanha e outro contexto de negócio em metadata.
• Envie um evento por lead, encomenda ou negócio. Evite enviar cada visualização de página como atribuição.