> For the complete documentation index, see [llms.txt](https://ajuda.financeiro.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ajuda.financeiro.app/guia-completo/integracoes/como-integrar-o-asaas-ao-falcon-financas.md).

# Como integrar o Asaas ao Falcon Finanças

O [**Falcon Finanças**](https://falcon.financeiro.app) utiliza uma chave de API para se comunicar com sua conta Asaas. Com a integração configurada, você pode gerar boletos, acompanhar cobranças e consultar saldo e extrato sem sair do Falcon.

Neste guia você aprenderá a:

* gerar uma chave de API no Asaas;
* ativar a integração geral da empresa no Falcon;
* vincular uma conta financeira específica ao Asaas;
* testar a conexão;
* atualizar uma chave inválida, desabilitada ou expirada.

## Antes de começar

Você precisa ter:

* uma conta ativa no Asaas;
* acesso ao Asaas pelo navegador de internet;
* um usuário **administrador** no Asaas;
* permissão para acessar **Sistema > Configuração do Sistema** no Falcon.

Se ainda não possui uma conta, faça o cadastro pelo [link de indicação do Falcon](https://www.asaas.com/r/7JIJZ9BL).

{% hint style="info" %}
O Asaas permite gerar chaves de API somente pela versão web e para usuários administradores. A opção não fica disponível no aplicativo.
{% endhint %}

## 1. Gerar a chave de API no Asaas

1. Acesse sua conta Asaas pelo navegador.
2. Abra **Integrações > Chaves de API**.
3. Clique em **Gerar chave de API** ou **Gerar nova chave de API**.
4. Dê um nome que facilite a identificação, como **Falcon Finanças**.
5. Confira a data de expiração, caso escolha definir uma.
6. Gere a chave e copie o valor completo imediatamente.
7. Guarde a chave em um local seguro até concluir a configuração no Falcon.

<figure><img src="/files/5Wlq1OQM8SyhrljVtsOp" alt="Tela de Chaves de API do Asaas com o botão para gerar uma nova chave"><figcaption><p>Gere a chave na área de Integrações do Asaas.</p></figcaption></figure>

O Asaas exibe o conteúdo completo da chave somente no momento da criação. Se você fechar a tela sem copiá-la, será necessário gerar outra chave.

Para consultar as regras atuais, veja também a [documentação oficial sobre chaves de API](https://docs.asaas.com/docs/chaves-de-api).

## 2. Ativar a integração geral da empresa

Esta é a configuração principal usada pelo Falcon para gerar boletos e como chave padrão para consultar o Asaas.

1. No Falcon, acesse **Sistema > Configuração do Sistema**.
2. Abra a guia **Integrações**.
3. Na seção **Plataforma Asaas - Chave de API - Boletos**, cole a chave no campo **Chave**.
4. Mude a opção **Ativo** para **Sim**.
5. Clique em **Salvar**.

<figure><img src="/files/PuAlGwLOAqD5QkCth4DC" alt="Configuração do Sistema do Falcon na guia Integrações com o campo de chave do Asaas"><figcaption><p>Informe a chave, ative a integração e salve a configuração.</p></figcaption></figure>

{% hint style="warning" %}
Não use uma chave de Sandbox na operação normal do Falcon. A integração de produção precisa da chave gerada na sua conta Asaas de produção.
{% endhint %}

## 3. Configurar uma Conta Conectada do Asaas

A chave geral atende a operação padrão. A **Conta Conectada** é útil para associar a credencial a uma conta financeira específica e também permite selecionar a conta correta no **Extrato do Asaas** quando a empresa trabalha com mais de uma conta Asaas.

1. Acesse **Cadastros > Contas**.
2. Crie uma conta ou edite a conta que representa o Asaas.
3. Confira se o tipo da conta é **Banco** e se o banco selecionado é **Asaas**.
4. Ative a opção **Conta Conectada**.
5. Abra a guia **Conta Conectada**.
6. Cole a chave no campo do Asaas.
7. Clique em **Testar Conexão**.
8. Aguarde a mensagem **Conexão com o Asaas efetuada com sucesso**.
9. Clique em **Salvar**.

<figure><img src="/files/pOySR2sMJ8vhsiVWTKyr" alt="Cadastro de uma conta Asaas no Falcon com a opção Conta Conectada ativada"><figcaption><p>Ative a Conta Conectada no cadastro da conta Asaas.</p></figcaption></figure>

<figure><img src="/files/Vdnv3iK4Hc1gk5PZU4oY" alt="Guia Conta Conectada do cadastro de contas com o campo da chave de API e o botão Testar Conexão"><figcaption><p>Informe a chave, teste a conexão e salve a conta.</p></figcaption></figure>

### Qual configuração o Falcon utiliza?

* **Boletos:** utilizam a chave geral salva na integração da empresa.
* **Extrato sem uma Conta Conectada selecionada:** utiliza a chave geral da empresa.
* **Extrato de uma Conta Conectada:** utiliza a chave salva no cadastro daquela conta.

Por isso, se você trocar a chave em **Configuração do Sistema**, mas o extrato continuar informando que a chave está inválida, abra também **Cadastros > Contas** e atualize a chave da Conta Conectada selecionada.

## 4. Validar a integração

Depois de salvar, faça estes testes:

1. Acesse **Financeiro > Extrato do Asaas**.
2. Se houver mais de uma Conta Conectada, selecione a conta desejada.
3. Informe o período e clique em **Atualizar**.
4. Confira se o Falcon apresenta saldo, entradas, saídas e movimentações.
5. Acesse **Financeiro > Contas a Receber**, selecione uma receita e abra a opção **Boleto** para confirmar que a configuração está disponível.

Você não precisa emitir uma cobrança apenas para testar. Se a tela do boleto reconhecer a chave e liberar a área de geração, a configuração principal está disponível.

## Segurança da chave de API

Trate a chave como uma senha da sua conta Asaas:

* não envie a chave por e-mail, WhatsApp, chat ou chamado;
* não coloque a chave em documentos ou imagens compartilhadas;
* não publique prints que mostrem o valor da chave;
* mantenha acesso à configuração apenas para usuários autorizados;
* se houver suspeita de vazamento, desabilite ou exclua a chave no Asaas, gere outra e atualize o Falcon;
* ao definir uma data de expiração, programe a substituição antes do vencimento.

## Como trocar ou renovar a chave

1. No Asaas, acesse **Integrações > Chaves de API**.
2. Confirme se a chave atual está habilitada.
3. Se necessário, gere uma nova chave e copie o valor completo.
4. No Falcon, atualize a chave em **Sistema > Configuração do Sistema > Integrações**.
5. Atualize também cada conta em **Cadastros > Contas > Conta Conectada** que use a chave antiga.
6. Salve e repita os testes do extrato e da tela de boleto.

Depois de validar a nova chave, desabilite ou exclua a anterior no Asaas se ela não for mais necessária.

## Solução de problemas

### Não encontro o menu Integrações no Asaas

A geração da chave exige acesso pela versão web e um usuário administrador. Entre pelo navegador com um administrador da conta.

### O Falcon informa que a chave é inválida ou expirou

Confira se:

* a chave foi copiada por completo;
* a chave está habilitada no Asaas;
* a chave pertence ao ambiente de produção;
* a chave não foi excluída ou substituída;
* a data de expiração ainda é válida.

Se não for possível recuperar a chave, gere uma nova e atualize todos os locais em que a chave antiga foi cadastrada no Falcon.

### O boleto funciona, mas o extrato apresenta erro de chave

O boleto pode estar usando a chave geral enquanto o extrato usa a chave da Conta Conectada. Atualize a credencial em **Cadastros > Contas**, teste a conexão e salve novamente.

### A conta não aparece no Extrato do Asaas

Confira no cadastro da conta se:

* a conta está ativa;
* o banco selecionado é **Asaas**;
* a opção **Conta Conectada** está ativa;
* a chave foi informada e passou no teste de conexão.

### Troquei a chave e as cobranças antigas desaparecerão?

Não. A troca da credencial não exclui lançamentos ou boletos já registrados no Falcon. Porém, consultas de status, saldo e extrato ficarão indisponíveis enquanto não houver uma chave válida.

## Próximos passos

Com a integração pronta, consulte:

* [**Como gerar boletos pelo Asaas**](/guia-completo/integracoes/como-gerar-boletos-pelo-asaas.md);
* [**Como utilizar o extrato do Asaas**](/guia-completo/integracoes/como-utilizar-o-extrato-do-asaas.md).