Sesiones y configuración del Customer Portal

El Customer Portal permite que un cliente gestione sus propias suscripciones y métodos de pago sin necesidad de contactar al soporte. Una sesión comienza con un magic link: el cliente solicita un enlace por correo electrónico y, luego, el paso de verificación intercambia el token enviado por correo por una cookie de sesión. Estos endpoints cubren ese handshake, la sesión actual, el payload de bootstrap que la interfaz carga primero, y la configuración del portal.

Todo lo demás en el portal — suscripciones, métodos de pago, cuenta — funciona sobre la cookie establecida aquí. El portal es white-label, por lo que su branding y las acciones permitidas provienen de la configuración del portal del Merchant.

La sesión del portal

Devuelto por los endpoints de listado y consulta de esta página.

Endpoints

GET/api/v1/merchants/:merchant_id/portal-config

Branding y comportamiento del portal self-service que usan tus clientes para gestionar sus suscripciones. Devuelve valores predeterminados cuando aún no se ha configurado nada.

Parámetros de ruta

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/portal-config \
  -H "Cookie: tf_portal_session=…"

Ejemplo de respuesta — 200

{
  "merchant_id": "mrc_123",
  "allow_cancellation": true,
  "allow_plan_change": true,
  "allow_payment_method_change": true,
  "cancellation_survey": true,
  "custom_cancellation_message": "Operation completed successfully"
}

PUT/api/v1/merchants/:merchant_id/portal-config

Hace upsert de la configuración — la primera llamada la crea, las llamadas posteriores reemplazan los campos que envías.

Parámetros de ruta

Campos de la solicitud

Ejemplo de solicitud

curl -X PUT https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/portal-config \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "allow_cancellation": true,
    "allow_plan_change": true,
    "allow_payment_method_change": true,
    "cancellation_survey": true,
    "custom_cancellation_message": "Operation completed successfully"
  }'

Ejemplo de respuesta — 200

{
  "merchant_id": "mrc_123",
  "allow_cancellation": true,
  "allow_plan_change": true,
  "allow_payment_method_change": true,
  "cancellation_survey": true,
  "custom_cancellation_message": "Operation completed successfully"
}

POST/api/v1/portal/auth/email-change/confirm

Confirma un cambio de correo electrónico mediante el token enviado por correo.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/email-change/confirm \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

POST/api/v1/portal/auth/logout

Borra la cookie de sesión del portal.

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/logout \
  -H "Cookie: tf_portal_session=…"

GET/api/v1/portal/auth/me

Obtiene la cuenta de la sesión actual del portal.

Ejemplo de solicitud

curl https://api.tokeflow.com/api/v1/portal/auth/me \
  -H "Cookie: tf_portal_session=…"

Ejemplo de respuesta — 200

{
  "id": "cpa_123",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "email": "customer@example.com",
  "expires_in": 1800
}

POST/api/v1/portal/auth/request-link

Solicita un correo electrónico de magic-link del portal.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/request-link \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": "org_123",
    "merchant_id": "mrc_123",
    "email": "customer@example.com"
  }'

POST/api/v1/portal/auth/verify

Verifica un token de magic-link; establece la cookie de sesión.

Campos de la solicitud

Ejemplo de solicitud

curl -X POST https://api.tokeflow.com/api/v1/portal/auth/verify \
  -H "Cookie: tf_portal_session=…" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string"
  }'

Ejemplo de respuesta — 200

{
  "id": "cpa_123",
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "email": "customer@example.com",
  "expires_in": 1800
}

GET/api/v1/portal/bootstrap

Resuelve el branding y las flags del Merchant para el portal.

Parámetros de consulta

Ejemplo de solicitud

curl -G https://api.tokeflow.com/api/v1/portal/bootstrap \
  -H "Cookie: tf_portal_session=…" \
  --data-urlencode "merchant_id=mrc_123" \
  --data-urlencode "organization_id=org_123" \
  --data-urlencode "merchant=acme-store"

Ejemplo de respuesta — 200

{
  "organization_id": "org_123",
  "merchant_id": "mrc_123",
  "merchant_slug": "acme-store",
  "merchant_name": "Acme Store",
  "branding": {
    "site_title": "Acme Store",
    "favicon": "string",
    "logo_light_mode": "string",
    "logo_dark_mode": "string",
    "theme_primary_color": "#1A73E8",
    "theme_secondary_color": "#0B5394",
    "custom_url": "https://acme.example.com",
    "show_name_with_logo": false
  },
  "config": {
    "allow_cancellation": true,
    "allow_plan_change": true,
    "allow_payment_method_change": true,
    "cancellation_survey": false,
    "custom_cancellation_message": "Operation completed successfully"
  }
}

Errores

Los errores usan el sobre estándar. Los casos más comunes aquí:

Relacionados

• Suscripciones del portal
• Métodos de pago del portal
• Configuración del portal del Merchant