Aparência
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:
| API | Endpoints | Login | Credenciais |
|---|---|---|---|
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 conta | Na 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ção | Endpoint | Método PHP |
|---|---|---|
| Gestão de chaves | POST /pix/dict/gestao-chave/incluir | includePixKey() |
| Gestão de chaves | GET /pix/dict/gestao-chave/listar | listPixKeys() |
| Gestão de chaves | DELETE /pix/dict/gestao-chave/excluir | deletePixKey() |
| Gestão de chaves | GET /pix/dict/gestao-chave/:chave/oculto | getPixKey() |
| Gestão de reivindicação | POST .../reivindicacao/incluir | includeKeyClaim() |
| Gestão de reivindicação | PUT .../reivindicacao/:id/concluir | completeKeyClaim() |
| Gestão de reivindicação | GET .../reivindicacao/listar | listPendingKeyClaims() |
| Gestão de reivindicação | GET .../reivindicacao/:id | getKeyClaim() |
| Gestão de reivindicação | PUT .../reivindicacao/:id/confirmar | confirmKeyClaim() |
| Gestão de reivindicação | DELETE .../reivindicacao/:id/cancelar | cancelKeyClaim() |
| QR Code | POST /pix/qrcode/decodificar/oculto | decodeQrCode() |
| QR Code | POST /pix/qrcode/estatico/gerar | generateStaticQrCode() |
| QR Code | POST .../dinamico/imediato/gerar | generateImmediateDynamicQrCode() (também usado por createDynamicPix(), da BankInterface) |
| QR Code | PUT .../dinamico/imediato/atualizar/:id | updateImmediateDynamicQrCode() |
| QR Code | POST .../dinamico/vencimento/gerar | generateDueDateDynamicQrCode() |
| QR Code | PUT .../dinamico/vencimento/atualizar/:id | updateDueDateDynamicQrCode() |
| QR Code | GET .../dinamico/imediato/listar | listDynamicQrCodes() |
| QR Code | GET .../dinamico/imediato/buscar | findDynamicQrCode() |
| QR Code | DELETE .../dinamico/imediato/inativar/:id | deactivateDynamicQrCode() |
| Transferências | GET /pix/spi/extrato | getPixStatement() |
| Transferências | POST /pix/spi/transferir | transferPix() |
| Transferências | GET /pix/spi/devolver/motivos | listPixReturnReasons() |
| Transferências | POST /pix/spi/devolver | returnPix() |
| Transferências | GET /pix/spi/consultar | consultPixTransfer() |
| Notificações | GET /pix/notificacoes | listPixNotifications() |
| Pix Recorrente | POST /pix/spi/recorrente/gerar | generateRecurringPix() |
| Pix Recorrente | GET /pix/spi/recorrente/simular | simulateRecurringPix() |
| Pix Recorrente | GET /pix/spi/recorrente/listar | listRecurringPix() |
| Pix Recorrente | GET /pix/spi/recorrente/consultar/{id} | consultRecurringPix() |
| Pix Recorrente | GET .../consultar/agendado/{id} | consultScheduledRecurringPix() |
| Pix Recorrente | DELETE /pix/spi/recorrente/cancelar/{id} | cancelRecurringPix() |
| Pix Agendado | POST /pix/spi/transferir (com data_agendamento) | schedulePix() (alias de transferPix(), mesmo endpoint) |
| Pix Agendado | GET /pix/spi/agendamento/listar | listScheduledPix() |
| Pix Agendado | GET .../agendamento/consultar/:numCtrlIF | consultScheduledPix() |
| Pix Agendado | DELETE .../agendamento/cancelar/:numCtrlIF | cancelScheduledPix() |
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ção | Endpoint | Método PHP |
|---|---|---|
| Boletos | POST /boleto | generateChargeBoleto() (também usado por makeBoleto(), da BankInterface) |
| Boletos | GET /boleto/:id | getChargeBoleto() (também usado por fetchBoleto(), da BankInterface) |
| Boletos | POST /boleto/deposito | generateDepositBoleto() |
| Boletos | GET /boleto/deposito/:id | getDepositBoleto() |
| Boletos | GET /boleto?di=&df= | listBoletos() |
| Boletos | GET /boleto/liquidados/:di/:df | listSettledBoletos() |
| Boletos | GET /favorecidos/boletos | listBoletoPayers() |
| Boletos | GET /favorecidos/boletos/:documento | getBoletoPayer() |
| Boletos | DELETE /favorecidos/boletos/:id | deleteBoletoPayer() |
| Boletos | POST /boleto/carne | generateBookletCharge() |
| Boletos | GET /boleto/carne | listBookletCharges() |
| Boletos | GET /boleto/carne/:id | getBookletCharges() |
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ção | Endpoint | Método PHP |
|---|---|---|
| Transferencias | GET /transferencia/bancos | listTransferBanks() |
| Transferencias | GET /transferencia/finalidades/:filtro | listTransferPurposes() |
| Transferencias | POST /conta/movimentar/:idConta | moveAccount() |
| Transferencias | POST /transferencia | transfer() |
| Transferencias | GET /transferencia/pendente | listPendingTransfers() |
| Transferencias | PUT /transferencia/pendente/:id | executePendingTransfer() |
| Transferencias | DELETE /transferencia/pendente/:id | cancelPendingTransfer() |
| Transferencias | PUT /transferencia/pendentes-lote | executePendingTransfersBatch() |
| Transferencias | DELETE /transferencia/pendentes-lote | cancelPendingTransfersBatch() |
| Transferencias | GET /transferencia/agendada | listScheduledTransfers() |
| Transferencias | GET /transferencia/agendada/:numCtrlIF | getScheduledTransfer() |
| Transferencias | DELETE /transferencia/agendada/:numCtrlIF | cancelScheduledTransfer() |
| Transferencias | GET /favorecidos/transferencia | listTransferPayees() |
| Transferencias | GET /favorecidos/transferencia/:cpf_cnpj | getTransferPayee() |
| Transferencias | DELETE /favorecidos/transferencia/:id | deleteTransferPayee() |
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):
| Arquivo | Caminho padrão |
|---|---|
| Certificado de cliente | storage/keys/fiducia-client-crt.crt |
| Chave privada (sem senha) | storage/keys/fiducia-client-key.key |
| Certificado da CA | storage/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_URLno.env(config('services.fiducia.contas.api_url')). Um registro embankspode sobrescrever comcredentials.contas_api_url. - Login de cada conta:
accounts.credentials(fiducia_password,fiducia_operator_code,fiducia_transactional_password), gravado peloFiduciaBankSeeder(variáveisFIDUCIA_CONTAS_*) ou porPUT /access/account. - mTLS:
FIDUCIA_CONTAS_MTLS(truena homologação,falsena produção). Caminhos opcionais embanks.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 temkey_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_passwordoufiducia_operator_codeemPUT /access/accountdescarta 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.