Visão geral
A importação de histórico traz para a Conversa Labs cobranças, vínculos de clientes e assinaturas que já existem no gateway. Cobranças criam os eventos financeiros, Pedidos e relatórios; assinaturas passam a aparecer em Pagamentos > Assinaturas; e um cliente importado só cria o vínculo técnico com um contato que já exista na conta.
O processo é governado: uma prévia não grava cobranças, vínculos nem assinaturas; ela persiste somente a execução auditável e a captura usada para revisar a seleção. Uma importação real só inclui os registros que você selecionar. A plataforma nunca cria contatos ou empresas silenciosamente: uma cobrança sem correspondência exata fica bloqueada até você escolher um contato existente ou propor um novo, que só será criado depois da confirmação final. Quando a cobrança e a assinatura têm o mesmo identificador de assinatura do gateway, elas também são vinculadas entre si, mesmo que você importe uma antes da outra. Cobranças históricas não disparam mensagens ao cliente, conversões de anúncios, comissões nem webhooks de saída.
Pré-requisitos
- Você precisa ser administrador da conta.
- A conexão do Asaas ou Mercado Pago deve estar ativa e com as credenciais verificadas.
- Para cobranças do Mercado Pago, escolha uma data inicial dentro dos últimos 12 meses. A busca completa desse recurso segue essa janela móvel.
- Para clientes do Mercado Pago, informe o e-mail do cliente. A API documentada desse gateway não oferece uma varredura total de clientes.
- Revise o marco d'água antes de permitir adoção automática de cobranças desconhecidas por webhook.
Passo a passo
- Acesse Configurações > Pagamentos > Conexões e escolha Importar histórico na conexão desejada. Você também pode abrir a ação no estado vazio de Cobranças.
- Em Recurso para importar, escolha Cobranças, Vínculos de clientes ou Assinaturas. As proteções de entrada e a adoção automática se aplicam somente às cobranças.
- Para cobranças, defina o marco d'água e mantenha a adoção automática desativada, a menos que sua operação tenha uma regra clara. A opção “Somente a partir do marco d'água” exige um marco válido.
- Informe o período e o limite de registros. Para cliente do Mercado Pago, informe também o e-mail. Selecione Gerar prévia.
- Revise a lista detalhada. Cada cobrança mostra os dados de cliente que o gateway forneceu, o contato encontrado e o sinal exato usado na associação. Busque por identificador, referência ou cliente; combine filtros; altere a ordenação e percorra as páginas sem perder a seleção já feita em outras páginas.
- Em uma cobrança marcada como Cliente pendente, escolha um contato existente ou proponha um novo com nome e pelo menos um identificador (e-mail, telefone ou documento). A proposta não cria nada durante a prévia. Correspondências automáticas usam somente cliente do gateway, e-mail, telefone normalizado ou documento exatos; nomes parecidos nunca bastam.
- Use Selecionar importáveis desta página, Selecionar todos os importáveis destes filtros (quando a prévia passa de uma página) ou marque cada linha. A seleção global considera todas as páginas do recorte, mas alcança apenas registros importáveis e com cliente resolvido: uma linha ignorada, já sincronizada ou pendente nunca é marcada. Alterar um filtro limpa a seleção de propósito; mudar de página a preserva. A conexão, a execução, os filtros e a ordenação ficam na URL, por isso voltar, avançar ou reabrir o link restaura a mesma visão somente quando a conexão pertence à conta atual.
- Selecione Importar selecionados, confira a quantidade e as resoluções de cliente na confirmação e confirme. Uma seleção vazia nunca significa “importar tudo”. Contatos propostos são criados dentro da importação confirmada; se qualquer validação falhar, a cobrança correspondente não entra sem contato.
- Acompanhe o resultado e o histórico da conexão. Registros com falha mostram o identificador e o motivo; o sucesso nunca inclui uma linha que falhou.
Configurações & opções
Marco d'água e adoção automática
O marco d'água limita a entrada de histórico. A adoção automática de cobranças que chegarem por webhook fica desativada por padrão. Se você a habilitar a partir do marco, a plataforma falha de forma segura quando o marco estiver ausente ou inválido.
Lista da prévia
A prévia é uma captura segura da mesma execução que importaria os dados, sem gravar cobranças, vínculos ou assinaturas. A lista usa paginação e totais retornados pelo servidor; o contador não é calculado apenas com a página visível. Em telas pequenas, os filtros e a ordenação abrem em um painel próprio e cada linha vira um cartão legível.
Os chips mostram os filtros ativos. Limpar filtros aparece quando uma combinação não encontra resultados. Se o limite informado for atingido, a prévia avisa que foi truncada: gere outra janela em vez de presumir que todo o histórico foi lido.
Registros ignorados
Na prévia, use o ícone de bloqueio ao lado de um registro para ignorá-lo permanentemente e informe o motivo. A decisão é separada por cobrança, cliente ou assinatura, mesmo se o gateway reutilizar um identificador. Em Registros ignorados permanentemente, use Permitir novamente para desfazer essa decisão.
Vínculos com contatos e empresas
A plataforma procura primeiro correspondências exatas por cliente do gateway, e-mail, telefone normalizado, documento e CNPJ. Para uma cobrança sem contato, você precisa escolher manualmente um contato da conta ou propor a criação de um novo antes de selecioná-la. A criação é adiada até a confirmação e o vínculo manual nunca é substituído silenciosamente. Uma assinatura sem contato correspondente continua visível para futura conciliação; um cliente do diretório sem contato correspondente é ignorado, porque não há proprietário local seguro para o vínculo. Cobranças e assinaturas são conectadas somente pelo identificador exato que o gateway informa, nunca por valor, data ou nome.
Casos de uso
- Recuperar cobranças, Pedidos e assinaturas depois de conectar um gateway que já tinha vendas.
- Construir primeiro os vínculos de clientes do Asaas e depois importar assinaturas, para aumentar a associação pelo identificador exato do gateway.
- Reconstruir relatórios internos sem reenviar notificações para clientes antigos.
- Excluir de forma durável uma cobrança que pertence a outra operação ou que não representa uma venda.
- Importar primeiro um período pequeno, validar os resultados e repetir em janelas menores.
Dicas, limites e boas práticas
- Comece com uma janela curta e um limite baixo; amplie somente após conferir a prévia.
- Cada prévia/importação e cada seleção explícita aceitam no máximo 5.000 registros.
- A importação confirmada deve usar exatamente o mesmo tipo de recurso, período, limite e e-mail da prévia concluída. Se qualquer parâmetro mudar, gere uma nova prévia; isso vale para cobranças, clientes e assinaturas.
- A seleção é obrigatória. A plataforma nunca interpreta uma seleção vazia como “importar tudo”.
- A seleção sobrevive à paginação e Selecionar todos cobre todas as páginas dos filtros atuais, mas ela é limpa ao mudar busca ou filtros para impedir que uma linha invisível seja importada por engano.
- Cobranças sem contato resolvido não podem ser selecionadas. Resolva cada uma manualmente; a API também bloqueia tentativas de contornar a prévia.
- A lista de registros ignorados é carregada por completo em páginas internas; mais de 100 exclusões não desaparecem silenciosamente.
- Clientes não usam filtro de data; eles só podem vincular um contato já existente. No Mercado Pago, a busca é sempre por e-mail.
- Os totais são mostrados por moeda; não compare a soma de moedas diferentes como se fosse um único valor.
- A reversão remove apenas registros locais que aquela execução criou. Ela nunca altera o gateway.
- Para reverter, abra uma execução elegível no histórico, digite
undoe confirme. Se uma cobrança, vínculo de cliente, assinatura, Pedido ou evento posterior tiver movimentado os dados, a reversão é recusada inteira para preservar a auditoria. A reversão remove somente registros e vínculos criados pela execução; contatos e organizações são preservados, inclusive um contato proposto e confirmado manualmente. - Execuções antigas, feitas antes da trilha de reversão, podem não ser elegíveis. Nesse caso, mantenha o histórico e faça os ajustes financeiros pela operação normal.
Solução de problemas
Mercado Pago pede uma data inicial
Informe uma data dentro da janela de histórico suportada pelo Mercado Pago. Uma data anterior pode produzir uma visão incompleta e é recusada pela plataforma.
Não consigo importar sem selecionar registros
Isso é esperado. Gere a prévia, marque os registros desejados e execute a importação selecionada.
Uma cobrança não pode ser selecionada porque o cliente está pendente
Abra a resolução de cliente na própria linha. Escolha um contato existente ou proponha um novo com nome e e-mail, telefone ou documento. Depois de salvar a decisão, selecione a cobrança e confirme a importação. O contato novo ainda não existe até essa confirmação.
O Mercado Pago pede o e-mail do cliente
Isso é esperado. A busca documentada de clientes do Mercado Pago exige e-mail e não permite uma importação geral da agenda. Informe o e-mail do cliente existente que deseja vincular ou importe assinaturas, que tentam associar os dados de pagador fornecidos pelo gateway.
Uma cobrança aparece como ignorada
Abra Cobranças ignoradas permanentemente na mesma tela, confirme o motivo e use Permitir novamente se ela puder voltar a ser considerada.
A reversão foi recusada
Ocorreu movimentação posterior ou o registro não foi criado pela execução escolhida. Nenhum dado foi removido. Revise a linha do histórico, os eventos da cobrança e faça o ajuste apropriado pela operação financeira normal.