Moeda e Câmbio

O desenho ingênuo é buscar a cotação na hora de converter

A implementação óbvia é uma função ConvertAsync que chama o serviço do Banco Central no momento em que precisa do número. Ela funciona na demonstração e falha em produção por quatro motivos ao mesmo tempo: a aprovação de uma requisição passa a depender de um host externo estar de pé; o mesmo documento reprocessado converte com número diferente; ninguém consegue responder "que taxa você usou naquele dia" seis meses depois; e a latência de uma chamada externa entra no caminho de uma tela de digitação que precisa responder em milissegundos.

SAP, Oracle e Dynamics chegaram os três ao mesmo desenho: a taxa é uma linha de tabela com data e tipo, alimentada por rotina, e o documento guarda a taxa que usou. A chamada externa fica na rotina, longe do caminho crítico — e quando ela falha, o efeito é um alerta, não uma aprovação travada.

Converter é um ato datado, e o resultado carrega a prova

Nenhum consumidor recebe só o valor convertido. O serviço devolve um ConversionResult com o valor, a taxa, o rateType, a rateDate realmente usada, a idade em dias e o id da linha de cotação. O consumidor congela o conjunto inteiro, e é isso que permite o extrato dizer "US$ 10.000 × 5,2013 (PTAX venda de 29/12, 2 dias) = R$ 52.013,00" em vez de mostrar um número que ninguém sabe defender.

Reavaliação retroativa não existe

Se a taxa de ontem mudasse o consumo de hoje, o saldo orçamentário mudaria sozinho durante a madrugada e ninguém conseguiria explicar ao gestor por que a verba encolheu sem ninguém ter comprado nada. A variação cambial entre estágios não é corrigida: ela aparece, como consumo real, no momento da liquidação — e é atribuível por relatório.

Ativar tem três efeitos, e é isso que faz a captura automática funcionar

Ativar EUR num tenant, na mesma transação: garante TenantCurrency; garante o CurrencyPair EUR→BRL global, com autoFetch ligado e provedor BCB_PTAX; e enfileira um backfill dos últimos 30 dias. O cadastro de pares não é uma tela que alguém precisa lembrar de preencher — ele é consequência de um ato que a pessoa já ia praticar de qualquer jeito. A tela de pares existe para curadoria e diagnóstico, não para o caminho comum.

Desativar é recusado enquanto houver documento em aberto

CURRENCY_IN_USE 409, com a contagem por tipo de documento na mensagem — "3 pedidos e 1 requisição em aberto em EUR". Documento fechado e histórico não impedem: eles continuam existindo, continuam legíveis e continuam com a taxa congelada. Impedir a desativação por causa de um pedido de 2024 seria transformar uma decisão de curadoria em impossibilidade permanente.

BRL é ativa por construção

Nasce ativa em todo tenant e a desativação é recusada na v1, porque é a moeda funcional obrigatória de toda empresa. Quando a moeda funcional deixar de ser só BRL, a regra vira "a moeda funcional de qualquer empresa do tenant não é desativável" — que é a mesma coisa, escrita de forma mais geral.

Não se edita cotação, substitui-se

UPDATE e DELETE recusados por grant e por trigger, mesma disciplina do razão orçamentário. Corrigir uma taxa é gravar a nova e apontar supersededById na antiga, na mesma transação. O motivo aparece na tela de cotações com a taxa que foi substituída ao lado.

E o que já foi convertido não muda. O BudgetEntry de ontem guarda exchangeRate, rateType e rateDate como valores, não como chave estrangeira para esta tabela. Substituir a cotação corrige o futuro; o passado é um fato registrado. Se a diferença for material, o caminho é um movimento de Adjustment com reasonCode próprio — visível, aprovado e rastreável — nunca uma reescrita silenciosa.

Taxa contratada é do documento, não da tabela

Compra com câmbio travado usa a taxa do contrato. O documento carrega exchangeRateOverride com rateType = Contracted, exige a permissão override:exchange_rate e registra quem informou e com que referência. É a única forma de a taxa não vir da resolução, e ela fica visível no extrato da verba, marcada. Opcionalmente a mesma taxa é persistida como ExchangeRate do tenant, para que outros documentos do mesmo contrato a encontrem sozinhos.

Dias corridos, não dias úteis — e o motivo é prático

Recuar por dia útil exigiria um calendário de feriado bancário mantido por alguém. Ninguém mantém, e feriado municipal não existe para o Banco Central. Cinco dias corridos cobrem o fim de semana comum, a segunda e a terça de carnaval e o Natal emendado ao fim de semana, que são os três casos reais. O preço é que uma rotina quebrada na sexta só é percebida na quarta — e é justamente por isso que a falha notifica na primeira ocorrência, em vez de esperar a janela estourar.

A idade da taxa é dado, não detalhe de implementação

O ConversionResult devolve rateDate e rateAgeDays, e ambos são gravados pelo consumidor. Acima de warnRateAgeDays a interface mostra "PTAX venda de 29/12 · 2 dias" ao lado do valor convertido. Esconder a idade é como esconder a taxa: o número fica indefensável na conversa com a controladoria.

Contraste deliberado com a resolução da verba orçamentária

Na BudgetLine, várias linhas podem cobrir a mesma fatia e vence a mais específica — dimensões aninhadas, empate impossível por construção de depth. Aqui a chave é exata e a cascata é por origem e por data. São problemas diferentes e é bom que as regras não se pareçam: quem lê as duas specs não deve tentar aplicar a intuição de uma na outra.

