Carteiras EFI

A partir da versão 4.24 o FUJI guarda o histórico das credenciais EfiPay de cada gestor: cada aplicação EFI (Client ID/Secret) vira uma carteira. A troca de credenciais deixa de interromper boletos, carnês e assinaturas emitidos antes dela.

Para o gestor

O problema que foi resolvido

Na EFI, cada cobrança pertence à aplicação (Client ID/Secret) que a emitiu. Antes, o FUJI guardava só um par de credenciais. Quando o gestor trocava de aplicação, as cobranças emitidas pela anterior não podiam mais ser consultadas, baixadas nem canceladas, e a EFI respondia com o erro de "uso misto de aplicações".

Com as carteiras:

  • a carteira ativa emite todas as cobranças novas;

  • as carteiras do histórico continuam cuidando das cobranças que emitiram, inclusive da baixa automática quando o aluno paga;

  • nenhuma carteira é apagada ou desativada automaticamente.

Onde ver

Em Configurações → EfiPay, o painel Carteiras EFI lista todas as carteiras do gestor:

Informação Significado

Ativa / Histórico

Situação da carteira. Só uma carteira fica ativa por vez.

Client ID mascarado

Identifica a aplicação EFI sem expor a credencial completa.

Homologação

A carteira usa chaves de homologação (sandbox), sem efeito financeiro real.

desde

Data e hora em que a carteira foi registrada.

Observação

Texto livre para registrar o motivo da troca, por exemplo "nova conta após migração de banco".

Trocar as credenciais

Ao salvar um Client ID e um Client Secret novos no formulário da EfiPay, o FUJI pede confirmação:

Trocar as credenciais cria uma nova carteira EFI. A atual passa para o histórico e continua sendo usada apenas para as cobranças já emitidas por ela.

A confirmação só aparece quando as duas credenciais novas estão preenchidas. Sem elas, não existe troca a confirmar.

Reativar uma carteira do histórico

O botão Tornar ativa (disponível para quem pode alterar as configurações) recupera uma carteira antiga. As credenciais e o certificado dela voltam a valer, e a carteira atual vai para o histórico. O formulário é recarregado com os dados da carteira reativada, e alterações não salvas são descartadas.

As credenciais (Client Secret) e os certificados das carteiras nunca aparecem nas telas nem nas respostas da API, seja a carteira ativa ou do histórico.

Detalhes técnicos

Modelo

EfiCarteira (app usuarios) tem um registro por aplicação EFI de cada gestor, com exatamente uma carteira ativa. Titulo e Bordero ganharam o carimbo efi_carteira (FK com on_delete=PROTECT), gravado na criação do objeto. Salvar as configurações do gestor (GestaoConfigSerializer) sincroniza a carteira ativa, e a migração de dados cria as carteiras iniciais a partir das configurações já existentes.

Regras

  • Criação nunca faz fallback: boleto, carnê, assinatura, cobrança no cartão e Pix são sempre emitidos pela carteira ativa.

  • Leitura e gestão fazem fallback: consulta (get_charge/get_subscription), cancelamento e baixa manual de objetos sem carimbo tentam as carteiras do histórico, da mais recente para a mais antiga, quando a EFI devolve o erro 3500010.

  • Notificações determinísticas: objetos novos levam a carteira na notification_url (?carteira=<id>), inclusive o webhook do Pix Automático. A view de notificação resolve a carteira pela querystring, sem tentativa e erro.

  • check_notification tenta o histórico no 3500010 em vez de disparar um alerta falso, mas não esconde uma falha de credencial da própria carteira ativa.

Passivo: efi-backfill-carteiras

Comando de gestão que percorre títulos e borderôs sem carimbo, descobre uma única vez a carteira dona de cada objeto, grava o carimbo local e regrava a notification_url na EFI. Depois disso, o objeto não precisa mais de fallback em nenhum dos dois lados. A opção --forcar regrava também as URLs de objetos já carimbados, o que é útil depois de uma troca de API_ENDPOINT.

API

Endpoint Uso

Listagem de carteiras do gestor

Alimenta o painel Carteiras EFI: situação, Client ID mascarado, sandbox, data e observação.

Observação da carteira

Edita o texto livre da carteira.

Ativar carteira

Copia as credenciais e o certificado da carteira do histórico para as configurações do gestor, torna-a ativa e devolve as configurações atualizadas para o front recarregar o formulário.

As cobranças avulsas da loja seguem as mesmas regras. Ver Pagamento por Boleto (bolix EFI).