Directorios multi-moneda

(Sección: Operaciones y Gestión)

1) Tarea y ámbito de aplicación

• un escaparate de precios correcto (UX, confianza),
• reproducibilidad de los cálculos (auditoría, devoluciones),
• previsibilidad económica (margen/impuestos),
• cumplimiento (impuestos, sanciones, restricciones monetarias).

2) Modelo de datos (referencia)

• Product/SKU: `{sku_id, title, attributes, region_policies[]}`
• PriceList: `{pricelist_id, base_currency, effective_from, effective_to, version}`
• PriceItem: `{sku_id, base_price, base_currency, tax_class, pricing_model, promo_refs[]}`
• FXRate: `{pair: EUR→USD, rate, source, method, precision, effective_from, version}`

• `minor_units` (ISO 4217; por ejemplo, JPY = 0, USD/EUR = 2, KWD = 3; para crypto - hasta 8)
• 'rounding _ mode': 'HALF _ UP' (venta al por menor), 'BANKERS' (finanzas), 'FLOOR '/' CEIL' (impuestos/reguladores)

3) Fuentes y políticas de FX (tipos de cambio)

Fuentes: proveedores de cursos (bancos comerciales/centrales), su propio TWAP/mediana.
Política de actualización: frecuencia (1-15 min para volátil, 1 vez/día para estable), publicación retardada.
Markaps: 'rate (1 + fx_markup_bps)' en el lado del cliente; reglas transparentes por canal/región.
Ventana de cotización garantizada (rate lock): 5-30 min con 'fx _ version' en el pedido.
Anti-salto: cambio de tope por teca, circuit-breakers, fallback a la última cotización válida.
Versioning: cada publicación de cursos tiene 'version', 'effective _ from'; almacene el historial de reembolsos/disputas.

4) Estrategias de precios

