Skip to content

Fidúcia — Auth, Pix, Boletos e TED da API de Contas ​

Autenticação e operações de Pix, Boletos e Transferências (TED) para a API de Contas da Fidúcia (core banking — login, saldo/extrato, transferências, boletos, pagamentos, Pix, cartões; catalogada em API de Contas - Integração.md, na raiz do workspace). Implementado em App\Models\Banks\Fiducia, seguindo o padrão de driver por banco (App\Interfaces\BankInterface, despachado por Account::getBank()/ Bank::getBank() a partir de banks.model_type).

Não confundir com App\Services\FiduciaService — essa é a API de Onboarding (api.onboardinghoml.fiduciascm.digital, POST /users/auth), usada só para abrir a conta (ver docs/abertura-de-conta.md §8.3). São duas APIs distintas da mesma instituição, cada uma com suas próprias credenciais e seu próprio token.

Autenticação por endpoint ​

A Fidúcia tem duas APIs, cada uma com o seu login:

APIEndpointsLoginCredenciais
Onboarding - Parceiro (https://api.onboardinghoml.fiduciascm.digital)Cadastro/abertura de conta (App\Services\FiduciaService: clientes, endereço, telefone, documentos, sócios, envio para análise)POST /users/auth com client_id, client_secret e scope (painel_api)Direto no .env: FIDUCIA_ONBOARDING_API_URL, FIDUCIA_ONBOARDING_CLIENT_ID, FIDUCIA_ONBOARDING_CLIENT_SECRET, FIDUCIA_ONBOARDING_SCOPE (config('services.fiducia.onboarding')). Token no cache da aplicação.
Contas - Integração (https://api.contas-homl.fiduciascm.digital:8609)Todas: Pix (chaves, reivindicação, QR Code, transferências e devolução, notificações, recorrente, agendado), boletos e TED (App\Models\Banks\Fiducia)POST /login com cpfcnpj, conta, password e, para PJ, cod_operador — o login da própria contaNa tabela accounts: credentials.fiducia_password, credentials.fiducia_operator_code; CPF/CNPJ e conta vêm de accounts.document e accounts.account. Sessão em credentials.fiducia_session. A URL vem de FIDUCIA_CONTAS_API_URL.

Conta sem fiducia_password não consegue usar nenhuma rota da API de Contas (DomainException); não existe mais credencial sistêmica do banco (POST /auth/token).

As senhas transacionais exigidas por algumas operações de Pix (incluir/excluir chave, reivindicação) vão no corpo da chamada (transational_password) e vêm de accounts.credentials.fiducia_transactional_password — não fazem parte do login.

Escopo desta implementação ​

Autenticação (getAccessToken()) e todas as operações das pastas "Pix", "Boletos" e "Transferencias" da coleção — ver tabelas abaixo. Pagar um boleto de terceiro (pasta "Pagamentos" — código de barras/linha digitável) e as operações da BankInterface que dependem dela (payBoleto, consultBoleto, getPaymentReceipt, cancelScheduledPayment, listDdaBoletos, endWithdraw) continuam não implementadas — cada uma lança Fidúcia: método 'X' ainda não implementado. em vez de simular um comportamento não testado contra a API real.

Métodos de Pix (Banks\Fiducia) ​

Pasta da coleçãoEndpointMétodo PHP
Gestão de chavesPOST /pix/dict/gestao-chave/incluirincludePixKey()
Gestão de chavesGET /pix/dict/gestao-chave/listarlistPixKeys()
Gestão de chavesDELETE /pix/dict/gestao-chave/excluirdeletePixKey()
Gestão de chavesGET /pix/dict/gestao-chave/:chave/ocultogetPixKey()
Gestão de reivindicaçãoPOST .../reivindicacao/incluirincludeKeyClaim()
Gestão de reivindicaçãoPUT .../reivindicacao/:id/concluircompleteKeyClaim()
Gestão de reivindicaçãoGET .../reivindicacao/listarlistPendingKeyClaims()
Gestão de reivindicaçãoGET .../reivindicacao/:idgetKeyClaim()
Gestão de reivindicaçãoPUT .../reivindicacao/:id/confirmarconfirmKeyClaim()
Gestão de reivindicaçãoDELETE .../reivindicacao/:id/cancelarcancelKeyClaim()
QR CodePOST /pix/qrcode/decodificar/ocultodecodeQrCode()
QR CodePOST /pix/qrcode/estatico/gerargenerateStaticQrCode()
QR CodePOST .../dinamico/imediato/gerargenerateImmediateDynamicQrCode() (também usado por createDynamicPix(), da BankInterface)
QR CodePUT .../dinamico/imediato/atualizar/:idupdateImmediateDynamicQrCode()
QR CodePOST .../dinamico/vencimento/gerargenerateDueDateDynamicQrCode()
QR CodePUT .../dinamico/vencimento/atualizar/:idupdateDueDateDynamicQrCode()
QR CodeGET .../dinamico/imediato/listarlistDynamicQrCodes()
QR CodeGET .../dinamico/imediato/buscarfindDynamicQrCode()
QR CodeDELETE .../dinamico/imediato/inativar/:iddeactivateDynamicQrCode()
TransferênciasGET /pix/spi/extratogetPixStatement()
TransferênciasPOST /pix/spi/transferirtransferPix()
TransferênciasGET /pix/spi/devolver/motivoslistPixReturnReasons()
TransferênciasPOST /pix/spi/devolverreturnPix()
TransferênciasGET /pix/spi/consultarconsultPixTransfer()
NotificaçõesGET /pix/notificacoeslistPixNotifications()
Pix RecorrentePOST /pix/spi/recorrente/gerargenerateRecurringPix()
Pix RecorrenteGET /pix/spi/recorrente/simularsimulateRecurringPix()
Pix RecorrenteGET /pix/spi/recorrente/listarlistRecurringPix()
Pix RecorrenteGET /pix/spi/recorrente/consultar/{id}consultRecurringPix()
Pix RecorrenteGET .../consultar/agendado/{id}consultScheduledRecurringPix()
Pix RecorrenteDELETE /pix/spi/recorrente/cancelar/{id}cancelRecurringPix()
Pix AgendadoPOST /pix/spi/transferir (com data_agendamento)schedulePix() (alias de transferPix(), mesmo endpoint)
Pix AgendadoGET /pix/spi/agendamento/listarlistScheduledPix()
Pix AgendadoGET .../agendamento/consultar/:numCtrlIFconsultScheduledPix()
Pix AgendadoDELETE .../agendamento/cancelar/:numCtrlIFcancelScheduledPix()

Todos os métodos que exigem senha transacional (transational_password — grafia da própria API da Fidúcia, mantida como está) recebem esse valor como parâmetro explícito, nunca lido de banks.credentials — é uma autorização de operação, não uma credencial de integração armazenada.

createDynamicPix(float $value), exigido pela BankInterface, gera uma cobrança dinâmica imediata usando a chave Pix padrão em banks.credentials['contas_pix_key'] (nova chave, opcional — só necessária se este método específico for chamado); sem ela, lança uma exceção explicando o que falta. Para controlar os demais campos (identificador, dados do pagador, expiração etc.), chamar generateImmediateDynamicQrCode() diretamente com o payload completo.

Métodos de Boleto (Banks\Fiducia) ​

Pasta da coleçãoEndpointMétodo PHP
BoletosPOST /boletogenerateChargeBoleto() (também usado por makeBoleto(), da BankInterface)
BoletosGET /boleto/:idgetChargeBoleto() (também usado por fetchBoleto(), da BankInterface)
BoletosPOST /boleto/depositogenerateDepositBoleto()
BoletosGET /boleto/deposito/:idgetDepositBoleto()
BoletosGET /boleto?di=&df=listBoletos()
BoletosGET /boleto/liquidados/:di/:dflistSettledBoletos()
BoletosGET /favorecidos/boletoslistBoletoPayers()
BoletosGET /favorecidos/boletos/:documentogetBoletoPayer()
BoletosDELETE /favorecidos/boletos/:iddeleteBoletoPayer()
BoletosPOST /boleto/carnegenerateBookletCharge()
BoletosGET /boleto/carnelistBookletCharges()
BoletosGET /boleto/carne/:idgetBookletCharges()

makeBoleto(float $value, string $expirationDate, array $payerData = [], array $options = []), exigido pela BankInterface, monta o payload de generateChargeBoleto() a partir desses parâmetros — chamar generateChargeBoleto() diretamente para controle total dos campos (juros, multa, número do documento etc.). fetchBoleto(string $nossoNumero) delega para getChargeBoleto().

Métodos de Transferência / TED (Banks\Fiducia) ​

Pasta da coleçãoEndpointMétodo PHP
TransferenciasGET /transferencia/bancoslistTransferBanks()
TransferenciasGET /transferencia/finalidades/:filtrolistTransferPurposes()
TransferenciasPOST /conta/movimentar/:idContamoveAccount()
TransferenciasPOST /transferenciatransfer()
TransferenciasGET /transferencia/pendentelistPendingTransfers()
TransferenciasPUT /transferencia/pendente/:idexecutePendingTransfer()
TransferenciasDELETE /transferencia/pendente/:idcancelPendingTransfer()
TransferenciasPUT /transferencia/pendentes-loteexecutePendingTransfersBatch()
TransferenciasDELETE /transferencia/pendentes-lotecancelPendingTransfersBatch()
TransferenciasGET /transferencia/agendadalistScheduledTransfers()
TransferenciasGET /transferencia/agendada/:numCtrlIFgetScheduledTransfer()
TransferenciasDELETE /transferencia/agendada/:numCtrlIFcancelScheduledTransfer()
TransferenciasGET /favorecidos/transferencialistTransferPayees()
TransferenciasGET /favorecidos/transferencia/:cpf_cnpjgetTransferPayee()
TransferenciasDELETE /favorecidos/transferencia/:iddeleteTransferPayee()

listTransferPurposes() recebe um $filter que na coleção original aparece como um segmento fixo da URL (str0008, sem nome de variável) — o significado real não está documentado; o método aceita o valor como parâmetro (com esse mesmo exemplo como padrão) em vez de travar a chamada.

Nenhum método de "Boleto" ou "TED" acima implementa pagar um boleto de terceiro — isso é a pasta "Pagamentos" da coleção (/pagamentos/autorizar

  • /pagamentos/efetivar, a partir de código de barras/linha digitável), fora do escopo desta implementação.

mTLS (certificado de cliente) ​

Na homologação, a API de Contas exige TLS mútuo em toda chamada, inclusive POST /login.

Na produção não há certificado: a Fidúcia libera o acesso pelo IP do servidor (54.157.218.229). Para isso, use FIDUCIA_CONTAS_MTLS=false no .env (config('services.fiducia.contas.mtls'), padrão true). Assim nenhum certificado é enviado, e o servidor da Fidúcia é validado pelas CAs do sistema.

Padrão (sem nada configurado em banks.credentials):

ArquivoCaminho padrão
Certificado de clientestorage/keys/fiducia-client-crt.crt
Chave privada (sem senha)storage/keys/fiducia-client-key.key
Certificado da CAstorage/keys/fiducia-ca-crt.crt

Configurável por conta bancária via banks.credentials (valor em credentials primeiro, arquivo padrão depois):

json
{
  "contas_cert_path": "/caminho/opcional/para/outro.crt",
  "contas_key_path": "/caminho/opcional/para/outra.key",
  "contas_ca_path": "/caminho/opcional/para/outra-ca.crt"
}

Com mTLS ativo, arquivo ausente (nem o configurado, nem o padrão) → mtlsOptions() lança uma exceção nomeando exatamente qual arquivo falta.

⚠️ Chaves reais versionadas no repositório. Os três arquivos padrão foram commitados em storage/keys/ — padrão não ideal, já registrado como pendência de segurança no CHANGELOG.md de 18/09/2026. Se a Fidúcia rotacionar essas credenciais, atualizar os três arquivos (ou apontar banks.credentials para novos caminhos).

Configuração ​

  • URL da API de Contas: FIDUCIA_CONTAS_API_URL no .env (config('services.fiducia.contas.api_url')). Um registro em banks pode sobrescrever com credentials.contas_api_url.
  • Login de cada conta: accounts.credentials (fiducia_password, fiducia_operator_code, fiducia_transactional_password), gravado pelo FiduciaBankSeeder (variáveis FIDUCIA_CONTAS_*) ou por PUT /access/account.
  • mTLS: FIDUCIA_CONTAS_MTLS (true na homologação, false na produção). Caminhos opcionais em banks.credentials (contas_cert_path/contas_key_path/contas_ca_path), ver acima.
  • banks.credentials.contas_pix_key (opcional): chave Pix usada pelo copia e cola quando a conta ainda não tem key_pix.

Token: sessão de cada conta ​

Quando a conta tem o próprio login configurado (accounts.credentials.fiducia_password), cada conta faz o seu login em POST {contas_api_url}/login com cpfcnpj (accounts.document, só dígitos), conta (accounts.account), password e, para PJ, cod_operador (credentials.fiducia_operator_code). A resposta ({ "status": "sucesso", "token": "...", "expiresIn": 3600 }) vira a sessão da conta em accounts.credentials.fiducia_session (token + expires_at, criptografado como o resto de credentials).

  • A sessão é reaproveitada até faltar 1 minuto para expirar; depois disso o próximo uso refaz o login. Um lock impede dois logins simultâneos da mesma conta.
  • Se a Fidúcia recusar o token antes do previsto (401), a sessão é descartada e a chamada seguinte faz um novo login.
  • Mudar fiducia_password ou fiducia_operator_code em PUT /access/account descarta a sessão atual.
  • A senha transacional (credentials.fiducia_transactional_password) fica na mesma coluna e é usada nas operações que a exigem (chaves Pix).

Todas as rotas da API de Contas exigem esse login. Conta sem fiducia_password não consegue usar nenhuma delas.

Formato da resposta do login ​

POST /login responde { "status": "sucesso", "token": "...", "expiresIn": 3600 } (confirmado por chamada real). O token da sessão vem em token e a validade, em segundos, em expiresIn.

Erros ​

Falha HTTP ao autenticar → App\Exceptions\BankException (mesmo padrão de erro usado pelos outros drivers — extrai a descrição do corpo da resposta quando possível). Configuração ausente (credenciais/URL) → \Exception com mensagem explicando exatamente o campo que falta.