A conexão com o Asaas usa a chave de API da sua conta, que você gera no próprio Asaas e cola na Toca. Não é o seu e-mail nem a sua senha de login. Com ela, a Toca consulta a sua conta a cada pergunta e prepara as alterações que você aprovar.
É a sua conta Asaas de cobranças, a dos seus clientes. Ela não tem relação com a assinatura da Toca, mesmo que você pague a Toca por boleto ou Pix do Asaas.
Esta integração está em homologação: a conexão funciona normalmente, mas as consultas no chat ainda estão em validação.
Antes de começar
- Use um usuário administrador da conta Asaas: só administrador gera chave de API, e só pela versão web (o aplicativo não gera).
- Na web do Asaas, vá em Integrações → Chaves de API e gere uma chave nova. Dê um nome como Toca. Se quiser, defina uma data de expiração.
- Copie a chave na hora: o Asaas mostra a chave uma vez só. Ela começa com
$aact_prod_; copie inteira, com o cifrão. - Use a chave de produção. A chave do Sandbox (
$aact_hmlg_) é do ambiente de testes do Asaas, com outra conta e outro saldo, e a Toca não a aceita. - Se a sua conta usa Whitelist de IPs (em Integrações → Mecanismos de segurança), o Asaas recusa as chamadas da Toca: ela chama o Asaas de servidores sem endereço fixo.
Passo a passo
- Acesse
Configurações → Integraçõesna Toca. - Localize o card Asaas e clique em Conectar.
- Cole a chave no campo Chave de API ($aact_).
- Clique em Salvar. O card fica marcado como conectado.
O que a Toca acessa
Com a conexão ativa, a Toca lê as cobranças por boleto, Pix e cartão, com status, vencimento, data de pagamento e data prevista de crédito; os totais do que foi recebido, do que está a receber e do que venceu; os clientes e as notificações de cobrança de cada um; as assinaturas e os parcelamentos, com as cobranças de cada um; os links de pagamento; as notas fiscais de serviço; o saldo, o extrato e os valores de split; as transferências, os pagamentos de contas e as recargas; as antecipações e os limites; as negativações e as consultas Serasa já feitas; os estornos e os chargebacks; as chaves Pix, as transações Pix, o Pix Automático e o Pix Recorrente; as subcontas, os webhooks e os dados e as taxas da conta.
A Toca também altera: gera, altera, cancela e restaura cobranças (boleto, Pix, ou cartão pago pelo cliente na fatura), dá baixa de recebimento em dinheiro e estorna; cria e altera clientes, assinaturas (inclusive pausar) e parcelamentos; agenda, emite e cancela nota fiscal de serviço; cria links de pagamento e QR Codes Pix; solicita e cancela antecipação; negativa cobrança vencida; paga boletos e QR Codes Pix com o saldo; faz saque para a conta bancária ou chave Pix do próprio titular da conta; e cuida de notificações e webhooks. Toda alteração só acontece mediante sua aprovação explícita, pedido a pedido, dentro do chat.
Algumas alterações não se desfazem, e o pedido de aprovação diz isso: estornar, cancelar cobrança, antecipar, negativar, pagar conta ou QR Code, recarregar celular, sacar e emitir ou cancelar nota fiscal. Além da sua aprovação na Toca, o Asaas pode segurar saques, pagamentos de contas, Pix pagos e recargas até você aprovar também no aplicativo ou na web do Asaas.
O que a Toca não faz pelo Asaas: transferir para conta de outra pessoa ou empresa, cobrar cartão com os dados do cartão (o cliente paga pela fatura do Asaas), enviar arquivos (documentos, imagens, provas de chargeback), consultar o Serasa, criar subconta ou chave de API e mexer nos dados comerciais e fiscais da conta. Isso continua pelo painel do Asaas.
Manutenção da conexão
A chave não vence por tempo de uso, mas o Asaas a desabilita depois de 3 meses sem nenhuma chamada e a expira de vez aos 6 meses, avisando por e-mail antes. Se você definiu data de expiração, ela para nesse dia. Para trocar a chave, gere uma nova no Asaas, abra o card em Configurações → Integrações pelo botão Gerenciar, cole a chave nova e clique em Atualizar. Por segurança, a chave salva aparece mascarada.
O Asaas aceita até 25 mil chamadas por conta a cada 12 horas, somando todos os sistemas ligados à conta. A Toca faz poucas consultas por vez, mas se a sua loja, o ERP e outros sistemas usam a mesma conta, o limite é dividido entre eles.
Problemas comuns
- O Asaas responde que não autorizou (401) — confira se colou a chave inteira, com o cifrão e sem espaço. O mesmo erro aparece quando a chave foi desabilitada por falta de uso (reative em Integrações → Chaves de API) ou quando expirou ou foi excluída (gere outra e atualize o card).
- A chave é recusada ao salvar — a chave de Sandbox (
$aact_hmlg_) não serve; gere a de produção. - Acesso negado (403) — a conta está com a Whitelist de IPs ligada. A Toca não tem endereço fixo e não funciona com ela ligada; a decisão de desligar é sua.
- A Toca disse que o saque ou o pagamento foi pedido, mas o dinheiro não saiu — o Asaas está esperando a sua aprovação no aplicativo ou na web. Aprove lá.
- O Asaas pede para esperar (429) — o limite de chamadas da conta estourou. Espere um pouco e peça de novo.
- Conectou a conta errada — use Excluir integração no menu ⋯ do card e conecte de novo, com a chave da conta certa.