Implementación en Producción

Poner en vivo es un cambio de configuración, no una reescritura. Tus queries, mutations y flujos son idénticos en ambos entornos. Lo que cambia es a qué hosts llamas y con qué credenciales los llamas — y esos cambian por completo.

Nada se traslada desde staging. Las aplicaciones, claves de API, client secrets, URIs de redirección y suscripciones de webhook existen por separado en cada entorno. Una credencial de staging nunca funcionará contra un host de producción y viceversa. Eso es deliberado: es lo que hace imposible mover dinero real accidentalmente desde un entorno de pruebas.

Mapa de endpoints

Propósito	Staging	Producción
Panel del desarrollador	`https://uni.staging.fluzapp.com/apps-and-integrations`	`https://fluz.app/for-developers`
OAuth authorize	`https://uni.staging.fluzapp.com/authorize`	`https://fluz.app/authorize`
Token exchange	`https://uni.staging.fluzapp.com/token/exchange`	`https://fluz.app/token/exchange`
Token refresh	`https://uni.staging.fluzapp.com/token/refresh`	`https://fluz.app/token/refresh`
GraphQL API	`https://transactional-graph.staging.fluzapp.com/api/v1/graphql`	`https://transactional-graph.fluzapp.com/api/v1/graphql`

El host de GraphQL y el host de OAuth son servicios distintos con dominios diferentes. Cambiar uno y no el otro es el error de corte más común — y falla de forma confusa, porque la autorización tiene éxito y luego cada llamada al API es rechazada.

Cómo acceder a cada portal

El portal live está en https://fluz.app/for-developers. Desde allí, la pestaña de desarrollador tiene un enlace ‘Open Staging’ hacia el portal de staging — tus credenciales de inicio de sesión son las mismas en ambos. Cada portal muestra solo las aplicaciones y claves de API de ese entorno.

Haz del entorno una variable

Si algún host, clave o URI de redirección es un string literal en tu base de código, corrígelo antes del corte. Todo lo específico del entorno pertenece a la configuración.

const ENVIRONMENTS = {
  staging: {
    authorizeUrl: 'https://uni.staging.fluzapp.com/authorize',
    tokenExchangeUrl: 'https://uni.staging.fluzapp.com/token/exchange',
    tokenRefreshUrl: 'https://uni.staging.fluzapp.com/token/refresh',
    graphqlUrl: 'https://transactional-graph.staging.fluzapp.com/api/v1/graphql',
    redirectUri: 'https://staging.example.com/oauth/finalize',
  },
  production: {
    authorizeUrl: 'https://fluz.app/authorize',
    tokenExchangeUrl: 'https://fluz.app/token/exchange',
    tokenRefreshUrl: 'https://fluz.app/token/refresh',
    graphqlUrl: 'https://transactional-graph.fluzapp.com/api/v1/graphql',
    redirectUri: 'https://app.example.com/oauth/finalize',
  },
};

export const fluz = ENVIRONMENTS[process.env.FLUZ_ENV ?? 'staging'];

// Credentials come from your secret store, keyed by the same environment name.
export const credentials = {
  clientId: process.env.FLUZ_CLIENT_ID,
  clientSecret: process.env.FLUZ_CLIENT_SECRET,
  apiKey: process.env.FLUZ_API_KEY,
  apiSecret: process.env.FLUZ_API_SECRET,
};

import os

ENVIRONMENTS = {
    "staging": {
        "authorize_url": "https://uni.staging.fluzapp.com/authorize",
        "token_exchange_url": "https://uni.staging.fluzapp.com/token/exchange",
        "token_refresh_url": "https://uni.staging.fluzapp.com/token/refresh",
        "graphql_url": "https://transactional-graph.staging.fluzapp.com/api/v1/graphql",
        "redirect_uri": "https://staging.example.com/oauth/finalize",
    },
    "production": {
        "authorize_url": "https://fluz.app/authorize",
        "token_exchange_url": "https://fluz.app/token/exchange",
        "token_refresh_url": "https://fluz.app/token/refresh",
        "graphql_url": "https://transactional-graph.fluzapp.com/api/v1/graphql",
        "redirect_uri": "https://app.example.com/oauth/finalize",
    },
}

FLUZ = ENVIRONMENTS[os.environ.get("FLUZ_ENV", "staging")]

