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.
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
- Abra a conta em Configurações › Integrações › Cobranças.
- No card 1. Conta Asaas, em Provedor, deixe Asaas.
- Em Ambiente, escolha Produção para cobranças reais ou Sandbox (testes) para experimentar. O campo começa em Sandbox (testes).
- Cole a Chave de API.
- 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.
- Revise o card 3. Padrões de cobrança (veja abaixo).
- 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.
- Copie a URL e o token. O token é exibido somente nesse momento.
- No painel do Asaas, em Integrações › Webhooks, crie um webhook com esses dados.
- 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
- Abra a conta em Configurações › Integrações › Cobranças.
- Em Provedor, escolha Efí Bank.
- Em Ambiente, escolha Produção para cobranças reais ou Homologação (testes) para experimentar.
- Cole o Client_Id e o Client_Secret.
- Clique em Testar conexão. Com sucesso, aparece Conectado — credenciais válidas.
- 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.
- 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.
- 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.
- 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.