Base + FX: almacenar el precio base en un «kernel» (por ejemplo, EUR), convertir en un escaparate.
Hojas por currency: precios predeterminados para monedas clave (mejor UX, previsibilidad).
Mixed: las 10 mejores monedas son pre-cálculo, la «cola larga» es on-the-fly.
Charm-pricing: `X. 99/95/90 'por región, controlar la acumulación de errores de redondeo.
Tarifas/cargos: pago fee, cross-border fee, network fee (crypto) - en el directorio o en el paso «Checkout Pricing».

5) Impuestos e «inclusión»

VAT/GST incluido/excluido: UE - más frecuentemente VAT-incluido; B2B puede ser sin IVA.
Capas de impuestos: federal/estatal/local; para juegos en línea - tarifas específicas.
Tipos umbrales: el impuesto cambia de volumen de negocios/categoría/región (threshold).
Redondeo de impuestos: per-item vs per-basket; los modos de redondeo y el orden de cálculo deben determinarse.
Ur. reporting: almacena 'tax _ rule _ version' en el cheque/recibo.

6) Redondeo y precisión

Redondee en el último paso de la presentación; en los cálculos almacenar «alta precisión» (hasta 8-9 signos).
Para crypto, utilice las bibliotecas decimal (sin flotante binario).
Carrito anti-deriva: «bankers rounding» para sumas, pero redondeo UX para mostrar; fije 'rounding _ scope'.
Regla de suma: la suma construida después de redondeos debe coincidir con total - utilice la distribución de los últimos céntimos/centavos (penny distribution).

7) Catálogos, promociones y bandejas

Promo-правила: `if region=A and currency in [EUR,USD] then discount=10% cap=50`.
Procedimiento de aplicación: (1) precio base → (2) descuento → (3) impuestos → (4) cargos → (5) redondeo.
Bundle-distribución: proporcional a la pestaña de posiciones antes del descuento; vropper para reembolsos.
Threshold-promo: envío gratuito/bono cuando se total≥X en la moneda del carrito; almacene el equivalente en la moneda base, pero confirme la versión FX.

8) Integración con pagos y cumplimiento

Disponibilidad de divisas: no todas las monedas están disponibles para cada jugador/región/proveedor de pagos.
FX garantizado: autorización prefijada por 'fx _ version' fija; durante la expiración - solicitud de confirmación del nuevo precio.
CUS/sanciones: listas de monedas/bancos/tokens, restricciones de conversión.
Devoluciones/chargeback: recuento por 'fx _ version' histórico del pedido; comisión de devolución - por catálogo en la fecha de la transacción.

9) Arquitectura y contrato de API

• `GET /catalog/prices? sku=…¤cy=…®ion=…&pricelist=…`
• Ответ: `{unit_price, currency, fx_version, pricelist_version, tax_breakdown[], fees[], display_price, rounding_mode}`

• `POST /pricing/quote { items[], region, currency, buyer_type }`
• Ответ: `{items_priced[], subtotal, discounts, taxes[], fees[], total, fx_version, lock_ttl, signature}`

• 'POST/pricing/commit {quote_id, signature}' → recibo con hash y firmas.

• `PriceListUpdated`, `FXRatePublished`, `TaxRuleChanged`, `PromoChanged` — с `version/effective_from`.

10) Almacenamiento en caché y rendimiento

Edge-cache: clave 'pricelist: region: currency: sku: version'; TTL para monedas estables arriba.
Warmup: calentar las categorías superiores para lanzar una campaña.
SWR (stale-while-revalidate): para escaparates; checkout - sólo fresh.
Inversión parcial: discapacidad por etiquetas 'sku', 'categoría', 'pricelist _ version'.
SLO: p95 ≤ 120 ms para escaparate, p95 ≤ 250 ms para quote, ≥99. 95% de disponibilidad.

11) Observabilidad y auditoría

Rastreo: 'trace _ id', 'pricelist _ version', 'fx _ version', 'tax _ rule _ version' en todos los eventos.
Inmutabilidad: revistas WORM de publicaciones de listas de precios/cursos; Cortes de Merkle, firmas de lanzamientos (DSSE).
Receipts: cheque/recibo con alineación completa y hash de carga útil; almacenar 7-10 años (por el regulador).
Dashboards: divergencia de vitrina↔checkout, frecuencia de redondeo «arriba/abajo», errores FX, tiempo de bloqueo del curso (TTL de bloqueo), ROI promocional.

12) Localización de visualización

Formato de moneda: símbolo/código (₴, €, $, AED), posición del símbolo, separadores, espacio.
Reglas locales: "₴ 1 234,56" vs "$1,234. 56”.
Psicología: los precios mágicos ('.99') no siempre son adecuados en fintech/juegos; probar por región.
Firmas legales: «El precio incluye el IVA», «La comisión de la red se cobra por separado».

13) Casos especiales

Monedas sin parte fraccionaria: JPY/ISK - minor_units=0.
Unidades menores de tres znak: KWD/BHD = 3.
Crypto: BTC/ETH/USDT - hasta 8 signos, red fee por separado; stablecoins ≠ «curso 1:1» con un border cruzado.
Doble precio: «moneda del catálogo» ≠ «moneda del cargo» (tasa bancaria del merchant). Documente el spread.
Deportes/juegos: límites a las ganancias máximas en la moneda del catálogo - almacenar equivalentes por 'fx _ version' ronda.

14) SLO/SLI y métricas de éxito

Corrección: proporción de pedidos donde total_checkout = total_quote (± 1 unidad menor bajo reglas de distribución) ≥ 99. 99%.
Estabilidad de FX: porcentaje de operaciones en la ventana de bloqueo de rate ≥ 99%.
Economía: margen/unidad vs plan; desviaciones debidas a FX/redondeos (bps).
UX: velocidad quote p95, proporción de los residuos en la conversión de precios, NPS escaparates.
Auditoría: 100% de los cheques con '_ version' y firma guardados.

15) Playbucks de incidentes

1. freeze cache disabilities, 2) forzar refresh lista de precios, 3) comparar 'pricelist _ version '/' fx _ version', 4) compensación por políticas.

1. habilita el aumento de los descuentos markup/cap, 2) acortar el bloqueo TTL, 3) cambiar a la fuente fallback.

1. comprobar 'tax _ rule _ version', 2) validación de rounding_scope, 3) reglas hotfix y reprais de cestas.

1. Reglas de protección (min_price), 2) desactivar las pilas, 3) recalculación y auditoría.

16) Seguridad y cumplimiento

Policy-as-code: controlar los cambios en las listas de precios/FX/impuestos a través de las firmas PR + de los lanzamientos.
Roles/Accesos: Principio de 4 ojos en las publicaciones de precios/FX.
Logs/recibos: eventos de publicación firmados y checkout.
Restricciones regionales: prohibición de monedas/tokens individuales; Políticas geográficas.

17) Experimentación y optimización

A/B: charm-pricing, precios predeterminados vs-the-fly, formato de visualización.
Marcación dinámica: dependencia de la volatilidad del par/hora del día.
Análisis de cohorte: devoluciones/chargeback por divisas, sensibilidad al redondeo.
Estrategias de caché: impacto de SWR/TTL en la conversión y la precisión.

18) Lista de verificación de implementación

• Definir la moneda base y la política de las hojas de cálculo por currency.
• Configurar la recopilación/publicación de FX con versionados, marcapuntos y TTL de bloqueo.
• Formalizar TaxRule y el orden de cálculo/redondeo (per-item o per-basket).
• Implementar la API del catálogo/quote/commit + recibos firmados.
• Habilitar el caché edge y la discapacidad granular; SWR para escaparates.
• Iniciar dashboards (vitrina↔checkout, errores de FX, impuestos, márgenes de bps).
• Introduzca roles/firmas en las publicaciones de precios/cursos, revistas WORM.
• Preparar los playbooks: no pago del precio, salto de FX, desajustes fiscales.
• Llevar a cabo «GameDay Catálogo»: desconexión de la fuente FX, burst promocional, cambio de impuestos.
• Realizar auditorías periódicas de minor_units/otobrazheniye por región.

19) FAQ

¿Es necesario almacenar los precios en cada moneda?
No necesariamente. Combine la prepago para las monedas superiores y la conversión para la «cola» - así se balancean UX y los costos.

¿Por qué el total después de redondear «no late»?
Debido a las diferencias per-item vs per-basket. Fije un enfoque y use «penny distribution».

¿Cómo puedo hacer una devolución en un mes?
Por los históricos 'pricelist _ version', 'fx _ version' y 'tax _ rule _ version' guardados en el recibo.

¿Qué pasa con crypto?
Utilice la precisión decimal, red fee por separado, no prometa 1:1 al fiat; fijar el curso y la ventana de acción.

Resumen: El catálogo multivalor es una combinación de matemáticas exactas, políticas estrictas y caché inteligente. Versione todo (precios/tasas/impuestos), fije la ventana de cotización, determine el orden de cálculos y redondeos, firme los artefactos de cheque y mantenga los dashboards visibles. Así obtendrá un escaparate honesto, cálculos reproducibles y una economía manejable en todas las monedas y regiones.