# Credentials come from your secret store, keyed by the same environment name.
CREDENTIALS = {
    "client_id": os.environ["FLUZ_CLIENT_ID"],
    "client_secret": os.environ["FLUZ_CLIENT_SECRET"],
    "api_key": os.environ["FLUZ_API_KEY"],
    "api_secret": os.environ["FLUZ_API_SECRET"],
}

Usa staging como valor predeterminado, nunca producción. Si un despliegue pierde su variable de entorno, quieres que apunte al entorno de pruebas, no que mueva dinero real.

Reconstruye tu app en el portal live

Vuelve a realizar Create an OAuth App y Configure OAuth App en https://fluz.app/for-developers. Luego verifica cada uno de estos — cada uno es algo que la gente suele olvidar:

Reemite cada credencial

client_id, client_secret, apiKey y apiSecret de producción son todos valores nuevos. Ponlos en tu almacén de secretos de producción. Confirma que ningún valor de staging sobrevive en una configuración de producción.

Vuelve a registrar URIs de redirección en hosts de producción

Tu URL de callback de producción, en su forma canónica exacta. Luego elimina cualquier localhost o URIs de staging — una app de producción no debe aceptar una redirección a la laptop de un desarrollador.

Redirige URLs de webhook

A endpoints de producción que sean públicamente accesibles, monitoreados y con alertas. Rehaz las suscripciones por evento; no se copian entre entornos. Si usaste una URL catch-all en staging, decide si realmente quieres eso en producción.

Configura Origin a tu dominio de producción

Para widgets embebidos, esto debe coincidir con el dominio que realmente sirve la página, o el widget no cargará.

Vuelve a seleccionar tus scopes

Las selecciones de scopes no se transfieren. Recorre las llamadas al API de tu integración y confirma que el scope de cada una esté marcado en la pestaña Permissions de la app de producción. Un scope faltante se omite silenciosamente, no se rechaza.

Completa la pestaña Overview

Nombre, subtítulo, descripción, avatar y logomark son lo que usuarios reales ahora ven en una pantalla de consentimiento real decidiendo si darte acceso a su dinero. El texto placeholder llega a producción si lo permites.

Confirma el estado de tu app

Las aplicaciones tienen un estado en el dashboard — una app en revisión aún no es una app que tus clientes puedan usar. Confirma que tu app de producción esté activa antes de anunciar nada.

Qué se comporta diferente en producción

Staging refleja las capacidades y flujos de transacción de producción sin dinero real. Eso cubre la mayor parte de la superficie, pero no toda.

	Staging	Producción
Fondos	Simulados	Reales. Las transferencias son irreversibles de tu lado
KYC	Rutas de prueba con resultados predecibles	Verificación real contra datos de identidad reales, con rechazos reales
Autorizaciones de tarjeta	Simuladas	Autorizaciones en red en vivo y rechazos reales
Tiempos de liquidación	Inmediatos o simulados	Tiempos bancarios reales
Fuentes de fondos	Tarjetas y cuentas bancarias de prueba	Tarjetas reales y cuentas vinculadas por Plaid
Modos de falla	Los que elegiste probar	Fondos insuficientes, tarjetas vencidas, rechazos de red, fallas de verificación

Tres consecuencias que vale la pena planificar:

La idempotencia deja de ser opcional. Cada llamada que mueve dinero necesita un idempotencyKey único, y los tokens de widget necesitan un jti único. En staging un duplicado es una molestia; en producción es un pago doble. Ver Idempotency.
Tu manejo de errores se pone a prueba. Los usuarios de prueba no son rechazados por fondos insuficientes ni fallan KYC de formas que no guionaste. Cada ruta de falla necesita un resultado definido de cara al usuario antes del lanzamiento, no después.
La conciliación importa. Verifica saldos en ambos lados de una transferencia en lugar de asumir éxito por una respuesta 200.

Higiene de datos, en ambas direcciones

Nunca pongas datos de producción en staging. Ni detalles reales de clientes, ni información financiera real, ni PII. Staging es para datos creados explícitamente para pruebas. La inversa también aplica: no lleves usuarios de prueba, fuentes de fondos de prueba o payloads de webhook de prueba a producción. Los artefactos de prueba en un libro mayor live son difíciles de desentrañar después, y algunos no pueden eliminarse.

Corte de widgets

Si estás publicando un widget embebido, aplican las mismas reglas más estas:

Regenera el código de inserción desde la pestaña Installation de la app de producción. El apiKey incluido en el snippet es específico del entorno.
Firma los patTokens con tu apiSecret de producción, del lado del servidor. Confirma que el secret se cargue desde tu almacén de secretos de producción y que el generador de tokens no siga apuntando a un valor de staging.
Confirma Origin coincida exactamente con tu dominio de producción.
Vuelve a verificar el tipo de transacción. Pay-In y Payout mueven dinero en direcciones opuestas; verifica la dirección contra una transferencia real antes de abrirlo a usuarios.

Lista de verificación previa al lanzamiento

Configuración

App de producción creada, configurada y activa
Las cuatro credenciales reemitidas y almacenadas en el almacén de secretos de producción
No quedan URIs de redirección de staging o localhost en la app de producción
URLs de webhook apuntan a endpoints de producción, con suscripciones de eventos vueltas a seleccionar
Scopes vueltos a seleccionar y alineados con tus llamadas reales al API
Pestaña Overview completa: nombre, subtítulo, descripción, avatar, logomark

Código

No hay hosts, claves o URIs de redirección hard-coded en la base de código
La resolución de entorno predetermina a staging
Se cambiaron tanto el host de OAuth como el host de GraphQL
Claves de idempotencia generadas por operación, no por sesión
La ruta de callback es idempotente y valida state
La renovación de token corre antes del vencimiento en lugar de reaccionar a una falla

Operaciones

Endpoint de webhook monitoreado, con alertas ante fallas de entrega o procesamiento
El logging captura identificadores de solicitud y claves de idempotencia, y nunca captura secretos, PANs ni PII
Hay responsables de los runbooks de “el usuario no puede conectar” y “transferencia atascada”
Ejecutaste una transacción real end-to-end al monto más pequeño posible, en ambas direcciones, y reconciliaste ambos libros mayores

Despliegue

Usuarios internos primero, luego una cohorte pequeña, luego disponibilidad general
Puedes deshabilitar la integración sin desplegar código: un feature flag, no un rollback
Ruta de reautorización construida y probada, para cuando expiren los refresh tokens o los usuarios revoquen

Fallas comunes en el corte

Síntoma	Causa
OAuth tiene éxito y luego cada llamada al API es rechazada	El host de GraphQL sigue apuntando a staging (o viceversa)
`/authorize` da error en la URL de producción	El URI de redirección de la app de producción no está registrado, o `client_id` es el valor de staging
El intercambio de token falla justo después de un consentimiento exitoso	El header de basic auth está construido con `client_id`/`client_secret` de staging
El widget no se renderiza en el sitio live	`Origin` sigue configurado al dominio de staging o localhost
El widget abre pero la transacción es rechazada	`patToken` firmado con el `apiSecret` de staging
Un permiso que funcionaba en staging ahora falla	No se volvieron a seleccionar los scopes en la app de producción
No hay webhooks en producción	No se redirigieron las URLs o no se volvieron a seleccionar las suscripciones de eventos
La pantalla de consentimiento muestra un nombre de app placeholder	Nunca se completó la pestaña Overview en producción
Transferencias duplicadas	Clave de idempotencia reutilizada o regenerada por reintento

Próximos pasos

Configurar app OAuth

Vuelve a ejecutar cada pestaña en tu app de producción.

Flujo de otorgamiento

Verifica la pantalla de consentimiento en hosts de producción.

Refrescar un access token

Mantén vivas las conexiones de producción sin volver a pedir permiso.

Funciones del API

Todo ahora corriendo contra dinero real.

​Mapa de endpoints

​Cómo acceder a cada portal

​Haz del entorno una variable

​Reconstruye tu app en el portal live

​Qué se comporta diferente en producción

​Higiene de datos, en ambas direcciones

​Corte de widgets

​Lista de verificación previa al lanzamiento

​Fallas comunes en el corte

​Próximos pasos

Configurar app OAuth

Flujo de otorgamiento

Refrescar un access token

Funciones del API

Mapa de endpoints

Cómo acceder a cada portal

Haz del entorno una variable

Reconstruye tu app en el portal live

Qué se comporta diferente en producción

Higiene de datos, en ambas direcciones

Corte de widgets

Lista de verificación previa al lanzamiento

Fallas comunes en el corte

Próximos pasos