Moeda e Câmbio

Currency não tem tenantId e não é editável por API de cliente. Moeda nova entra por migração, com code, numericCode e minorUnits conferidos contra a ISO 4217.

referencePriceCurrency, ItemSupplier.currency, SupplierEstablishment.currency, moeda de documento e Budget.currency recusam código que não seja TenantCurrency com isEnabled. Validação no servidor, não no combo.

BRL nasce ativa em todo tenant e, sendo a moeda funcional de toda empresa na v1, não é desativável. A regra vale para qualquer moeda que seja functionalCurrency de alguma empresa: sem ela o tenant fica sem destino de conversão.

Recusada com CURRENCY_IN_USE_CONFLICT enquanto houver documento em aberto na moeda. Histórico e documentos fechados permanecem legíveis, com a taxa que congelaram.

TenantCurrency + CurrencyPair (moeda→BRL, autoFetch derivado da união das ativações — e ligado a partir desta —, provedor BCB_PTAX) + backfill de 30 dias enfileirado. O cadastro de pares não depende de ninguém lembrar de preenchê-lo.

A conversão exige par cadastrado no sentido pedido. 1 ÷ rate não é a cotação inversa, e derivá-la produz divergência que ninguém rastreia.

O tipo é fixado no passo 1 e vale até a recusa. Não existe plano B por tipo — só por data, dentro da janela.

Tipos PtaxVenda e PtaxCompra só existem com tenantId nulo; Manual, Contracted e Commercial, só com tenantId preenchido. Em cada passo existe uma linha candidata, garantida pela unicidade de (tenantId, par, tipo, data) só entre as linhas não substituídas, com tenantId nulo contando como valor — requisito, não recurso de banco: um índice único filtrado é o exemplo de implementação, e conferir sob trava do par na gravação, o equivalente. A cascata é determinística e não tem desempate.

A taxa vale enquanto rateAgeDays ≤ maxRateAgeDays, com maxRateAgeDays configurável entre 4 e 15 — 4 é o maior intervalo sem fechamento nos feriados bancários nacionais, o da quarta-feira de cinzas (422 CURRENCY_SETTINGS_MAX_RATE_AGE_DAYS_UNPROCESSABLE fora da faixa). A rateDate efetivamente usada e a rateAgeDays voltam no resultado, são gravadas pelo consumidor e aparecem no extrato. Nunca se anda para a frente: cotação de amanhã não existe.

A cotação não é alterada nem excluída — requisito, com a recusa no banco só como exemplo de implementação. supersedeReasonCodeId obrigatório — motivo codificado, uso ExchangeRateSupersede. A resolução só enxerga linha com supersededById nulo.

O documento guarda taxa, tipo, data e quoteUnit como valores, não como referência. Refletir a taxa corrigida num documento é estorno e relançamento no próprio estágio, com entryReason = RateCorrection e o motivo da substituição — nunca Adjustment, que muda verba.

amount × rate ÷ quoteUnit em precisão cheia, arredondado uma vez para Currency.minorUnits, HALF_UP. Nunca se assume duas casas.

O rateio ocorre na moeda do documento e cada fatia converte separadamente. O resíduo do rateio é apurado ali, na moeda do documento, pela RN-CC-23 — maior fatia, empate pelo menor order —, que é a regra única do produto e não se reescreve aqui. Depois da conversão não há um segundo resíduo: o valor do documento na moeda funcional é, por definição, a soma das fatias convertidas, nunca o total convertido. Converter o total daria outro número, e o número que vale é o que o razão orçamentário guarda — e o razão guarda fatias.

from == to é passagem direta com rate = 1. Falha de câmbio nunca alcança o cliente que só compra no Brasil.

Colisão na unicidade da cotação descarta sem efeito. value: [] registra "sem boletim" e não incrementa consecutiveFailures.

A partir de notifyOnFailureAfter falhas consecutivas de um par, notificação para alertRecipients. A tela de pares mostra desde quando está quebrado.

Three-way match compara pedido, recebimento e nota na moeda do documento. Variação cambial não é divergência de preço e não trava nota: entra no realizado como ExchangeVariance, lançada pela nota.

POST /convert:currency é pré-visualização. Quem grava resolve a taxa de novo dentro da transação.

