Integração com o Asaas

A integração com o Asaas transforma o Coconut numa ferramenta de cobrança completa: você emite cobranças por PIX, boleto e cartão de crédito direto pelo app, e os pagamentos voltam automaticamente, atualizando o status da cobrança e dando baixa no lançamento. Além disso, você pode importar clientes e cobranças que já existem na sua conta Asaas, configurar e emitir NFS-e e acompanhar o financeiro, sem sair do Coconut. O Asaas é uma instituição de pagamento autorizada pelo Banco Central: é ele quem processa o dinheiro; o Coconut é a camada de gestão por cima.

Como funciona, em uma visão

O fluxo completo de uma cobrança:

1. 1
   Você cria uma cobrança no Coconut, escolhendo um cliente já cadastrado.
2. 2
   O Coconut cadastra (ou reaproveita) esse cliente como cliente no Asaas automaticamente (você não faz isso à mão).
3. 3
   A cobrança é gerada no Asaas e, ao mesmo tempo, vira um lançamento de receita pendente no Coconut.
4. 4
   Você envia o link/QR Code ou boleto pro seu cliente.
5. 5
   Quando ele paga, o Asaas avisa o Coconut em segundos: a cobrança vira Paga e o lançamento é dado como recebido sozinho.
6. 6
   (Opcional) Para cobranças pagas, você pode emitir a NFS-e com um clique.

E o caminho inverso também funciona: cobranças e clientes que já existem na sua conta Asaas podem ser trazidos para o Coconut pela importação (sempre com prévia e confirmação).

Pré-requisitos

• Uma conta no Asaas já criada e ativa (cadastro aprovado e dados bancários configurados lá).
• A chave de API da sua conta Asaas, no formato $aact_....

Ainda não tem conta no Asaas?

Crie a sua pelo link da parceria Coconut + Asaas, na própria tela de conexão em Configurações Asaas . Criar por ali garante as condições especiais da parceria. É gratuito e rápido.

Passo 1: Pegar a chave de API no Asaas

1. 1
   Faça login no painel do Asaas (ou crie a conta pelo link da parceria).
2. 2
   No Asaas, vá em Minha conta (ou Configurações) → Integrações → API.
3. 3
   Clique em Gerar chave de API (ou copie a que já existir). A chave começa com $aact_, é bem longa: copie inteira, sem espaços.

Passo 2: Conectar a conta no Coconut

1. 1
   Vá em Configurações Asaas .
2. 2
   Cole a chave no campo Chave de API. Ela fica criptografada no servidor: ninguém vê a chave depois de salva.
3. 3
   Clique em Conectar conta. O Coconut valida a chave com o Asaas na hora.
4. 4
   Se a chave for válida, a tela passa a mostrar o nome da conta conectada, e-mail, ambiente (produção ou sandbox) e a data de ativação.

Ao conectar, o Coconut registra o webhook na sua conta Asaas automaticamente (é o canal por onde o Asaas avisa sobre pagamentos, para o status atualizar sozinho) e detecta se a NFS-e está habilitada na conta.

Quem pode conectar

Apenas o dono da organização e usuários com perfil de administrador podem conectar, desconectar ou emitir cobranças. Visualizadores têm acesso somente de leitura.

Passo 3: Definir a categoria padrão das cobranças

Antes de criar cobranças ou importar dados, defina a categoria de receita padrão que as cobranças do Asaas vão usar no seu financeiro. Isso evita que os lançamentos entrem sem categoria e bagunça no relatório.

1. 1
   Em Configurações Asaas , encontre o card Categoria padrão das cobranças.
2. 2
   Escolha uma categoria de receita (ex.: “Receita de serviços”, “Mensalidades”).
3. 3
   Clique em Salvar.

Essa categoria é usada automaticamente nas cobranças recorrentes (que entram sozinhas pelo Asaas) e vem pré-selecionada na hora de importar cobranças, onde você ainda pode trocar a categoria de cada uma.

Como os clientes se vinculam ao Asaas

Você não cadastra ninguém no Asaas manualmente. Quando você cria a primeira cobrança (ou assinatura) para um cliente, o Coconut:

1. 1
   Procura no Asaas se já existe um cliente com aquele CPF/CNPJ.
2. 2
   Se existir, reaproveita o cadastro. Se não existir, cria um novo cliente no Asaas com os dados do Coconut.
3. 3
   Guarda o vínculo. Da segunda cobrança em diante, reutiliza o mesmo cliente, sem duplicar.

Vão para o Asaas: nome, e-mail, CPF ou CNPJ, telefone (celular) e o endereço.

Importar clientes do Asaas

Se você já tinha clientes cadastrados na sua conta Asaas, traga todos de uma vez para o Coconut:

1. 1
   Vá em Clientes e clique em Importar do Asaas.
