Integrações

Integração Asaas

Conecte sua conta Asaas ao Synchro Hub para receber vendas (cobranças) em tempo real e consolidar métricas no dashboard.

Visão geral

Ao integrar o Asaas, o Synchro Hub passa a:

Receber webhooks de cobranças confirmadas, reembolsos e chargebacks automaticamente — o webhook é registrado pelo próprio Synchro via API, sem configuração manual no painel da Asaas.
Consolidar suas cobranças (boleto, PIX, cartão) junto com vendas de outras plataformas em um único dashboard.

Tempo estimado: 3 minutos. O que você vai precisar:

Conta Asaas ativa em asaas.com.
Workspace já criado no Synchro Hub.

Pré-requisitos

Estar logado no Synchro Hub com um workspace selecionado.
Ter acesso ao painel do Asaas para gerar a API Key.

Passo 1 — Gerar a API Key no Asaas

Entre no painel do Asaas em www.asaas.com.
Acesse Configurações → Integrações → API.
Clique em Gerar nova chave (ou Nova chave) e dê um nome (ex.: Synchro Hub).
Copie a chave exibida. Atenção: ela tem o formato $aact_... e só aparece uma vez — guarde-a com segurança antes de fechar a tela.

Importante: essa API Key dá acesso total à sua conta Asaas via API. Nunca compartilhe, não comite em repositórios e revogue imediatamente se desconfiar de vazamento.

Passo 2 — Conectar a plataforma no Synchro Hub

No Beacon, acesse Configurações → Integrações → Fontes de Venda.
Clique em + Adicionar Plataforma.
Selecione Asaas (badge azul-ciano).
Clique em Confirmar — uma integração ECOMMERCE/ASAAS é criada (ainda sem credencial).

Passo 3 — Salvar a API Key

Na tela de credenciais, cole a chave $aact_... no campo API Key.
Clique em Salvar.

O Synchro valida a chave fazendo uma chamada ao endpoint GET /v3/myAccount da Asaas. Se a chave for inválida (401/403), você verá um erro — verifique o passo anterior e gere uma nova chave se necessário.

Passo 4 — Ativar o webhook (automático)

Após salvar a credencial, clique em Ativar Webhook.
O Synchro chama POST /v3/webhooks na Asaas e registra automaticamente:
- URL do webhook: https://api.synchro.app/v1/webhooks/ecommerce/asaas/<seu-integration-id>
- Token de autenticação (gerado pelo Synchro)
- Eventos: cobranças confirmadas, recebidas, reembolsadas e chargebacks
A integração fica em estado Ativo — pronto.

Você não precisa entrar no painel da Asaas para configurar webhook manualmente. O Synchro faz tudo via API.

Verificação

Para confirmar que tudo está funcionando:

Gere uma cobrança de teste no Asaas (boleto, PIX ou cartão) e marque como paga, ou aguarde o pagamento.
Abra Vendas no menu lateral do Synchro Hub.
A venda deve aparecer em segundos após a confirmação (PAYMENT_CONFIRMED / PAYMENT_RECEIVED).

O que será sincronizado

Evento Asaas	O que aparece no dashboard
`PAYMENT_CONFIRMED` / `PAYMENT_RECEIVED`	Venda aprovada
`PAYMENT_REFUNDED` / `PAYMENT_PARTIALLY_REFUNDED`	Venda reembolsada
`PAYMENT_CHARGEBACK_REQUESTED` / `DISPUTE`	Venda em chargeback

Eventos como PAYMENT_CREATED (cobrança gerada mas ainda não paga) ou PAYMENT_OVERDUE (vencida) não geram registro no dashboard — só vendas confirmadas aparecem, alinhado com o comportamento das outras plataformas.

Limitações conhecidas

Produto da cobrança: o Asaas não tem catálogo de produto nativo. Se você preencher o campo Referência Externa (externalReference) ao criar a cobrança, o Synchro usa esse valor como identificador de produto. Sem ele, a venda é registrada mas não vincula a um produto (não aparece em relatórios “Vendas por Produto”). Recomendação: padronize um externalReference por produto/plano em seu checkout.
Split (afiliados): se você usa o recurso de split do Asaas, cada destinatário aparece como afiliado não identificado (apenas o walletId). Isso é uma limitação do próprio Asaas — a API deles não expõe o dono da carteira. Os valores estão corretos; só o nome/email do afiliado fica em branco.
Sandbox vs produção: ambientes separados na Asaas. A API Key de sandbox só funciona com o ambiente sandbox; produção exige chave de produção. O Synchro detecta automaticamente o ambiente pelo NODE_ENV da instância (clientes de produção usam Asaas produção).

Resolução de problemas

Sintoma	Causa provável	Ação
”API Key do Asaas inválida ou sem permissão”	Chave revogada ou copiada errado.	Gere uma nova chave no painel Asaas.
Webhook ativado, mas nenhuma venda aparece	A chave é de sandbox e você está em produção.	Gere chave do ambiente correto.
Venda aparece sem nome de produto	Cobrança sem `externalReference`/`subscription`.	Esperado — preencha esses campos no checkout para identificar.
Comissão de afiliado sem nome/email	Limitação da API Asaas.	Esperado — apenas o `walletId` é registrado.

