@saulwade/swl-ses 1.0.0

package/habilidades/stripe-pagos/recursos/errores-reintentos.md

@@ -0,0 +1,390 @@
+# Manejo de Errores Stripe y Estrategias de Reintento
+
+Stripe clasifica los errores en categorías con semántica distinta. Manejarlos
+correctamente determina si el usuario ve un mensaje útil, si el sistema se
+recupera solo, o si un pago legítimo se pierde por un error transitorio.
+
+---
+
+## Tipos de errores Stripe
+
+### Jerarquía de excepciones del SDK Python
+
+```
+stripe.error.StripeError          # Base — todos los errores Stripe
+├── stripe.error.CardError        # Tarjeta declinada por el banco emisor
+├── stripe.error.RateLimitError   # Demasiadas peticiones (429)
+├── stripe.error.InvalidRequestError  # Parámetros inválidos (400)
+├── stripe.error.AuthenticationError  # API key inválida (401)
+├── stripe.error.PermissionError  # Sin permisos para la operación (403)
+├── stripe.error.APIConnectionError   # Error de red — Stripe no respondió
+├── stripe.error.IdempotencyError # Idempotency key reutilizada incorrectamente
+└── stripe.error.APIError         # Error interno de Stripe (5xx)
+```
+
+### Atributos clave en CardError
+
+```python
+try:
+    stripe.PaymentIntent.create(...)
+except stripe.error.CardError as e:
+    error = e.error
+    # error.code: 'card_declined', 'insufficient_funds', 'expired_card', etc.
+    # error.decline_code: sub-código del banco emisor
+    # error.message: mensaje técnico de Stripe (inglés)
+    # error.param: parámetro que causó el error (si aplica)
+    print(error.code, error.decline_code)
+```
+
+---
+
+## Clasificación por tipo y estrategia de manejo
+
+| Error | Tipo | ¿Reintentar? | Acción recomendada |
+|-------|------|-------------|-------------------|
+| `card_declined` | CardError | No | Pedir nueva tarjeta al usuario |
+| `insufficient_funds` | CardError | No | Informar fondos insuficientes |
+| `expired_card` | CardError | No | Pedir nueva tarjeta |
+| `incorrect_cvc` | CardError | No (max 3x) | Pedir CVV de nuevo |
+| `authentication_required` | CardError | Sí (con 3DS) | Redirigir a 3D Secure |
+| `rate_limit_error` | RateLimitError | Sí (backoff) | Retry con espera exponencial |
+| `api_connection_error` | APIConnectionError | Sí (backoff) | Retry — error de red |
+| `api_error` (5xx) | APIError | Sí (backoff) | Retry — error interno Stripe |
+| `idempotency_error` | IdempotencyError | No | Revisar la key — bug en código |
+| `invalid_request_error` | InvalidRequestError | No | Bug en la llamada — no reintentar |
+
+---
+
+## Retry con backoff exponencial para errores transitorios
+
+```python
+import asyncio
+import logging
+import stripe
+from typing import TypeVar, Callable, Awaitable
+
+logger = logging.getLogger(__name__)
+T = TypeVar("T")
+
+# Errores que justifican reintento automático
+ERRORES_REINTENTABLES = (
+    stripe.error.RateLimitError,
+    stripe.error.APIConnectionError,
+    stripe.error.APIError,
+)
+
+
+async def stripe_con_retry(
+    operacion: Callable[[], T | Awaitable[T]],
+    max_reintentos: int = 3,
+    base_delay_segundos: float = 1.0,
+    operacion_nombre: str = "stripe_call",
+) -> T:
+    """
+    Ejecuta una operación de Stripe con retry exponencial.
+    Solo reintenta errores transitorios — nunca CardError ni errores de validación.
+    """
+    ultimo_error: Exception | None = None
+
+    for intento in range(max_reintentos + 1):
+        try:
+            resultado = operacion()
+            if asyncio.iscoroutine(resultado):
+                return await resultado
+            return resultado
+
+        except ERRORES_REINTENTABLES as exc:
+            ultimo_error = exc
+            if intento == max_reintentos:
+                logger.error(
+                    "Operación Stripe agotó reintentos",
+                    operacion=operacion_nombre,
+                    intentos=intento + 1,
+                    error=str(exc),
+                )
+                raise
+
+            # Backoff exponencial con jitter: 1s, 2s, 4s + ruido aleatorio
+            import random
+            delay = (base_delay_segundos * (2 ** intento)) + random.uniform(0, 0.5)
+            logger.warning(
+                "Error transitorio Stripe — reintentando",
+                operacion=operacion_nombre,
+                intento=intento + 1,
+                delay_segundos=round(delay, 2),
+                error_tipo=type(exc).__name__,
+            )
+            await asyncio.sleep(delay)
+
+        except (
+            stripe.error.CardError,
+            stripe.error.InvalidRequestError,
+            stripe.error.AuthenticationError,
+            stripe.error.IdempotencyError,
+        ):
+            # Errores no reintentables — fallar inmediatamente
+            raise
+
+    raise RuntimeError("No debería llegar aquí") from ultimo_error
+
+
+# Uso
+async def crear_intent_con_retry(orden: Orden) -> stripe.PaymentIntent:
+    return await stripe_con_retry(
+        lambda: stripe.PaymentIntent.create(
+            amount=int(orden.total * 100),
+            currency="mxn",
+            idempotency_key=f"pi_{orden.id}",
+        ),
+        operacion_nombre=f"crear_payment_intent_{orden.id}",
+    )
+```
+
+---
+
+## Manejo de declinación de tarjeta: mensajes user-friendly
+
+Los mensajes técnicos de Stripe están en inglés y son inapropiados para mostrar
+al usuario. Mapear a mensajes en español claros y útiles:
+
+```python
+# services/mensajes_pago.py
+
+MENSAJES_DECLINACION: dict[str | None, str] = {
+    # Códigos de CardError.code
+    "card_declined": "Tu tarjeta fue declinada. Verifica que los datos sean correctos o intenta con otra tarjeta.",
+    "insufficient_funds": "Tu tarjeta no tiene fondos suficientes para esta compra.",
+    "expired_card": "Tu tarjeta ha expirado. Por favor usa una tarjeta vigente.",
+    "incorrect_cvc": "El código de seguridad (CVV) es incorrecto. Revísalo e intenta de nuevo.",
+    "incorrect_number": "El número de tarjeta es incorrecto.",
+    "invalid_expiry_month": "El mes de vencimiento no es válido.",
+    "invalid_expiry_year": "El año de vencimiento no es válido.",
+    "card_velocity_exceeded": "Has excedido el límite de intentos. Intenta más tarde o usa otra tarjeta.",
+    "do_not_honor": "Tu banco no autorizó el cargo. Contacta a tu banco para más información.",
+    "fraudulent": "Esta transacción fue bloqueada por seguridad. Contacta a tu banco.",
+    "authentication_required": "Tu banco requiere autenticación adicional. Completa el proceso de verificación.",
+    # Fallback para códigos desconocidos
+    None: "No pudimos procesar tu pago. Verifica los datos de tu tarjeta o intenta con otra.",
+}
+
+# Códigos del banco emisor (decline_code) — más específicos
+MENSAJES_DECLINE_CODE: dict[str, str] = {
+    "insufficient_funds": "Fondos insuficientes en tu tarjeta.",
+    "lost_card": "Esta tarjeta fue reportada como perdida. Contacta a tu banco.",
+    "stolen_card": "Esta tarjeta fue reportada como robada. Contacta a tu banco.",
+    "generic_decline": "Tu banco no autorizó el pago. Intenta con otra tarjeta o contacta a tu banco.",
+    "do_not_honor": "Tu banco no autorizó el cargo. Contacta a tu banco directamente.",
+    "card_not_supported": "Tu tarjeta no está habilitada para pagos en línea.",
+    "currency_not_supported": "Tu tarjeta no acepta pagos en esta moneda.",
+}
+
+
+def obtener_mensaje_declinacion(error: stripe.error.CardError) -> str:
+    """Retorna un mensaje en español apropiado para mostrar al usuario."""
+    err = error.error
+
+    # Intentar con decline_code primero (más específico)
+    if err.decline_code and err.decline_code in MENSAJES_DECLINE_CODE:
+        return MENSAJES_DECLINE_CODE[err.decline_code]
+
+    # Luego con code
+    return MENSAJES_DECLINACION.get(
+        err.code,
+        MENSAJES_DECLINACION[None],
+    )
+```
+
+---
+
+## Dunning management: reintentos automáticos en suscripciones
+
+Cuando el cobro de una suscripción falla, Stripe implementa "dunning": reintentos
+automáticos según el schedule configurado en el dashboard. El sistema maneja esto
+de forma transparente, pero la app debe reaccionar a los eventos:
+
+```python
+# Configuración recomendada en el dashboard de Stripe (Smart Retries):
+# - Reintento 1: 3 días después del fallo
+# - Reintento 2: 5 días después del primer reintento
+# - Reintento 3: 7 días después del segundo reintento
+# - Después del último reintento: cancelar suscripción o marcar como unpaid
+
+# La app debe manejar estos eventos para degradar o restaurar acceso:
+
+async def manejar_invoice_payment_failed(invoice: dict) -> None:
+    """
+    Se llama cuando Stripe no pudo cobrar una factura.
+    Estado de suscripción: active → past_due → unpaid → canceled
+    """
+    from app.models.subscripciones import Subscripcion
+    from sqlalchemy import select, update
+
+    stripe_subscription_id = invoice.get("subscription")
+    if not stripe_subscription_id:
+        return
+
+    # Obtener el número de intento para decidir la acción
+    attempt_count = invoice.get("attempt_count", 1)
+
+    async with AsyncSessionLocal() as db:
+        sub = await db.scalar(
+            select(Subscripcion).where(
+                Subscripcion.stripe_subscription_id == stripe_subscription_id
+            )
+        )
+        if sub is None:
+            return
+
+        if attempt_count == 1:
+            # Primer fallo — notificar al usuario, no restringir aún
+            await enviar_notificacion_pago_fallido(sub.usuario_id, intento=1)
+        elif attempt_count == 2:
+            # Segundo fallo — advertencia urgente
+            await enviar_notificacion_pago_fallido(sub.usuario_id, intento=2)
+        else:
+            # Tercer fallo o más — restringir acceso parcialmente
+            await db.execute(
+                update(Subscripcion)
+                .where(Subscripcion.id == sub.id)
+                .values(acceso_restringido=True)
+            )
+            await enviar_notificacion_suspension_inminente(sub.usuario_id)
+        await db.commit()
+
+
+async def manejar_subscripcion_cancelada_por_no_pago(sub: dict) -> None:
+    """
+    Se llama cuando Stripe cancela la suscripción por reintentos agotados.
+    Revocar acceso completamente.
+    """
+    async with AsyncSessionLocal() as db:
+        from sqlalchemy import update
+        from app.models.subscripciones import Subscripcion
+
+        await db.execute(
+            update(Subscripcion)
+            .where(Subscripcion.stripe_subscription_id == sub["id"])
+            .values(estado="cancelada", acceso_restringido=True)
+        )
+        await db.commit()
+```
+
+---
+
+## Dispute handling: evidencia requerida por tipo de disputa
+
+Una disputa (chargeback) ocurre cuando el tarjetahabiente impugna un cargo
+ante su banco. Stripe genera el evento `charge.dispute.created`.
+
+```python
+async def manejar_disputa(disputa: stripe.Dispute) -> None:
+    """
+    Responde automáticamente a disputas con evidencia disponible.
+    El plazo para responder es típicamente 7-21 días según el banco emisor.
+    """
+    from app.models.ordenes import Orden
+
+    # Obtener la orden relacionada
+    payment_intent_id = disputa.payment_intent
+    orden = await Orden.objects.aget(
+        stripe_payment_intent_id=payment_intent_id
+    )
+
+    # Tipos de disputa y evidencia requerida
+    razon = disputa.reason
+    evidencia: dict = {}
+
+    if razon in ("fraudulent", "unrecognized"):
+        # El cliente dice no reconocer el cargo
+        evidencia = {
+            "billing_address": orden.direccion_facturacion,
+            "customer_email_address": orden.usuario.email,
+            "customer_ip_address": orden.ip_cliente,
+            "receipt": orden.url_recibo,
+            "shipping_documentation": orden.url_guia_envio,
+            "uncategorized_text": (
+                f"El cliente {orden.usuario.email} realizó la compra el "
+                f"{orden.creado_en.strftime('%d/%m/%Y')} desde la IP "
+                f"{orden.ip_cliente}. Se enviaron notificaciones de confirmación "
+                f"a su correo registrado."
+            ),
+        }
+
+    elif razon == "product_not_received":
+        # El cliente dice no haber recibido el producto
+        evidencia = {
+            "shipping_documentation": orden.url_guia_envio,
+            "shipping_tracking_number": orden.numero_guia,
+            "shipping_carrier": orden.paqueteria,
+            "shipping_date": orden.fecha_envio.strftime("%Y-%m-%d"),
+            "uncategorized_text": (
+                f"El pedido fue enviado el {orden.fecha_envio.strftime('%d/%m/%Y')} "
+                f"por {orden.paqueteria} con guía {orden.numero_guia}. "
+                f"Estado de entrega: {orden.estado_entrega}."
+            ),
+        }
+
+    elif razon == "duplicate":
+        # El cliente dice que el cargo está duplicado
+        evidencia = {
+            "duplicate_charge_id": disputa.charge,
+            "duplicate_charge_explanation": (
+                "Este cargo corresponde a una única transacción. "
+                f"El ID de orden es {orden.numero}."
+            ),
+            "receipt": orden.url_recibo,
+        }
+
+    if evidencia:
+        stripe.Dispute.modify(
+            disputa.id,
+            evidence=evidencia,
+            submit=True,  # Enviar inmediatamente a Stripe para revisión
+        )
+        logger.info(
+            "Evidencia de disputa enviada",
+            disputa_id=disputa.id,
+            razon=razon,
+            orden_id=str(orden.id),
+        )
+```
+
+### Tipos de disputa y evidencia óptima
+
+| Razón de disputa | Evidencia más efectiva |
+|-----------------|----------------------|
+| `fraudulent` | IP del cliente, email de confirmación, historial de compras |
+| `unrecognized` | Email de confirmación, descripción del producto, IP |
+| `product_not_received` | Guía de envío, número de rastreo, fecha de entrega |
+| `product_unacceptable` | Política de devoluciones, comunicación con el cliente |
+| `duplicate` | Explicación del cargo, recibo original |
+| `subscription_canceled` | Fecha de cancelación, términos de servicio |
+| `credit_not_processed` | Documentación del reembolso ya procesado |
+
+---
+
+## Alertas y monitoreo de salud de pagos
+
+```python
+# Métricas clave a monitorear (enviar a tu sistema de alertas)
+
+ALERTAS_PAGOS = {
+    # Tasa de declinación > 10% en 1 hora → posible fraude o problema técnico
+    "tasa_declinacion_alta": {
+        "umbral": 0.10,
+        "ventana_minutos": 60,
+        "severidad": "alta",
+    },
+    # Más de 3 disputas en 24 horas → revisar calidad del producto/servicio
+    "disputas_frecuentes": {
+        "umbral": 3,
+        "ventana_horas": 24,
+        "severidad": "media",
+    },
+    # Webhook sin procesar por más de 5 minutos → posible problema en el endpoint
+    "webhook_delayed": {
+        "umbral_minutos": 5,
+        "severidad": "alta",
+    },
+}
+```