Toda gravação de ExchangeRate, substituição, ativação e desativação de moeda e alteração de CurrencySettings gera registro com autor, antes e depois.

autoFetch é a união das ativações dos tenants — liga com a primeira, desliga com a última, nunca aceita escrita. quoteUnit, provedor, tipos capturados e isActive só mudam com update:currency-pairs, que nenhum papel de tenant recebe, porque a mudança alcança todos os tenants de uma vez.

O RateQuote devolve quoteUnit; a rotina compara com o do par e recusa a gravação quando diferem, sem ajustar a taxa. Par alimentado pelo BCB_PTAX tem quoteUnit = 1 em toda moeda, porque é assim que o boletim publica. Teste obrigatório do adaptador.

O documento converte na submissão e, depois dela, só no ato que abre rodada nova de aprovação: o reenvio de documento devolvido e a alteração de documento aprovado que reabre com rodada do zero (Fluxo de Aprovação, RN-AP-71). Nesses dois atos o documento inteiro é reconvertido pela cascata da RN-CUR-27, com a conversionDate contada do dia do ato (RN-CUR-25) e as mesmas recusas da submissão, e o ConversionResult novo passa a ser a taxa do documento: rodada nova é decisão nova, e quem decide vê o valor de hoje — a alçada pode mudar de dono, e a verba pode não comportar. O ajuste do documento aprovado não converte: o valor novo é convertido pela taxa já gravada no documento — exchangeRate, quoteUnit, rateType, rateDate e conversionDate. Fora desses atos nada reconverte: aprovar, empenhar, receber e o passar do tempo não mexem na taxa, e não há reavaliação de saldo em aberto.

A ordem é fixa. Na alteração de documento aprovado, ajuste ou reabertura se decide pela taxa gravada, e só a reabertura, já decidida, reconverte — o câmbio do dia nunca transforma reabertura em ajuste. No reenvio, a condição de herança “valor que não subiu” vale nas duas moedas, a do documento e a funcional convertida pela taxa nova (Fluxo, RN-AP-21): US$ 100 mil que viram US$ 104 mil não herdam a aprovação porque o dólar caiu de 5,40 para 5,15 (R$ 535.600 contra R$ 540.000), e US$ 100 mil que ficam iguais não herdam se o dólar subiu. Sem cotação na reconversão, o ato é recusado com EXCHANGE_RATE_MISSING_UNPROCESSABLE, como na submissão: o reenvio não acontece e o documento continua Returned, ou a alteração não acontece e o documento continua na versão aprovada. Trocar a taxa por ato explícito — incluir, alterar ou remover o exchangeRateOverride, ou trocar a moeda do documento — muda o retrato, nunca é ajuste e reabre com rodada do zero, e por isso reconverte (RN-CUR-27). Risco aceito: quem reenvia escolhe o dia, e com ele a taxa — a mesma escolha que a submissão já dá; a data e a idade da taxa ficam gravadas e aparecem no extrato (RN-CUR-09).

Todo movimento do razão originado por documento herda exchangeRate, quoteUnit, rateType e rateDate dele; a liquidação herda da entrada que liquida. A resolução própria de taxa do Orçamento vale só para movimento sem documento de origem — Manual e Import. O recebimento não converte: herda a taxa do pedido. A nota converte na sua submissão e lança só a variação, como ExchangeVariance. A reconversão da rodada nova entra no razão como estorno do aberto pela taxa antiga e relançamento pela nova, no mesmo estágio, com entryReason = Reconversion e sujeita ao bloqueio (Orçamento, RN-O59); a parte já liquidada fica na taxa com que foi liquidada.

approvalLimitCurrency é obrigatória com o limite preenchido, nó corporativo incluído. O valor da fatia é convertido para a moeda do limite com a taxa congelada na submissão, e o ApprovalEvent grava o valor comparado com a taxa, o fator e a data. Sem par vigente entre as duas moedas, a submissão é recusada com APPROVAL_LIMIT_CURRENCY_NOT_CONVERTIBLE_UNPROCESSABLE — nunca comparada em silêncio. É a regra única de comparação: converte-se para a moeda de quem limita.

