> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Asaas

> Conecte sua conta Asaas por chave de API e envie mensagens automáticas a cada evento de cobrança: criada, vencida, paga e lembrete antes do vencimento

A integração com o **Asaas** conecta sua conta de cobranças à OctaSend por uma chave de API. Com ela você manda mensagens automáticas a cada evento de cobrança (criada, vencida, paga, lembrete antes do vencimento) pelos canais que você já usa, como WhatsApp, e-mail e SMS.

Diferente das integrações de loja, o Asaas não traz pedidos nem produtos: ele trabalha com **cobranças** e **clientes**.

## Conectar

**1. Gere uma chave no Asaas**

No Asaas, abra **Integrações → Chaves de API** e gere uma chave. Ela precisa poder **ler cobranças e clientes** e **gerenciar webhooks**.

**2. Cole a chave na OctaSend**

Na OctaSend, abra **Configurações → Desenvolvedores → Integrações**, clique em **Conectar** no card do Asaas, cole a chave em **Chave de API** e clique em **Conectar**.

A OctaSend confere a chave na hora e só salva se ela funcionar. Chave inválida, revogada ou sem permissão aparece com a explicação em português, e nada é gravado.

* Cada conta OctaSend conecta **uma conta Asaas**.
* A chave salva nunca volta para a tela. Para trocar, cole uma nova em **Editar conexão**.

### Sandbox e produção

Chaves de sandbox também funcionam e são o jeito certo de testar. O ambiente sai do início da chave: a que começa com `$aact_hmlg_` é sandbox; qualquer outra é tratada como produção. O card da integração mostra o selo **Sandbox** enquanto a conexão for de sandbox. Para passar para produção, clique em **Editar conexão** e cole a chave de produção.

### O webhook é criado sozinho

Ao conectar, a OctaSend cadastra na sua conta Asaas um webhook chamado **OctaSend**, com envio em ordem (sequencial) e os eventos de cobrança listados abaixo. Não é preciso configurar nada no Asaas.

Se o Asaas recusar o cadastro (por exemplo, a conta já tem os **10 webhooks** que o Asaas permite), a conexão fica salva e o card avisa. Apague um webhook que você não usa na sua conta do Asaas e clique em **Salvar** na tela de eventos: a OctaSend cadastra de novo e o aviso some.

## Desligue as notificações do Asaas

O Asaas manda e-mail e SMS próprios quando uma cobrança é criada, vence ou é paga. Se a OctaSend vai avisar seus clientes, desligue esses avisos nas configurações de notificação do Asaas, senão o cliente recebe duas mensagens para o mesmo fato. A OctaSend não altera essa configuração da sua conta.

## Mapear os eventos

Em **Configurações → Desenvolvedores → Integrações**, clique em **Configurar eventos** no card do Asaas. Na aba **Mapeamento de eventos**, escolha uma comunicação para cada evento e clique em **Salvar**. Evento sem comunicação (**Não enviar nada**) não dispara nada.

