Resolve um BR Code Pix (copia-e-cola, payload EMV) pelo lado do
pagador. Proxy + normalização sobre o POST /spi/code/v1/decode da
Autra — quem cuida do mTLS ICP-Brasil + download/validação do
JWS na location embarcada é a Autra; aqui só repassa e normaliza a
resposta.

Quando usar

Sempre que o app receber um QR Code Pix pra pagar e precisar do
txid antes de iniciar a transferência. Caso típico: pagar
fatura de empresa com QR Code (CLARO, Vivo, banks). Essas
chaves EVP são cadastradas como "Pix Cobrança dinâmica" e
retornam AG03 ("Transaction type not supported/authorized on
this account") se o pagamento for enviado como initiationType=KEY
ou QR_CODE_STATIC. Só passam com QR_CODE_DYNAMIC + qrTxId
— e o qrTxId só vive dentro do JWS resolvido por este endpoint.

Fluxo completo

1. App escaneia QR Code (ou recebe copia-e-cola)
2. App → POST /pix/qr/decode { brcode } → recebe qrTxId + dados
3. App mostra tela de confirmação ao usuário
4. App → POST /pix-payments {
     initiationType: "QR_CODE_DYNAMIC",
     qrTxId: <qrTxId retornado>,
     amount, creditParty, device, ...
   }

Tipos suportados e mapping pro initiationType

A Autra decodifica os 7 cenários documentados; o response normaliza
em qrType + já entrega o recommendedInitiationType pronto pra
ser repassado direto pro POST /pix-payments (sem o app ter que
mapear). Tabela de equivalência:

Por que não usar qrType direto? Porque a Autra só aceita 4 valores
no initiationType (KEY, MANUAL, QR_CODE_STATIC,
QR_CODE_DYNAMIC) e o qrType tem 7 categorias semânticas. O
backend faz a redução pelo app.

⚠️ Atenção a CLARO/Vivo/concessionárias: o QR de fatura desses
emissores é tecnicamente STATIC (não dinâmico, apesar da UX de
"cobrança única"). Eles pre-geram um QR Static com final_amount

• tx_id embutidos. Se o app enviar como QR_CODE_DYNAMIC, o
  /spi/v1/payments da Autra rejeita com 400 INVALID_FORMAT no
  tx_id (regex strict 26-35 chars em dynamic; o txid desses
  emissores tem 25 chars, válido só pra static).

Campos do response

Como a Autra retorna 7 shapes diferentes, o response é tolerante: só
os campos aplicáveis ao qrType vêm preenchidos. O payload Autra
completo fica em raw pra fallback.

• qrTxId — usar no POST /pix-payments com QR_CODE_DYNAMIC.
  Pode vir vazio em QR estático puro (use KEY ou QR_CODE_STATIC).
• amount.original vs amount.final — pra DUE_DATE_DYNAMIC,
  final inclui juros/multa menos desconto/abatimento calculados
  pra paymentDate.
• beneficiary — quem vai receber. Sempre exibir na confirmação.
• payer — restrição de pagador (Pix Cobrança fechada). Quando
  presente, o POST /pix-payments precisa partir dessa pessoa.
• purpose — só em saque/troco.

Notas operacionais

• Sem PIN (decode é leitura, não move dinheiro).
• paymentDate é opcional (formato YYYY-MM-DD) — usado pra
  cálculo de juros/desconto em cobranças com vencimento. Se
  omitido, a Autra usa o dia atual.
• Não persistimos local — chamada é stateless, idempotente.