Linha com tenantId nulo é gravada só pela rotina, como serviço de sistema, e substituída só com create:official-exchange-rates e update:official-exchange-rates, permissão fora do catálogo do tenant e não atribuível a papel de tenant — como update:currency-pairs; a rota do tenant sobre linha oficial é 403 EXCHANGE_RATE_OFFICIAL_FORBIDDEN, e rota de plataforma chamada por quem não é operador é 403 CURRENCY_PLATFORM_OPERATION_FORBIDDEN. Taxa de tenant só em Manual, Contracted ou Commercial; tipo PTAX com tenantId preenchido é 422 EXCHANGE_RATE_TYPE_RESERVED_UNPROCESSABLE. A busca manual é de plataforma. Nenhum tenant grava, substitui ou sombreia uma linha que outro lê.

Num documento, conversionDate = D−1 civil: o dia anterior à data do ato que converte — a submissão, ou o ato que abre rodada nova (RN-CUR-22) — em America/Sao_Paulo, qualquer que seja a hora, sem calendário de feriado. A taxa usada é a do último boletim de fechamento com data até a conversionDate, que a janela acha recuando dia a dia (RN-CUR-09); rateAgeDays = conversionDate − rateDate. Toda segunda-feira grava idade 2, e a quarta-feira de cinzas, 4. A rotina grava só o boletim de fechamento, reconhecido pelo tipoBoletim; abertura e intermediários são descartados antes da gravação, e resposta sem fechamento conta como dia sem boletim. Teste obrigatório do adaptador: resposta com intermediários e sem fechamento não grava nada.

Gravar taxa em Manual, Contracted ou Commercial — e substituí-la — muda o valor de documento convertido e, com ele, alçada e verba. Por isso é ato de controle: registro isolado por tenant, gravado na mesma transação da taxa, com autor, par, tipo, data, taxa e quoteUnit, sem alteração posterior; e evento exchange-rate.recorded publicado depois do commit (na substituição, exchange-rate.superseded). O registro é preparado por IAuditTrail.Stage (Gryd.IO 11.1.0) e fica legível depois da entrega pelo Worker.

O tipo vem da configuração. O tipo de taxa de um documento vem de CurrencySettings.processRateTypes, pela entrada do processo dele; defaultRateType vale só para movimento sem documento de origem. É este o contrato, com estes dois nomes, que o Fluxo de Aprovação (RN-AP-70) e o Orçamento citam. O rateType da conversão de um documento é, portanto, o de CurrencySettings.processRateTypes para o processo dele (passo 1); quem pede, prepara ou submete não escolhe, e a configuração só muda com duas pessoas (RN-CUR-28). O documento não carrega tipo próprio: rateType enviado fora do exchangeRateOverride e diferente do configurado é recusado com 422 EXCHANGE_RATE_TYPE_NOT_SELECTABLE_UNPROCESSABLE no ato que o recebe, e nada é gravado. Outro tipo, ou taxa informada, só por exchangeRateOverride, com update:exchange-rates e allowContractedOverride ligado: congela o tipo, a taxa quando informada, o quoteUnit do par quando há taxa informada, o autor e a referência, e devolve isOverride = true (passo 0). O quoteUnit depende do ramo do override, e os dois ramos têm fatores diferentes. Com taxa informada — rate no corpo — não existe linha ExchangeRate nenhuma, e o fator é o do CurrencyPair: quando o corpo traz quoteUnit, ele tem de ser igual ao do par vigente; divergente é 422 EXCHANGE_RATE_OVERRIDE_QUOTE_UNIT_MISMATCH_UNPROCESSABLE, no ato que recebe o documento, e nada é convertido. Omitido, vale o do par. E o fator conferido é congelado no override, no ato que o recebe: o quoteUnit gravado com o override é o do CurrencyPair naquele instante — informado ou herdado —, e é ele que a conversão usa na submissão — e em toda reconversão de rodada nova, com a mesma conferência abaixo (RN-CUR-22). Se o quoteUnit do par vigente na submissão diverge do congelado — o par foi editado pela rota de plataforma PUT /currency-pairs/{id} entre um ato e outro —, a submissão é recusada com o mesmo 422 EXCHANGE_RATE_OVERRIDE_QUOTE_UNIT_MISMATCH_UNPROCESSABLE, com os dois fatores na mensagem. A recusa é de submissão, e o documento fica onde estava: nada é convertido, nenhuma instância de aprovação é criada, nada é lançado no razão e o documento continua não submetido, editável, com o override registrado nele — refazê-lo contra o par novo, ou removê-lo e submeter pelo tipo do processo, é o caminho de volta, e quem o registrou é quem o refaz. Sem o congelamento, a conferência do ato que recebe o documento não prova nada sobre a conversão, que acontece depois. Sem taxa informada — override só de tipo — a taxa vem dos passos 2 a 4, e a linha achada traz quoteUnit próprio, copiado do par no instante da gravação e congelado nela (RN-CUR-11): é o fator da linha que a conversão da submissão usa, e não há segundo fator a conferir, porque a linha e o quoteUnit dela são resolvidos juntos, no mesmo passo. O fator do par não entra nessa conta, o congelado do override não o sobrescreve e a 422 de divergência não alcança este ramo — é o que a RN-CUR-11 exige: mudar o fator no par não reinterpreta as taxas já gravadas, e reinterpretá-las é exatamente o que o fator do par faria sobre uma taxa que ele não descreve. quoteUnit no corpo sem rate não tem taxa que descrever e é recusado com a mesma 422, no ato que recebe o documento. Sem essa guarda, { Contracted, rate 5,40, quoteUnit 100 } num par de quoteUnit 1 converte US$ 100 mil em R$ 5.400: alçada e verba cem vezes menores, e a controladoria lendo "5,40", uma taxa plausível. A taxa informada nunca é gravada como ExchangeRate do tenant — nem por opção: taxa de tenant só nasce por POST /exchange-rates, ato de controle (RN-CUR-26).