Resposta vazia é ausência, não falha

Sábado, domingo e feriado bancário devolvem 200 com value: []. Isso não incrementa consecutiveFailures e não notifica ninguém: é a resposta correta para uma pergunta sobre um dia sem boletim. Falha é timeout, erro de rede, 5xx e resposta que não desserializa — essas contam, e são elas que alertam.

Um par por requisição, sequencial, com backoff

O serviço é público e não documenta limite de uso. Com dez a quinze pares, o custo total da passada é de segundos, e paralelizar contra um serviço gratuito de terceiro para economizar dois segundos é a forma mais rápida de ser bloqueado. Falha de par não interrompe a passada: os outros seguem e o relatório da execução lista o que deu certo e o que não deu.

Idempotente por construção

A gravação colide no índice único (tenantId, par, tipo, data) e é descartada sem efeito. Por isso as três execuções diárias são seguras, o botão "buscar agora" é seguro e reprocessar uma janela inteira é seguro. Uma taxa capturada só muda por substituição explícita, nunca por uma segunda passada da rotina.

Por que PtaxVenda de D−1 como padrão

O boletim de fechamento do próprio dia só sai no fim da tarde, e requisição aprovada às 10h não pode esperar. Venda porque é a taxa a que a empresa compra moeda estrangeira — que é o que uma ordem de compra representa. O boletim traz compra e venda na mesma resposta, então PtaxCompra é gravada junto de graça, para o relatório que precise da outra ponta.

Backfill na ativação, e nada de "primeiro dia sem histórico"

Ativar uma moeda enfileira FetchRangeAsync dos últimos 30 dias via CotacaoMoedaPeriodo — uma requisição só. Sem isso, o cliente ativa EUR na terça e a primeira nota com data de necessidade na semana anterior é recusada por falta de cotação, o que parece defeito e é só falta de histórico.

O que não usamos do boletim, e por quê

A resposta traz também paridadeCompra e paridadeVenda, que é a moeda contra o dólar, com a convenção invertida entre moedas tipo A (USD/moeda) e tipo B (moeda/USD) do recurso Moedas. A paridade é a matéria-prima da conversão cruzada — EUR→USD sem passar pelo real — e a v1 não faz conversão cruzada. Fica registrada como a fonte natural quando fizer, com a ressalva de que a decisão difícil não é obter a paridade, e sim qual ponta usar em cada perna da triangulação.

Um único arredondamento, nas casas da moeda de destino

amount × rate ÷ quoteUnit em precisão cheia, e um arredondamento no fim, para Currency.minorUnits do destino, HALF_UP. Arredondar no meio da conta — depois da multiplicação e antes da divisão pelo fator — é o defeito clássico de centavo, e ele só aparece nas moedas com quoteUnit diferente de 1, ou seja, tarde e em produção.

Converte-se a fatia, nunca o total

Quando a linha do documento é rateada entre centros de custo, o rateio acontece na moeda do documento e cada fatia converte separadamente. Converter o total e depois ratear dá uma soma diferente por um ou dois centavos, e a diferença aparece exatamente onde dói: a soma das linhas do extrato não bate com o total do documento.

O resíduo de arredondamento da conversão segue a mesma regra de resíduo do rateio já definida na spec de Centro de Custo — sobra para a fatia de maior percentual, com desempate por menor costCenterId. Mesma regra em dois lugares é uma regra; duas regras parecidas é uma armadilha.

Moeda igual é passagem direta, não conversão com taxa 1

from == to devolve o valor intacto, rate = 1, exchangeRateId nulo e rateAgeDays = 0, sem tocar na tabela. O caminho comum — documento em real, empresa em real — nunca depende de existir cotação de BRL→BRL, e nenhuma falha de câmbio pode alcançar o cliente que só compra no Brasil.

O consumidor congela o resultado inteiro

Não basta guardar o valor convertido, e não basta guardar o id da cotação. O documento grava valor de origem, moeda de origem, taxa, quoteUnit, tipo e data — como valores. É o que permite reconstruir a conta seis meses depois mesmo que a cotação tenha sido substituída, e é o que torna o extrato defensável.

O motivo é a fonte, não a modelagem

O modelo já suporta qualquer par: CurrencyPair não sabe o que é real. O que não existe é fonte. O boletim do Banco Central publica moeda contra real, e mais nada. Uma subsidiária que orçasse em dólar e comprasse em euro precisaria de EUR→USD, que só sai de conversão cruzada — por dupla conversão via real, ou pela paridade do próprio boletim. As duas envolvem escolher qual ponta usar em cada perna, e as duas produzem números plausíveis quando a escolha está errada. Conversão cruzada errada é o defeito mais difícil de detectar que existe nesta área: ninguém desconfia de 5,43 quando o certo era 5,41.

O gancho, escrito

Quando houver demanda declarada: CurrencyPair ganha derivationMode (Direct | ViaAnchor | ViaParity) e anchorCurrency; a resolução ganha um passo 3.5 que compõe duas taxas e devolve isDerived com as duas pernas no ConversionResult; e a regra de qual ponta usar vira decisão documentada, não convenção de código. É o mesmo desenho de moeda de referência do SAP e de moeda âncora do Dynamics — a diferença é que eles precisam com dezenas de moedas funcionais, e nós ainda não temos a primeira.