Configuração do gateway de pagamento Asaas

O que e a integracao Asaas no eSocial Brasil

O Asaas e o gateway de pagamento utilizado pela plataforma eSocial Brasil para gerenciar cobrancas, boletos e pagamentos via PIX. A configuracao correta das chaves de API e dos webhooks e essencial para o funcionamento do faturamento automatizado da consultoria, garantindo que cada cobranca gerada tenha seu status atualizado sem intervencao manual.

Requisitos previos para configurar o gateway

Antes de iniciar a integracao, confirme se voce atende aos pre-requisitos abaixo:

Possuir uma conta no Asaas (ambiente sandbox para testes ou producao para cobrancas reais).
Ter acesso de administrador ou ser o responsavel pela consultoria no sistema.
CNPJ da consultoria devidamente cadastrado e validado no Asaas.

Como configurar a API Key do Asaas

A API Key e a credencial que autoriza o eSocial Brasil a criar cobrancas em nome da consultoria. Siga o passo a passo:

Acesse o painel do Asaas e navegue ate Configuracoes > Integracao.
Copie a API Key de producao (ou a chave de sandbox para ambiente de testes).
No sistema eSocial Brasil, acesse Configuracoes > Gateway de Pagamento.
Cole a API Key no campo Chave de API Asaas.
Opcionalmente, informe o Wallet ID caso utilize subcontas (split de pagamento).
Ative a opcao Asaas Ativo para habilitar a integracao.
Clique em Salvar configuracoes.

Producao ou sandbox: qual ambiente usar

Utilize o ambiente sandbox para validar todo o fluxo sem gerar cobrancas reais e migre para a chave de producao apenas quando o teste de ponta a ponta estiver aprovado.

Configuracao de webhooks do Asaas

Os webhooks permitem que o Asaas notifique o sistema automaticamente sobre eventos de pagamento (confirmacao, cancelamento, vencimento), mantendo o status das faturas sempre sincronizado.

Ao salvar as configuracoes, o sistema cria automaticamente o webhook no Asaas com a URL correta.
Os eventos monitorados incluem: pagamento confirmado, pagamento vencido, cobranca cancelada e pagamento estornado, entre outros.
O webhook utiliza um token de autenticacao unico para validar as requisicoes recebidas.
Caso o webhook ja exista, o sistema atualiza a configuracao existente automaticamente.

Resumo dos campos e eventos da integracao

Item	Funcao	Obrigatorio
Chave de API Asaas	Autoriza a criacao de cobrancas	Sim
Wallet ID	Split de pagamento via subcontas	Nao
Asaas Ativo	Habilita a integracao	Sim
Webhook (URL + token)	Recebe notificacoes de pagamento	Criado automaticamente
Empresas para gerar fatura	Define quem sera faturado	Conforme necessidade

Subcontas da consultoria

Consultorias podem configurar subcontas no Asaas para receber pagamentos diretamente. Cada subconta esta vinculada a uma consultoria especifica e possui suas proprias credenciais de acesso.

Selecao de empresas para faturamento

Na tela de configuracao, voce pode selecionar quais empresas-cliente terao faturas geradas automaticamente pelo sistema. Marque as empresas desejadas no campo Empresas para gerar fatura.

Verificacao e testes da integracao

Apos configurar, gere uma cobranca de teste para validar o fluxo completo.
Verifique no painel Asaas se o webhook foi registrado corretamente em Configuracoes > Webhooks.
Confirme que o status das faturas atualiza automaticamente apos o pagamento do boleto de teste.

Solucao de problemas comuns

Erro ao salvar: verifique se a API Key esta correta e se o CNPJ da consultoria esta validado no Asaas.
Webhook nao dispara: confirme que a URL do webhook esta acessivel publicamente (sem bloqueio de firewall).
Pagamento nao atualiza: verifique os logs do sistema em caso de falha no processamento do webhook.

Perguntas frequentes

Preciso criar o webhook manualmente no Asaas? Nao. Ao salvar as configuracoes no eSocial Brasil, o sistema cria e configura o webhook automaticamente com a URL e o token corretos.

Posso testar sem gerar cobrancas reais? Sim. Use a API Key do ambiente sandbox do Asaas para validar todo o fluxo antes de ativar a chave de producao.

Para que serve o Wallet ID? Ele e usado apenas quando ha split de pagamento via subcontas, direcionando os valores para a conta correta da consultoria.