Migración de identidad de pasarelas: ids legacy a Vector, Harbor y Plaza

Índice de documentación · English

Esta versión separa la identidad propia de Payment Emulator de las APIs de terceros que emula. Las pasarelas del producto pasan a llamarse Vector, Harbor y Plaza. Stripe, PayPal y Mercado Pago permanecen únicamente como objetivos de compatibilidad y nombres de procedencia documental.

Es un cambio incompatible de identidad/URLs para instalaciones anteriores a los perfiles independientes. Los contratos wire se conservan deliberadamente.

#Mapeo

#Namespaces propios del emulador

Estos prefijos pertenecen al emulador. Las rutas del protocolo compatible dentro de ellos no cambian: continúan, por ejemplo, /v1/payment_intents, /v2/checkout/orders y /v1/orders. El acceso sin prefijo usado por SDKs compatibles sigue resolviendo la pasarela a partir de la credencial.

#URLs de checkout alojado

Los enlaces generados y persistidos de Vector y Harbor se migran automáticamente. La metadata libre aportada por el usuario no se busca ni se reescribe.

#Namespaces de escenarios y contratos

Los escenarios cambian por prefijo:

stripe/<scenario>       -> vector/<scenario>
paypal/<scenario>       -> harbor/<scenario>
mercadopago/<scenario>  -> plaza/<scenario>

Los contratos pasan a almacenarse bajo la identidad independiente:

contracts/stripe/       -> contracts/vector/
contracts/paypal/       -> contracts/harbor/
contracts/mercadopago/  -> contracts/plaza/

Los archivos pueden seguir nombrando el objetivo real en su atribución de fuente. Esa procedencia no debe reescribirse.

#Variable de entorno

Se renombró una configuración del contrato de compatibilidad:

MERCADOPAGO_CONTRACT_URL
    -> PLAZA_COMPATIBILITY_CONTRACT_URL

Actualiza ficheros de entorno, secretos de despliegue y variables CI antes de arrancar la nueva versión. No se mantienen aliases públicos permanentes para los IDs anteriores.

#Qué cambia la migración de base de datos

Migration20260930210000 migra:

• IDs de gateway;
• applications.provider y escenarios vinculados;
• provider/key/definition de escenarios;
• provider de pagos, recursos, trazas y eventos webhook;
• códigos/nombres de cuentas de clearing y fees propiedad de la pasarela;
• URLs de redirección generadas por Vector;
• enlaces HATEOAS generados por Harbor en recursos e idempotent replay.

No reescribe metadata arbitraria ni payloads históricos de trazas. Los nombres de cuentas creadas por operadores solo cambian cuando su código demuestra que son cuentas internas propiedad del proveedor.

La migración tiene down() simétrico y está cubierta por la certificación semántica de migración de branding.

#Qué no cambia

• shapes de las APIs wire;
• headers específicos de proveedor;
• vocabulario de SDKs oficiales y sus pruebas de compatibilidad;
• atribución de fuentes de contratos oficiales;
• arquitectura canónica de dinero, ledger, idempotencia y webhooks;
• la regla de que el runtime nunca llama a una API real del proveedor.

Los nombres de terceros siguen existiendo cuando describen un contrato externo real. Ya no son la identidad propia de la pasarela.

#Procedimiento de actualización

1. Haz backup de la base de datos. Con PostgreSQL y DATABASE_URL:

   bash Copiar

   pg_dump "$DATABASE_URL" > payment-emulator-before-gateway-identity.sql
   

   En una base gestionada utiliza el mecanismo habitual de snapshot.

2. Registra la release actual y conserva el build anterior para rollback.

3. Renombra la configuración MERCADOPAGO_CONTRACT_URL a PLAZA_COMPATIBILITY_CONTRACT_URL.

4. Despliega el código nuevo y ejecuta las migraciones normales. Las herramientas de setup/update del proyecto ya ejecutan migraciones; un despliegue manual puede usar el CLI de migración existente del API.

5. Actualiza clientes que usen URLs prefijadas propias del emulador a /vector, /harbor o /plaza. Los SDKs oficiales que usan la superficie compatible sin prefijo no necesitan renombrar rutas del protocolo.

6. Actualiza enlaces de checkout, escenarios y tooling local de contratos que estuvieran hard-coded fuera de la base de datos.

7. Reinicia API, worker, Console y Checkout con el procedimiento normal.

#Validación posterior

Ejecuta los gates del repositorio:

npm ci
npm run docs:check
npm run brand:check
npm run typecheck
npm run lint
npm test
npm run test:checkout
npm run test:cli
npm run test:docs
npm run build
npm run certify:branding-migration --workspace @payment-emulator/api
npm run smoke

Para aceptación equivalente a producción ejecuta también la ruta Docker Compose del CI o los health checks de despliegue. Confirma que Console y Checkout muestran Vector, Harbor y Plaza y que ninguna configuración conserva los IDs runtime anteriores.

#Rollback

Si necesitas volver atrás antes de aceptar tráfico nuevo:

1. detén los procesos;
2. despliega la release anterior;
3. ejecuta el down() correspondiente o restaura el backup/snapshot previo;
4. restaura el nombre de variable de entorno esperado por la versión anterior;
5. reinicia y ejecuta sus health/smoke checks.

Si junto a este cambio se desplegaron otros cambios de esquema incompatibles, prefiere restaurar el backup. Esta migración de identidad sí soporta la certificación semántica up -> down -> up, incluyendo identificadores de ledger internos y URLs de replay generadas.

#Política de compatibilidad a partir de esta versión

Los IDs legacy son entradas de migración, no aliases permanentes del runtime. No se deben reintroducir stripe, paypal ni mercadopago como IDs del producto, nombres visibles de gateway o namespaces propios. Cuando un nombre de tercero sea obligatorio por SDK, header, campo wire o fuente documental, se conserva allí y se identifica explícitamente como compatibilidad.