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 — e a curadoria é da plataforma, porque o par é de todos.

Desativar é recusado enquanto houver documento em aberto

CURRENCY_IN_USE_CONFLICT 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. A regra geral, desde 09/09/2026: a moeda funcional de qualquer empresa do tenant não é desativável, e BRL é o caso comum dela, não a exceção — antes a redação era "porque é a moeda funcional obrigatória de toda empresa", e a obrigatoriedade acabou. BRL continua nascendo ativa porque é o destino de conversão do tenant típico brasileiro, e desativá-la enquanto houver empresa que feche nela deixaria o tenant sem destino.

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-rates 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.

O fluxo de aprovação ganhou uma lista de dias não úteis em 08/09/2026, e ela continua não servindo aqui. Aquela lista é o calendário do escritório do tenant — feriado municipal, recesso, ponte —, e quem decide se houve boletim é o Banco Central, que publica normalmente no aniversário da cidade. Guiar a busca de taxa por ela faria a conversão pular um dia em que existia cotação, e faria a taxa de uma compra depender do RH. São dois calendários com dois donos, e nenhuma rotina desta página lê o do tenant. Anotado em v1.4

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.

O fator de cotação vem do provedor, não do cadastro

Novo em 09/09/2026. quoteUnit é propriedade da fonte, não da moeda. O CotacaoMoedaDia publica reais por uma unidade — para todas as moedas, iene incluído; é a mesma constatação que faz a paridade ser descartada. Logo todo par com providerCode = BCB_PTAX tem quoteUnit = 1, e o 100 do iene e o 1000 do guarani só existem para fonte que publique assim.

Para que isso não dependa de alguém lembrar, a rotina compara o quoteUnit que o RateQuote traz com o do par: divergindo, a gravação é recusada com EXCHANGE_RATE_QUOTE_UNIT_MISMATCH_UNPROCESSABLE e o par entra no relatório da passada como quebrado. Não se ajusta a taxa para caber no fator cadastrado — dividir por um fator que a fonte não usou é justamente o defeito.

Por que a recusa e não o silêncio: com quoteUnit = 100 num par alimentado pelo PTAX, o iene entra a 0,0357 e sai valendo 0,000357 — cem vezes menos, num número que ninguém acha implausível. E como a taxa é congelada no movimento (RN-CUR-11), o erro fica gravado e não se corrige por substituição de cotação: teria de virar movimento de ajuste, um por documento. É o tipo de defeito que só se conserta antes de acontecer. Caso de teste obrigatório do adaptador, ao lado do MM-DD-YYYY: uma moeda de quoteUnit histórico 100 capturada do PTAX tem de gravar 1, e um par cadastrado com 100 tem de recusar.

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 é resolvido uma vez no rateio da moeda original: maior fatia, desempate por menor order, conforme RN-CC-23. Cada fatia converte e arredonda separadamente; o total funcional é a soma das fatias convertidas, sem segundo ajuste para coincidir com a conversão isolada do total.

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 que a restrição escondia era outro problema

Quatro páginas discordavam: Empresa aceitava qualquer ISO 4217, esta aqui recusava tudo que não fosse BRL, o Centro de Custo declarava BRL como única e o Fluxo escrevia a regra como se a multimoeda já valesse. Discordância dessa ordem não se resolve escolhendo o lado mais restritivo — ela existia porque o problema real nunca tinha sido escrito: com uma empresa em BRL e outra em USD, o limite do nó corporativo era comparado com um valor em outra moeda sem conversão declarada. Comparação silenciosa entre moedas, no ponto exato em que a alçada decide quem aprova. Fechar a moeda funcional adiava o defeito; escrever a conversão o elimina.

O limite de alçada tem moeda própria

CostCenterAssignment.approvalLimit ganha approvalLimitCurrency, obrigatória sempre que o limite estiver preenchido — inclusive no nó corporativo, que não tem empresa e por isso não tinha de onde herdar moeda. Deixou de ser gancho: sem a coluna, o número no nó corporativo é um valor sem unidade. A coluna é escrita pelo Centro de Custo; o que esta página define é o que a comparação faz com ela.

A comparação converte para a moeda do limite, e guarda a prova

O motor converte o valor da fatia para a moeda do limite — nunca o contrário, nunca "as duas para uma terceira" — usando a taxa congelada na submissão do documento, e grava no ApprovalEvent o valor comparado com a taxa e a data usadas. Quem lê a trilha seis meses depois refaz a conta; é a mesma exigência que o BudgetEntry já cumpre.

Sem par vigente, a submissão é recusada — nunca comparada em silêncio

Submeter documento cuja moeda não tenha par de conversão vigente contra a moeda do limite é recusa declarada, com APPROVAL_LIMIT_CURRENCY_NOT_CONVERTIBLE_UNPROCESSABLE 422, e a mensagem nomeia o par que falta. É a mesma decisão da RN-CUR-06 (não se inverte taxa) e da janela de maxRateAgeDays: onde não há número defensável, o produto recusa em vez de produzir um plausível.

O que continua fora é a conversão cruzada

O modelo já suporta qualquer par: CurrencyPair não sabe o que é real. O que não existe é fonte para o par que não passa pelo real. O boletim do Banco Central publica moeda contra real, e mais nada. Uma subsidiária que orce em dólar e compre em euro precisa 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

Enquanto não houver, a empresa em moeda estrangeira funciona com os pares que existem — cada par que ela precisar entra por cadastro, com fonte própria quando não vier do PTAX, e a submissão sem par é recusada em vez de adivinhada. Quando a triangulação for pedida: 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.