Perguntas frequentes

Posso ter mais de uma chave de API ativa no Asaas? Sim. O Asaas permite múltiplas chaves; use uma exclusiva para o Synchro Hub para conseguir revogar sem afetar outras integrações.

O campo externalReference é obrigatório? Não, mas é fortemente recomendado. Sem ele, a venda entra no dashboard sem vínculo a um produto e não aparece em relatórios por produto.

Por que o nome/e-mail do afiliado fica em branco quando uso split? Limitação do próprio Asaas — a API expõe só o walletId do destinatário do split, não os dados do dono da carteira. Os valores financeiros estão corretos.

Como desconecto a integração? No card da Asaas, clique em Remover. O Synchro também remove o webhook registrado na Asaas via API. Revogue a chave no painel Asaas se não for mais usá-la em nenhuma integração.

Atribuição de ROI em PIX/Boleto (opcional — só se você usa o SynchroPixel)

Opcional. Esta seção só interessa se você usa (ou pretende usar) o SynchroPixel para rastrear o ROI dos seus anúncios server-side. Se você não usa pixel, a integração Asaas funciona normalmente — pode pular esta seção.

Por que isso é necessário

Pagamentos por PIX e Boleto são assíncronos — o cliente sai do seu site para pagar e o webhook PAYMENT_RECEIVED só chega depois (às vezes horas). Nesse momento o navegador do cliente já não tem mais cookies de pixel (fbclid, gclid, _fbp), então o CAPI perde a atribuição.

A solução é anexar o identificador do SynchroPixel ao externalReference da cobrança Asaas, antes do cliente sair da sua página. O webhook traz esse identificador de volta e o Synchro casa a venda com a visita original — disparando CAPI server-side com todos os parâmetros corretos.

O que você vai injetar

Uma única chamada no seu checkout:

const metadata = window.synchroPixel.getCheckoutMetadata();

Retorna um objeto plano (só com chaves preenchidas) que inclui:

Chave	Origem	Para que serve
`synchroSessionId`	Cookie 1st-party (UUID gerado pelo pixel)	Casamento direto venda↔visita
`fbclid`	URL da landing page	Atribuição Meta
`gclid`	URL da landing page	Atribuição Google
`ttclid`	URL da landing page	Atribuição TikTok
`fbp`, `fbc`	Cookies do Facebook	EMQ score Meta CAPI
`utmSource`, `utmMedium`, `utmCampaign`, `utmContent`, `utmTerm`	URL da landing	Atribuição de campanha

Exemplo — Asaas (`POST /payments`)

O Asaas não tem campo metadata arbitrário, mas tem externalReference (string única, ≤255 chars). O Synchro convenciona usá-lo como JSON quando há pixel:

// frontend — montar o externalReference no clique do "Pagar"
const metadata = window.synchroPixel?.getCheckoutMetadata() ?? {};
const externalReference = JSON.stringify({
  inv: 'seu-pedido-123', // opcional: seu id interno
  ...metadata,
});

// backend — criar a cobrança Asaas
await fetch('https://api.asaas.com/v3/payments', {
  method: 'POST',
  headers: {
    access_token: process.env.ASAAS_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer: 'cus_xxx',
    billingType: 'PIX', // ou 'BOLETO', 'CREDIT_CARD'
    value: 99.9,
    dueDate: '2026-12-31',
    description: 'Curso X',
    externalReference,
  }),
});

O Synchro decodifica externalReference automaticamente:

Se for JSON com a chave inv: extrai seu id interno como productId e as chaves de pixel para atribuição.
Se for string opaca (formato antigo, como inv_123): mantém retrocompatibilidade — continua sendo tratado como productId.

Já uso externalReference para meu pedido interno? Sem problema: passe seu id no campo inv do JSON. O Synchro preserva esse valor como productId, exatamente como antes.

Como validar

No painel Asaas: abra a cobrança → campo Referência externa deve conter o JSON ({"inv":"...","synchroSessionId":"..."}).
No Beacon: após a confirmação do pagamento, abra Vendas → detalhe e veja a coluna Origem do clique. Deve mostrar “Sessão (synchroSessionId)” — o casamento direto. Em Anúncios → Atribuição, a venda aparece sob o anúncio correto.
Meta Events Manager / Google Ads: eventos Purchase server-side com EMQ alto / gclid populado.

FAQ rápido

E se o cliente bloqueou o pixel via AdBlocker? window.synchroPixel fica undefined. O exemplo já usa ?. — sem o pixel, metadata vai vazio e o externalReference cai para o formato legado. O Synchro tenta match por email (janela 7d) — atribuição mais fraca mas existe.

O externalReference no Asaas tem limite de tamanho? 255 chars. O JSON canônico fica em ~200 chars com sessão + 3 click IDs. Se você empilhar muitos campos extras, considere truncar (mas o Synchro prefere synchroSessionId — se ele estiver presente, os outros são redundância).