2. 2
   O Coconut analisa sua conta e mostra uma prévia: quantos clientes são novos (serão criados) e quantos serão vinculados a clientes que você já tem (pelo CPF/CNPJ).
3. 3
   Confira os números e confirme para aplicar, ou cancele, se preferir não trazer agora.

Como funciona o casamento: se o cliente do Asaas já estiver vinculado, é ignorado; se existir um cliente seu com o mesmo CPF/CNPJ, é vinculado (sem duplicar); se não existir, é criado.

Emitir uma cobrança avulsa

Em Relatórios Asaas , clique em Nova cobrança → Avulsa:

• Escolha o cliente (precisa ter documento), o valor, o vencimento e a descrição.
• Escolha o método: PIX, Boleto ou Cartão de crédito.
• (Opcional) Configure os lembretes por e-mail.

Ao salvar, o Asaas gera o link de cobrança (e o QR Code, no PIX), que fica disponível na lista para você copiar e enviar.

Sincronizar cobranças do Asaas

Cobranças criadas direto no painel do Asaas (ou por outra ferramenta), e todo o histórico, podem ser trazidas para o Coconut pela sincronização, com prévia e escolha de categoria.

1. 1
   Em Relatórios Asaas , clique em Sincronizar.
2. 2
   O Coconut analisa e mostra a prévia: quantas cobranças são novas (viram lançamento) e quantas já existem (só atualizam status/valor).
3. 3
   Para as novas, escolha a categoria: defina uma para todas de uma vez e, se quiser, ajuste individualmente cada cobrança na lista.
4. 4
   Confirme para aplicar.

A sincronização é idempotente: rodar de novo não duplica cobranças nem lançamentos. Quando uma cobrança importada bate exatamente (mesmo cliente, valor e vencimento) com um lançamento pendente que você já tinha, o Coconut concilia os dois em vez de criar um novo.

Como as cobranças viram lançamentos

Toda cobrança está ligada a um lançamento de receita. Há dois caminhos:

1. Criar um lançamento novo (padrão)

Ao criar a cobrança, o Coconut cria um lançamento de receita pendente com o mesmo valor, vencimento e descrição, usando a categoria padrão que você definiu. Ele aparece em Lançamentos .

2. Vincular a um lançamento que já existe

No formulário há a opção “Vincular a um lançamento existente”: o Coconut lista seus lançamentos de receita pendentes sem cobrança, você escolhe um e ele preenche valor, vencimento e descrição. Útil quando você já lançou a receita e só agora vai cobrar, sem duplicar.

Quando o cliente paga

Assim que o Asaas confirma o pagamento, automaticamente a cobrança vira Paga e o lançamento vira recebido, com a data preenchida. Sem baixa manual.

O que acontece em cada ação

Assinaturas recorrentes (cobrança automática)

Para cobranças que se repetem, o Coconut cria uma assinatura no Asaas: o Asaas passa a cobrar o cliente sozinho a cada período, sem você gerar cobrança mês a mês. E tudo nasce de um lançamento recorrente de receita.

Criar a assinatura a partir do lançamento

1. 1
   Em Lançamentos , no lançamento recorrente, abra o menu de ações e clique em Criar cobrança.
2. 2
   Escolha a forma de pagamento (PIX, boleto ou cartão): é o único campo obrigatório, já que valor, periodicidade e descrição vêm do lançamento.
3. 3
   (Opcional) Configure juros, multa e desconto e os avisos ao cliente.
4. 4
   Clique em Criar assinatura. A partir daí, cada cobrança gerada vira um lançamento automaticamente, com a categoria padrão, sem duplicar, mesmo que o Asaas reenvie o aviso.

As periodicidades (semanal, quinzenal, mensal, trimestral, semestral ou anual) vêm da recorrência do próprio lançamento.

Juros, multa e desconto

Na criação da assinatura, você define direto no Coconut:

• Juros ao mês: percentual (%).
• Multa por atraso: percentual (%) ou valor fixo (R$), aplicada uma vez.
• Desconto: percentual (%) ou valor fixo (R$), com prazo (até o vencimento ou até X dias antes).

Antes isso só era configurável no painel do Asaas; agora vale por assinatura, definido na hora de criar.

Gerenciar a assinatura

Quando a série já tem assinatura ativa, o menu do lançamento troca Criar cobrança por Gerenciar assinatura, com as ações: Pausar, Reativar, Editar valor (com opção de aplicar também às cobranças pendentes já geradas), Cancelar assinatura e Desvincular do lançamento.

Já tinha a assinatura no Asaas? Importe em vez de duplicar

Ao abrir Criar cobrança, o Coconut verifica se o cliente já tem assinatura ativa no Asaas. Se tiver, avisa em destaque e oferece Importar e vincular: traz a assinatura existente e reconcilia as cobranças já geradas, em vez de criar outra.

Acompanhar o financeiro (somente leitura)

Em Relatórios Asaas você acompanha a saúde da conta sem abrir o painel do Asaas:

• O saldo e o total a receber aparecem nos cartões do topo.
• O botão Extrato abre o Extrato da conta Asaas: as movimentações de entrada e saída, em modo leitura.

Avisos ao cliente (e-mail, WhatsApp e SMS)

O Coconut configura a régua de notificações do Asaas direto na cobrança. Na criação, abra a seção Avisos ao cliente (opcional) e escolha:

• Canais: E-mail, WhatsApp e SMS.
• Avisos: Cobrança gerada, Lembrete antes do vencimento, Pagamento confirmado e Cobrança vencida.

Você também ajusta isso depois, no botão Notificações dentro dos detalhes da cobrança.

Cancelar, reembolsar e receber em dinheiro

No menu de ações de cada cobrança:

• Cancelar: cancela no Asaas; o cliente deixa de conseguir pagar. Irreversível.
• Reembolsar: devolve o valor (só para cobranças já pagas).
• Receber em dinheiro: marca como paga sem pagamento pelo Asaas (cliente pagou por outro meio). O lançamento é dado como recebido do mesmo jeito.

NFS-e (nota fiscal de serviço)

A NFS-e tem área própria no menu: Notas Fiscais. Lá você configura os dados fiscais, define o serviço padrão, emite e acompanha as notas, sem ir ao painel do Asaas no dia a dia.

Passo 1: Configurar os dados fiscais

1. 1
   Vá em Notas Fiscais e abra a Configuração de NFS-e.
2. 2
   Preencha os dados que o seu município exige: e-mail, inscrição municipal, CNAE, item da lista de serviço, regime especial de tributação, série e número do RPS, usuário e senha da prefeitura e se é optante pelo Simples Nacional.
3. 3
   Clique em Salvar. Ao salvar com sucesso, a emissão de NFS-e fica habilitada.

Passo 2: Definir o serviço municipal padrão

Para a nota já vir preenchida e evitar erro na hora de emitir, defina um serviço padrão na aba Serviços da Configuração de NFS-e:

1. 1
   Se a sua conta lista os serviços, escolha um da lista e clique em Definir padrão.
2. 2
   Se a sua conta usa código manual (comum no Portal Nacional), preencha código do serviço, descrição e alíquota ISS e clique em Salvar serviço padrão.

Passo 3: Emitir a nota

Você pode emitir a NFS-e a partir do lançamento ou dos detalhes da cobrança:

1. 1
   No Lançamentos , no menu de ações de um lançamento de receita, clique em Emitir nota fiscal. (Também dá para emitir pelos detalhes da cobrança em Relatórios Asaas .)
2. 2
   Confira os dados pré-preenchidos (cliente, valor, descrição e serviço padrão) e escolha quando emitir: Agora, no vencimento, alguns dias antes ou no 1º dia do mês.
3. 3
   Clique em Emitir nota (ou Agendar nota). Não é preciso esperar o pagamento: dá para emitir antes.
4. 4
   A nota vai ao Asaas, que a registra na prefeitura. O status começa como agendada e passa a autorizada quando a prefeitura aprova. Quando autorizada, o PDF fica disponível e a NFS-e aparece refletida no lançamento (número, status e link). Use Visualizar nota fiscal no menu do lançamento.

Passo 4: Gerenciar a nota (atualizar, cancelar, reemitir)

Tudo nos detalhes da cobrança, sem abrir o Asaas:

• Atualizar status: busca no Asaas o status mais recente da nota (útil enquanto a prefeitura processa).
• Cancelar NFS-e: cancela a nota na prefeitura, com confirmação. (É uma nota fiscal de verdade, confira antes.)
• Reemitir NFS-e: quando a nota anterior falhou ou foi cancelada, gera uma nova por cima.

Status que você vai ver

• Pendente: emitida, aguardando pagamento.
• Paga: pagamento confirmado (entra automaticamente).
• Vencida: passou da data sem pagamento.
• Cancelada: cancelada manualmente ou no Asaas.
• Reembolsada: valor devolvido.
• Recorrente: filtro para ver só cobranças de assinaturas.

A atualização acontece sozinha, em segundos após o pagamento, na maioria dos casos.

Limitações conhecidas

• Split de pagamento e antecipação de recebíveis são feitos no painel do Asaas.
• A taxa do Asaas não vira despesa automática: o lançamento é pelo valor bruto.
• Editar cliente no Coconut não re-sincroniza o cadastro no Asaas.
• Emissão automática de NFS-e a cada cobrança da assinatura ainda não é automática: emita ou agende a nota por cobrança.
• NFS-e é só para serviços (não emite nota de produto).
• Saque e transferência nunca são feitos pelo Coconut, só pelo painel do Asaas.

Custos

O Coconut não cobra nada a mais por transação. As taxas são as da sua conta Asaas, conforme o plano que você contratou com eles. Consulte o painel do Asaas.

Perguntas frequentes