Pular para o conteúdo

Conectar o provedor de cobranças (Asaas ou Efí)

Credencie uma conta financeira no Asaas ou na Efí Bank para emitir boletos, Pix, carnês e cobranças por cartão e receber as baixas automáticas.

Intermediário6 min de leituraAtualizado em 13 de novembro de 2026

Para emitir boletos, Pix, carnês e cobranças por cartão pelo Orvya, o escritório conecta uma conta financeira à sua própria conta em um provedor de cobrança: o Asaas ou a Efí Bank. Esse vínculo se chama credenciamento. Depois dele, as cobranças saem em nome do escritório, o dinheiro cai na conta do escritório no provedor e o Orvya dá baixa sozinho nos lançamentos e nas faturas quando o cliente paga.

Onde fica

  • Configurações › Integrações › Cobranças. Com mais de uma conta financeira, escolha a conta no campo Conta financeira.
  • Financeiro › Configurações › Contas › link Credenciar para emitir cobranças na linha da conta.
  • No menu lateral, Cobranças: sem conta credenciada, a página mostra o botão Credenciar uma conta.

Cada conta financeira tem um único provedor. Para usar os dois provedores, credencie duas contas diferentes.

Antes de começar

  • Asaas: gere uma chave em Integrações › Chaves de API, no painel do Asaas. A chave de produção começa com $aact_prod_ e a de testes (Sandbox), com $aact_hmlg_.
  • Efí Bank: crie uma aplicação em API › Aplicações, no painel da Efí, com os escopos da API Cobranças, e copie o Client_Id e o Client_Secret do mesmo ambiente (produção ou homologação). Para o boleto sair com QR Code Pix (Bolix), ative o Bolix nas configurações de boletos da conta Efí.

Credenciar no Asaas

  1. Abra a conta em Configurações › Integrações › Cobranças.
  2. No card 1. Conta Asaas, em Provedor, deixe Asaas.
  3. Em Ambiente, escolha Produção para cobranças reais ou Sandbox (testes) para experimentar. O campo começa em Sandbox (testes).
  4. Cole a Chave de API.
  5. No card 2. Testar conexão, clique em Testar conexão. Com sucesso, aparece Conectado — Wallet seguido do identificador da carteira e do saldo disponível.
  6. Revise o card 3. Padrões de cobrança (veja abaixo).
  7. No card 4. Webhook, clique em Salvar credenciamento. O botão só fica ativo depois de um teste com sucesso.

Aparece Credencial salva e webhook ativo. O Orvya cadastra sozinho, na sua conta Asaas, o webhook que avisa os pagamentos.

Quando o webhook não é cadastrado

Se o Asaas recusar o cadastro automático (por exemplo, pelo limite de 10 webhooks na conta), aparece Credencial salva. O webhook ainda precisa ser ativado. e a janela Cadastre o webhook manualmente, com a URL e o Token de autenticação.

  1. Copie a URL e o token. O token é exibido somente nesse momento.
  2. No painel do Asaas, em Integrações › Webhooks, crie um webhook com esses dados.
  3. Volte ao Orvya e clique em Já cadastrei — verificar. Com o webhook encontrado, aparece Webhook encontrado e ativo.

Enquanto isso, a conta aparece como Concluir credenciamento em Financeiro › Configurações › Contas.

Credenciar na Efí Bank

  1. Abra a conta em Configurações › Integrações › Cobranças.
  2. Em Provedor, escolha Efí Bank.
  3. Em Ambiente, escolha Produção para cobranças reais ou Homologação (testes) para experimentar.
  4. Cole o Client_Id e o Client_Secret.
  5. Clique em Testar conexão. Com sucesso, aparece Conectado — credenciais válidas.
  6. Revise os padrões de cobrança e clique em Salvar credenciamento.

Aparece Credencial salva. As cobranças da Efí já podem ser emitidas. A Efí não usa webhook cadastrado na conta: cada cobrança emitida pelo Orvya informa o endereço de notificação, e não há nada a cadastrar no painel da Efí. Logo depois do credenciamento, o Orvya carrega também as cobranças que já existiam na Efí, inclusive as emitidas pelo painel ou pelo aplicativo dela.