A flag. O módulo dono deriva exchangeRateOverridden do ConversionResult, na submissão, na reavaliação e no reenvio — no ajuste, o que já está gravado no documento; na rodada nova, o da reconversão (RN-CUR-22); quem pede nunca a declara —, em dois casos: (a) isOverride — o documento traz exchangeRateOverride, com rate ou só com o tipo, e mesmo quando o tipo informado é igual ao configurado: o que aciona a controladoria é o override existir, não o tipo ter mudado —; (b) a taxa usada é do tenant e o capturedBy dela é quem submete o documento ou está entre os excluídos do documento pela RN-AP-60 do Fluxo de Aprovação por outra razão que não RateOverrider — requisitante, LastEditor, Beneficiary e os demais que ela lista. Com a flag, o motor acrescenta o passo complementar da controladoria; a regra do passo e a semente nos processos com valor moram no Fluxo (RN-AP-70), e esta página declara a origem da flag.

O autor da taxa não decide. O capturedBy de toda taxa do tenant usada na conversão entra em excludedUsers com a razão RateOverrider, com ou sem flag e qualquer que seja o papel dele no documento. No override, capturedBy é o autor da linha efetivamente usada: quando o override só troca o tipo, a linha vem dos passos 2 a 4 e o autor dela é excluído como qualquer outro. E quem registra o override entra também, com taxa informada ou só com o tipo: o overriddenBy do ConversionResult é excluído com a mesma razão. Os dois juntos garantem que a flag nunca chegue ao motor sem ao menos um RateOverrider. A cotação oficial não tem autor no tenant: a capturada pela rotina não tem autor nenhum, e a substituída por POST /official-exchange-rates/{id}:supersede tem como autor o operador de plataforma, que não é usuário do tenant e não decide passo nenhum de documento dele. Por isso o capturedBy do ConversionResult é nulo quando a taxa usada é oficial, e taxa oficial, sozinha, não exclui ninguém. Contrato das duas pontas: a flag se chama exchangeRateOverridden e a razão, RateOverrider; o Fluxo cita com esses nomes.