package/habilidades/stripe-pagos/recursos/stripe-connect.md

@@ -0,0 +1,290 @@
+# Stripe Connect — Marketplaces y Plataformas
+
+Stripe Connect permite que una plataforma facilite pagos entre compradores
+y vendedores (o prestadores de servicio), reteniendo una comisión y pagando
+a los vendedores automáticamente. Es el sistema detrás de marketplaces como
+Airbnb, Etsy o plataformas de freelancers.
+
+---
+
+## Modelo de negocio: plataforma → vendedor → cliente
+
+```
+Cliente
+  |
+  | paga $1,000 MXN
+  v
+Plataforma (cuenta Stripe principal)
+  |
+  | transfiere $900 MXN al vendedor
+  | retiene $100 MXN como comisión
+  v
+Vendedor (cuenta Stripe Connect — "connected account")
+```
+
+La plataforma es responsable ante Stripe de los pagos. Los vendedores reciben
+payouts directamente en su cuenta bancaria según el schedule configurado.
+
+---
+
+## Tipos de cargos en Connect
+
+### 1. Destination Charges (recomendado para la mayoría de casos)
+
+El cargo se crea en la cuenta de la **plataforma** y se transfiere al vendedor.
+La plataforma es responsable de disputas y reembolsos.
+
+```python
+import stripe
+from app.core.config import settings
+
+stripe.api_key = settings.STRIPE_SECRET_KEY
+
+
+async def crear_cobro_marketplace(
+    monto_total_centavos: int,
+    comision_plataforma_centavos: int,
+    stripe_account_id_vendedor: str,
+    orden_id: str,
+) -> stripe.PaymentIntent:
+    """
+    Crea un Destination Charge.
+    El cliente paga monto_total; el vendedor recibe (monto_total - comision).
+    """
+    return stripe.PaymentIntent.create(
+        amount=monto_total_centavos,
+        currency="mxn",
+        # La comisión que retiene la plataforma
+        application_fee_amount=comision_plataforma_centavos,
+        # La cuenta Connect del vendedor recibe el resto
+        transfer_data={
+            "destination": stripe_account_id_vendedor,
+        },
+        metadata={"orden_id": orden_id},
+        idempotency_key=f"pi_marketplace_{orden_id}",
+    )
+```
+
+### 2. Direct Charges (para mayor autonomía del vendedor)
+
+El cargo se crea directamente en la cuenta del **vendedor**. La plataforma
+toma su comisión vía `application_fee_amount`. El vendedor maneja disputas.
+Requiere que el cliente conozca la marca del vendedor.
+
+```python
+async def crear_cobro_directo(
+    monto_centavos: int,
+    comision_centavos: int,
+    stripe_account_id_vendedor: str,
+    orden_id: str,
+) -> stripe.PaymentIntent:
+    """Cargo directo en la cuenta del vendedor."""
+    return stripe.PaymentIntent.create(
+        amount=monto_centavos,
+        currency="mxn",
+        application_fee_amount=comision_centavos,
+        metadata={"orden_id": orden_id},
+        idempotency_key=f"pi_direct_{orden_id}",
+        stripe_account=stripe_account_id_vendedor,  # Clave: ejecutar en cuenta del vendedor
+    )
+```
+
+### 3. Separate Charges and Transfers (control máximo)
+
+Cobra al cliente en la cuenta de la plataforma y crea transferencias
+independientes a uno o varios vendedores. Útil cuando un pedido tiene
+productos de múltiples vendedores.
+
+```python
+async def distribuir_pago_multi_vendedor(
+    payment_intent_id: str,
+    distribuciones: list[dict],  # [{"account": "acct_xxx", "amount": 500}]
+) -> list[stripe.Transfer]:
+    """
+    Transfiere partes del pago a múltiples vendedores.
+    Llamar DESPUÉS de que el PaymentIntent sea exitoso.
+    """
+    transferencias = []
+    for dist in distribuciones:
+        transferencia = stripe.Transfer.create(
+            amount=dist["amount"],
+            currency="mxn",
+            destination=dist["account"],
+            source_transaction=payment_intent_id,
+            idempotency_key=f"transfer_{payment_intent_id}_{dist['account']}",
+        )
+        transferencias.append(transferencia)
+    return transferencias
+```
+
+---
+
+## Onboarding de vendedores: AccountLink para KYC
+
+Stripe requiere verificar la identidad de los vendedores (KYC — Know Your Customer)
+antes de permitirles recibir pagos. Este proceso se realiza vía AccountLink.
+
+### Paso 1: Crear la cuenta Connect del vendedor
+
+```python
+async def crear_cuenta_vendedor(
+    email: str,
+    usuario_id: str,
+) -> stripe.Account:
+    """
+    Crea una cuenta Connect de tipo 'express' (recomendado).
+    - express: Stripe maneja el onboarding UI (dashboard simplificado para el vendedor)
+    - standard: el vendedor tiene acceso completo al dashboard de Stripe
+    - custom: la plataforma controla toda la UI (requiere más trabajo y responsabilidad)
+    """
+    cuenta = stripe.Account.create(
+        type="express",
+        email=email,
+        country="MX",
+        capabilities={
+            "card_payments": {"requested": True},
+            "transfers": {"requested": True},
+        },
+        business_type="individual",
+        metadata={"usuario_id": usuario_id},
+    )
+    # Guardar cuenta.id como stripe_connect_account_id en la BD del vendedor
+    return cuenta
+
+
+async def generar_link_onboarding(
+    stripe_account_id: str,
+    usuario_id: str,
+) -> str:
+    """
+    Genera un AccountLink para que el vendedor complete el KYC.
+    El link expira en ~10 minutos — generar justo antes de redirigir.
+    """
+    link = stripe.AccountLink.create(
+        account=stripe_account_id,
+        refresh_url=f"{settings.BASE_URL}/vendedores/onboarding/reiniciar",
+        return_url=f"{settings.BASE_URL}/vendedores/onboarding/completado",
+        type="account_onboarding",
+    )
+    return link.url
+
+
+async def verificar_onboarding_completo(stripe_account_id: str) -> bool:
+    """Verifica si el vendedor completó el KYC y puede recibir pagos."""
+    cuenta = stripe.Account.retrieve(stripe_account_id)
+    return (
+        cuenta.details_submitted
+        and cuenta.charges_enabled
+        and cuenta.payouts_enabled
+    )
+```
+
+### Flujo de onboarding completo
+
+```
+1. Vendedor hace clic en "Conectar cuenta de pagos"
+2. Backend llama crear_cuenta_vendedor() → guarda stripe_connect_account_id
+3. Backend llama generar_link_onboarding() → redirige al vendedor a Stripe
+4. Vendedor completa KYC en Stripe (CURP, datos bancarios, etc.)
+5. Stripe redirige a return_url
+6. Backend llama verificar_onboarding_completo() para confirmar
+7. Stripe envía webhook account.updated cuando cambia el estado
+```
+
+---
+
+## Splits de pago: application_fee_amount
+
+La comisión de la plataforma se especifica en `application_fee_amount` (centavos).
+Esta comisión se retiene automáticamente antes de transferir al vendedor.
+
+```python
+# Ejemplo: orden de $1,000 MXN con 10% de comisión de plataforma
+monto_total = 100_000       # $1,000.00 MXN en centavos
+comision = 10_000           # $100.00 MXN (10%)
+# El vendedor recibe: $900.00 MXN
+
+# Cálculo dinámico de comisión
+def calcular_comision(monto_centavos: int, porcentaje: float) -> int:
+    """Retorna la comisión en centavos, redondeando hacia arriba."""
+    import math
+    return math.ceil(monto_centavos * porcentaje / 100)
+```
+
+---
+
+## Payout schedule para vendedores
+
+Por defecto, Stripe realiza payouts automáticos a las cuentas bancarias de
+los vendedores. Se puede configurar el schedule por cuenta:
+
+```python
+async def configurar_payout_schedule(
+    stripe_account_id: str,
+    intervalo: str = "weekly",  # "daily" | "weekly" | "monthly"
+    dia_semana: str = "friday",  # Para weekly
+) -> stripe.Account:
+    """
+    Configura cuándo recibe payouts el vendedor.
+    - daily: cada día hábil (requiere cuenta activa por ≥ 7 días)
+    - weekly: el día especificado de la semana
+    - monthly: el día especificado del mes (1-31)
+    """
+    return stripe.Account.modify(
+        stripe_account_id,
+        settings={
+            "payouts": {
+                "schedule": {
+                    "interval": intervalo,
+                    "weekly_anchor": dia_semana,
+                }
+            }
+        },
+        stripe_account=stripe_account_id,
+    )
+```
+
+---
+
+## Webhooks críticos para Connect
+
+Además de los webhooks estándar, Connect genera eventos para cuentas conectadas:
+
+```python
+# El header stripe-signature sigue siendo obligatorio verificar
+# Los eventos de cuentas conectadas incluyen account.updated
+
+match evento.type:
+    case "account.updated":
+        # Verificar si el vendedor completó onboarding
+        cuenta = evento.data.object
+        await actualizar_estado_vendedor(cuenta.id, cuenta.charges_enabled)
+    case "account.application.deauthorized":
+        # El vendedor desconectó la plataforma — revocar acceso
+        await revocar_vendedor(evento.data.object.id)
+    case "transfer.created":
+        # Transferencia enviada al vendedor
+        await registrar_transferencia(evento.data.object)
+    case "payout.paid":
+        # El vendedor recibió el dinero en su banco
+        await marcar_payout_pagado(evento.data.object)
+    case "payout.failed":
+        # El payout falló (cuenta bancaria inválida, etc.)
+        await notificar_payout_fallido(evento.data.object)
+```
+
+---
+
+## MUST DO / MUST NOT DO en Connect
+
+**MUST DO:**
+- Guardar `stripe_connect_account_id` en la BD del vendedor desde el momento de creación.
+- Verificar `charges_enabled` Y `payouts_enabled` antes de permitir transacciones.
+- Manejar `account.updated` para actualizar el estado de onboarding en tiempo real.
+- Escalar `application_fee_amount` según la lógica de negocio de cada transacción.
+
+**MUST NOT DO:**
+- NUNCA crear un transfer sin `source_transaction` — vincula la transferencia al cobro.
+- NUNCA hacer payouts manuales cuando el schedule automático es suficiente.
+- NUNCA asumir que el return_url significa que el onboarding está completo — verificar con la API.
+- NUNCA compartir el `stripe_account_id` de un vendedor con otros vendedores.