Certificado da API Pix (extrato)

Para ver o saldo e gerar o Extrato da conta Efí em Relatórios, envie também o certificado da sua aplicação. As cobranças funcionam sem ele.

  1. Na Efí, em API › Meus certificados, gere o certificado do mesmo ambiente da conta e baixe o arquivo .p12. Na aplicação, ative os escopos de consulta de saldo, Pix recebidos e Pix enviados.
  2. No Orvya, depois de salvar o credenciamento, aparece na página da conta o card Certificado da API Pix (extrato). Clique em Enviar certificado (.p12) e escolha o arquivo.
  3. Confira os escopos testados. Com tudo certo, aparece Certificado salvo. O extrato será sincronizado em instantes.

O card mostra a impressão digital, a validade e a última sincronização do extrato. Toda segunda-feira o Orvya confere a validade e avisa os administradores quando o certificado vence em até 30 dias ou já venceu.

Padrões de cobrança

Os padrões valem para as cobranças emitidas a partir de lançamentos e faturas e preenchem o formulário de novas cobranças:

  • Multa por atraso (%): de 0 a 10. Começa em 2.
  • Juros ao mês (%): de 0 a 10. Começa em 1. Na Efí, o valor é convertido em juros diários (1% ao mês ≈ 0,033% ao dia).
  • Dias para pagar após o vencimento (só Efí): de 0 a 120. Vazio usa o padrão da Efí.
  • Desconto para pagamento antecipado: ao ligar, escolha o Desconto, o Tipo (Percentual (%) ou Valor fixo (R$)) e os Dias antes do vencimento (de 0 a 60).
  • Instruções: até 500 caracteres, enviados na descrição da cobrança (na Efí, também nas linhas do boleto).
  • Asaas envia notificações ao cliente (só Asaas): o Asaas avisa o cliente por conta própria.
  • Registrar tarifa do Asaas como saída ("Tarifas Bancárias") (só Asaas): ligado por padrão. Quando o cliente paga uma cobrança emitida por um lançamento ou por uma fatura, a tarifa vira um lançamento de saída já pago, na mesma conta.

Depois do credenciamento, altere os padrões e clique em Salvar padrões. Aparece Padrões de cobrança salvos.

Trocar ou remover o credenciamento

  • Trocar chave (Asaas) ou Trocar credenciais (Efí): refaz o teste e grava a nova credencial, mantendo o mesmo provedor.
  • Remover credenciamento: as cobranças já emitidas continuam válidas no provedor, mas o Orvya deixa de receber as baixas automáticas. Para trocar de provedor, remova o credenciamento atual antes.

Contas em Sandbox ou Homologação mostram, em Cobranças, a etiqueta de cobranças sem valor real. Use esses ambientes só para testes.

Se algo der errado

"Chave de produção usada no ambiente Sandbox."

ou "Chave de Sandbox usada no ambiente de Produção." A chave não é do ambiente escolhido. Troque o Ambiente ou gere a chave certa no Asaas.

"Chave inválida ou desabilitada"

. A chave do Asaas foi digitada errada, expirou ou foi desativada. Gere uma nova em Integrações › Chaves de API.

"Client_Id ou Client_Secret inválidos para este ambiente da Efí."

Confira se as credenciais são do mesmo ambiente escolhido e se a aplicação tem os escopos da API Cobranças.

"Somente administradores podem credenciar contas para emitir cobranças."

Peça a um administrador do escritório para fazer o credenciamento.

"Esta conta está credenciada no Asaas. Remova o credenciamento atual antes de trocar de provedor."

Remova o credenciamento ou credencie outra conta financeira no novo provedor.

"Webhook ainda não encontrado no Asaas."

O webhook ainda não foi criado ou os dados não conferem. Revise a URL e o token no painel do Asaas e verifique de novo.

"Este certificado está vencido. Gere um novo na Efí (API › Meus certificados)."

Gere um certificado novo e envie pelo botão Trocar certificado.

Continue em Cobranças

Ainda com dúvida?

Conte o que aconteceu e, se puder, o endereço da tela. A equipe responde por suporte@orvya.net.