Caso de ataque. A taxa decide a alçada. (1) Quem pede escolhia uma taxa Contracted ou Commercial antiga, gravada para outro fim, baixava o valor em reais e caía em alçada menor sem aviso: agora o tipo é o do processo, e outro tipo só entra como exceção, com a controladoria na cadeia. (2) Com o processo configurado em Manual, um aprovador com update:exchange-rates grava 4,90 com a PTAX a 5,40; o pedido de US$ 100 mil de um colega vira R$ 490 mil em vez de R$ 540 mil e cai na alçada dele — sem ser requisitante, editor nem quem submete, ele não acionava a flag e decidia. Agora ele está em excludedUsers como RateOverrider e não decide nenhum passo do documento. (3) O mesmo aprovador grava a Contracted baixa e, em vez de informar taxa, manda exchangeRateOverride só com o tipo: com capturedBy nulo no override, ele não era RateOverrider e decidia o próprio passo complementar — agora o autor da linha usada volta a ser o capturedBy. (4) E, com capturedBy e overriddenBy nulos, o documento com flag e nenhum RateOverrider era recusado com 422 pelo Fluxo e nunca era submetido: o override só de tipo virava um jeito de travar o documento. (5) Taxa informada. O par JPY→BRL passa de quoteUnit 1 para 100 pela rota de plataforma depois de o override { Contracted, rate 0,0357 } estar gravado no documento: sem o fator congelado, ou a submissão converte por um fator que ninguém conferiu — ¥10.000.000 × 0,0357 ÷ 100 = R$ 3.570,00, em vez de ¥10.000.000 × 0,0357 ÷ 1 = R$ 357.000,00, cem vezes menos —, ou a guarda passa a recusar um documento cujo override estava certo quando foi registrado. Com o congelamento, a conversão usa o fator conferido, e a divergência aparece nomeada, na submissão. (6) Override só de tipo. Mesmo par e mesma edição de 1 para 100, com uma linha Contracted de rate 0,0357 gravada quando o par ainda valia 1 e, por isso, com quoteUnit 1 congelado nela (RN-CUR-11). O override só de tipo é registrado depois da edição: o fator do par congelado com ele é 100, igual ao do par vigente na submissão, então nenhuma 422 dispara — e converter por ele daria os mesmos R$ 3.570,00 num documento que vale R$ 357.000,00 pelo fator da linha, com alçada e verba cem vezes menores e nada nomeado na tela. Por isso o fator do par congelado com o override vale só onde há taxa informada: neste ramo, quem descreve a taxa é a linha.

defaultRateType, processRateTypes e maxRateAgeDays mudam como a política do Fluxo de Aprovação (RN-AP-55 e RN-AP-69). PUT /currency-settings com corpo que muda um deles é 409 CURRENCY_SETTINGS_CRITICAL_FIELD_CONFLICT. maxRateAgeDays está na lista porque alargar a janela para trás é escolher taxa mais velha sem tocar em tipo nenhum — com 15 dias, o documento de hoje alcança o fechamento da semana passada, e a diferença cai direto na alçada. Os demais campos da configuração seguem no PUT de uma pessoa só. A mudança nasce como CurrencySettingsChange Pending por POST /currency-settings/changes, com o diff item a item — campo, processo, valor vigente e valor novo — e proposedByUserId; a proposta nunca é editada: mudar é descartar e propor de novo. Processo que não é processo com valor do Fluxo, entrada de processo com valor removida ou tipo fora do enum é 422 CURRENCY_SETTINGS_PROCESS_RATE_TYPE_UNPROCESSABLE. Efetiva por POST /currency-settings/changes/{id}:apply, que grava o valor novo na mesma transação, por pessoa com update:currency-settings diferente de quem propôs — senão 403 CURRENCY_SETTINGS_CHANGE_SELF_APPLY_FORBIDDEN. Proposta que não está Pending, ou cujo valor vigente não é mais o "antes" dela, é 409 CURRENCY_SETTINGS_CHANGE_STALE_CONFLICT. :discard encerra sem efeito. Documento já convertido não muda: a configuração nova só o alcança se ele reconverter numa rodada nova (RN-CUR-22).

A prova e o aviso. É ato de controle: a CurrencySettingsChange guarda o diff, quem propôs, quem efetivou ou descartou e quando, isolada pelo tenant e gravada na transação do ato, e não sofre escrita além da transição de status (Pending · Applied · Discarded). Depois do commit sai currency-settings-change.applied, e a controladoria recebe aviso obrigatório com o diff.

Caso de ataque. Com o tipo fora do alcance de quem pede, o atalho passaria a ser a configuração: um administrador sozinho trocaria o tipo do pedido de compra de PtaxVenda para Commercial, em que há uma taxa baixa gravada, submeteria os pedidos da semana e voltaria a configuração. Agora a troca exige uma segunda pessoa e chega à controladoria com o diff.