| Evento | Quando acontece | Mensagem uma vez por cobrança? |
| - | - | - |
| **Cobrança criada** | Uma cobrança nova é criada no Asaas | Sim |
| **Cobrança alterada** | Valor, vencimento ou outro dado da cobrança muda | Não: cada alteração pode gerar mensagem |
| **Cobrança vencida** | A cobrança passa do vencimento sem pagamento | Sim |
| **Pagamento confirmado** | O Asaas confirma o pagamento (no cartão, confirmação e recebimento viram uma mensagem só) | Sim |
| **Cobrança estornada** | O pagamento é estornado | Sim |
| **Cobrança removida** | A cobrança é removida no Asaas | Sim |
| **Fatura visualizada** | O cliente abre o boleto ou a fatura | Sim (só a primeira vez) |
| **Vencimento próximo** | Faltam N dias para vencer ([veja abaixo](#lembrete-de-vencimento)) | Uma vez por cobrança e data de vencimento |

Os mesmos eventos aparecem nas [automações](https://docs.octasend.com.br/plataforma/automacoes.md), no gatilho **Evento de uma integração** e no passo **Aguardar evento**. A coluna acima vale para o mapeamento direto (evento para comunicação); as automações têm uma regra própria, descrita em Limitações.

Outros eventos que o Asaas mandar (assinaturas, análise de risco e similares) são recebidos e ignorados.

## Variáveis

O painel lateral da tela de eventos mostra as variáveis, com botão para copiar. Todas valem para todos os eventos.

| Variável | O que traz |
| - | - |
| `{{cliente_nome}}` | Nome do cliente da cobrança |
| `{{cobranca_valor}}` | Valor, já com R$ (por exemplo, R$ 1.234,56) |
| `{{cobranca_vencimento}}` | Vencimento (dd/mm/aaaa) |
| `{{cobranca_forma_pagamento}}` | Boleto, Pix, Cartão de crédito, Cartão de débito, Transferência, Depósito, A definir ou Dinheiro |
| `{{cobranca_descricao}}` | Descrição da cobrança |
| `{{cobranca_link_fatura}}` | Link da fatura no Asaas |
| `{{cobranca_link_boleto}}` | Link do boleto em PDF |
| `{{cobranca_linha_digitavel}}` | Linha digitável do boleto |
| `{{cobranca_pix_copia_cola}}` | Código Pix copia e cola |
| `{{cobranca_referencia}}` | Referência externa que você deu à cobrança |
| `{{cobranca_parcela}}` | Número da parcela |

> [!NOTE]
>
> A linha digitável e o Pix só vêm quando a cobrança ainda está em aberto (criada, alterada, vencida, fatura visualizada, vencimento próximo) e quando a forma de pagamento tem esses códigos. Se o Asaas não devolver o código, a variável fica vazia e a mensagem sai assim mesmo.

### Quem recebe a mensagem

A mensagem vai para o celular do cliente no Asaas (ou o telefone fixo, se não houver celular) e para o e-mail dele. A opção "desabilitar notificações" do cliente no Asaas vale só para as notificações do próprio Asaas e não bloqueia as da OctaSend.

Cobrança de cliente sem telefone e sem e-mail aparece no histórico como **Ignorado**, com o motivo. O contato é criado na OctaSend na primeira mensagem; não há importação dos clientes do Asaas.

## Lembrete de vencimento

O Asaas não avisa "vai vencer", então a OctaSend procura sozinha: **de hora em hora**, ela lista as cobranças **pendentes** que vencem daqui a **N dias** (calendário de Brasília) e dispara o evento **Vencimento próximo** para cada uma. Rodar de hora em hora não repete a mensagem.

> [!NOTE]
>
> O lembrete só procura cobranças **a partir das 08:00 (horário de Brasília)**, para a mensagem não chegar de madrugada. Isso vale também para o **Executar agora**.

Configure em **Configurar eventos → aba Rotinas → Lembrete de vencimento**:

| Campo | O que faz |
| - | - |
| **Ativo** | Liga ou desliga o lembrete |
| **Avisar quantos dias antes do vencimento** | De 0 a 30 (padrão 3; com 0, o aviso sai no dia do vencimento) |
| **Salvar alterações** | Grava a configuração |
| **Executar agora** | Roda a busca na hora, sem esperar a próxima rodada |

Se a cobrança for paga (ou deixar de estar pendente) entre a busca e o envio, o lembrete não sai e aparece no histórico como **Ignorado**, com o motivo. O lembrete só consulta o Asaas quando o evento **Vencimento próximo** tem comunicação mapeada ou é usado numa automação ativa.

> [!TIP]
>
> Para uma régua de cobrança depois do vencimento ("vencida há N dias"), monte uma automação com o gatilho **Cobrança vencida**, o passo **Aguardar evento: Pagamento confirmado** com prazo e o envio no caminho de prazo esgotado. Veja as limitações abaixo.

## Acompanhar

A aba **Eventos recebidos** mostra cada evento com o resultado (a aba **Logs** traz o histórico das rotinas e dos avisos recebidos):

| Resultado | Quando |
| - | - |
| **Recebido** | O aviso chegou e ainda está sendo processado |
| **Enviado** | Aceito pelo canal ou colocado na fila |
| **Ignorado** | Sem comunicação mapeada, sem destinatário, já enviado para esta cobrança, ou lembrete de cobrança que já não está em aberto |
| **Falhou** | Houve erro; o motivo aparece junto |

Na aba **Logs**, **Ver detalhes** mostra o que o Asaas mandou. A execução do lembrete aparece em **Logs** como "Rotina: Lembrete de vencimento", com quantas cobranças encontrou.

Se a chave for revogada depois de conectada, os eventos passam a falhar e o card mostra o erro. Gere uma chave nova e cole em **Editar conexão**.

## Fila pausada no Asaas

O Asaas entrega cada evento até receber confirmação. Depois de 15 falhas seguidas, ele **pausa a fila** do webhook. Para reativar, clique em **Salvar** na tela de eventos (ou em **Salvar conexão** em **Editar conexão**): a OctaSend atualiza o webhook e tira a fila da pausa.

## Limitações

* Uma conta Asaas por conta OctaSend.
* As notificações do próprio Asaas continuam ligadas até você desligá-las.
* **Automações começam uma vez por cobrança.** Uma automação com gatilho **Vencimento próximo** ou **Cobrança alterada** inicia o fluxo uma única vez para cada cobrança: se o vencimento mudar ou a cobrança for alterada de novo, o fluxo não recomeça para a mesma cobrança. No mapeamento direto, **Cobrança alterada** envia a cada alteração, e **Vencimento próximo** envia de novo quando a data de vencimento muda.
* No **Aguardar evento**, a espera é destravada pelo **cliente**, não pela cobrança: um cliente com duas cobranças vencidas que paga uma destrava o fluxo das duas.
* **Cobrança vencida** sai assim que o Asaas avisa que a cobrança venceu, e a OctaSend não segura a mensagem até o horário comercial. Com o mapeamento direto, ela pode chegar de madrugada. Para enviar durante o dia, use uma automação com o gatilho **Cobrança vencida** e um passo de espera antes do envio.
* Assinaturas, chargeback e split não fazem parte desta integração.

## Desconectar

Desconectar remove o webhook **OctaSend** da sua conta Asaas. Se o Asaas não responder, a integração é desconectada mesmo assim e o webhook pode ficar lá: apague-o na sua conta do Asaas.

## Veja também

> [card] [Integrações](https://docs.octasend.com.br/integracoes/visao-geral.md)
>
> As plataformas disponíveis e o que muda entre elas

> [card] [Automações](https://docs.octasend.com.br/plataforma/automacoes.md)
>
> Régua de cobrança com esperas e condições

> [card] [Conta Azul](https://docs.octasend.com.br/integracoes/conta-azul.md)
>
> Outra integração financeira, com contas a receber

> [card] [E-commerce](https://docs.octasend.com.br/plataforma/ecommerce.md)
>
> Clientes, pedidos e produtos sincronizados


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.