Operar un catálogo comercial versionado y ofertas por tenant

Objetivo y autoridad

El catálogo global define productos, planes, revisiones y precios una sola vez. Una oferta de tenant referencia esas entidades; no duplica el catálogo. Esta separación permite cambiar la oferta futura sin reescribir contratos anteriores. Las lecturas requieren billing.view. Las escrituras administrativas requieren billing.manage y el rol activo Platform Administrator; una membresía secundaria inactiva no basta.

Este capítulo describe el modelo implementado y sus contratos. Antes de usarlo en una instalación, verifique que el catálogo y su migración se publicaron. Un documento local o un formulario visible no prueba que una migración de datos haya terminado.

Identidades y campos relevantes

revision comercial y version de concurrencia no significan lo mismo. Tampoco equivalen a CATALOG_VERSION, que identifica evolución técnica de almacenamiento, ni a la release de Dova.

Los importes se representan en unidades monetarias menores enteras y porcentajes en puntos básicos. Como ejemplo didáctico, 12.300 unidades menores de PEN representan S/123,00; 1.000 puntos básicos representan 10 %. Verifique siempre la semántica del campo concreto y no copie importes de pantalla sin conversión correcta.

Publicar nuevas condiciones

1. Revise Catalog y confirme el producto y plan estables.
2. Cree o abra una versión draft autorizada. Compare términos con la revisión anterior y documente qué cambiará.
3. Edite únicamente draft. Revise límites, derechos y datos comerciales antes de publicar.
4. Publique usando la versión de concurrencia actual.
5. Cree un Price vinculado a la publicación correcta. Revise moneda y condiciones antes de ofrecerlo.

Una revisión publicada no se corrige sobrescribiendo términos históricos. Para cambios comerciales cree otra revisión. Un precio utilizado congela condiciones y vínculo; sustitúyalo por uno nuevo cuando necesite cambiarlos. Retirar disponibilidad no elimina el historial de uso.

Asignar una oferta

En Offers, seleccione el tenant autorizado y referencias correctas de versión/precio. Revise vigencia con zona horaria, moneda y descuento o importe negociado. El inicio de vigencia es inclusivo y el fin exclusivo. Ofertas activas solapadas para la misma combinación tenant/producto/moneda/intervalo pueden rechazarse.

Compruebe el catálogo efectivo del tenant después de guardar. No use el catálogo global como evidencia de que una oferta particular está vigente. La visibilidad y elegibilidad también dependen del contexto de acceso. Un usuario de facturación del tenant no puede negociarse a sí mismo un precio mediante parámetros enviados desde el navegador.

Contratos y cambios concurrentes

Al crear una orden o suscripción se conserva una instantánea contractual. Activar después no debe volver a leer términos actuales para sustituir lo acordado. Si cambia el catálogo entre creación y activación, compare la instantánea original, no sólo la pantalla vigente.

Los endpoints de administración utilizan version para concurrencia. Un 409 exige recargar y revisar qué cambió; no cambie el número manualmente para hacer pasar una edición obsoleta. Un 400 indica petición inválida y un 403 alcance no autorizado. No se proporciona una API de eliminación de historial comercial.

POC sintético

Use un producto de demostración y un tenant aislado. Publique revisión A y precio ficticio en PEN; asigne oferta con una ventana temporal inequívoca. Genere una orden simulada con esa revisión. Publique revisión B con términos diferentes y compruebe que la orden A conserva los originales. Pruebe además una oferta solapada y una edición con versión antigua: ambas deben rechazarse según el contrato.

La prueba no cobra dinero ni usa tarjetas reales. No invente tokens para un proveedor productivo. Separe validación del modelo, renderizado de UI y autorización de cualquier pago real.

Migración y recuperación

Instalaciones antiguas requieren migración explícita; no se ejecuta automáticamente al iniciar. La herramienta local de migración no autoriza mutar producción. Una orden legacy con snapshot incompleto necesita revisión comercial; no rellene historia con defaults actuales. Ante resultado incierto de proveedor conserve identidad e intención y use reconciliación autorizada, evitando repetir efectos financieros.