Saltar al contenido principal

🔑 Autenticación de clientes en el Portal vía API

🎯 Introducción​

La autenticación por API permite que un cliente acceda al Portal de Clientes de Debi sin necesidad de ingresar manualmente su correo.
Si el cliente ya está autenticado en tu aplicación, puede ser redirigido directamente al portal mediante una sesión segura y temporal.

🛠️ Cómo crear una sesión autenticada​

Para autenticar a un cliente, tu backend debe crear una sesión del portal llamando a la API de Debi.

Ejemplo en cURL:

curl --request POST \
  --url https://api.debi-test.pro/v1/billing_portal/sessions \
  --header 'Authorization: Bearer sk_test_***' \
  --header 'content-type: application/json' \
  --data-raw '{
    "customer_id":"CSLd8N345MZg"
  }'

  • customer_id: identificador único del cliente en Debi.
  • La respuesta de la API devolverá una URL temporal al portal.

💡 Nota: Esa URL es válida solo por un tiempo limitado.
Si la sesión expira, se debe generar una nueva sesión y URL.

🧩 Flujo de integración en tu aplicación​

  1. El cliente se autentica en tu app (ejemplo: plataforma educativa, gimnasio o SaaS).
  2. Tu backend llama a la API de Debi para generar la sesión del portal.
  3. La API responde con una URL temporal del portal.
  4. La app redirige al cliente automáticamente a esa URL.
  5. En el portal, el cliente puede:
    • Actualizar métodos de pago.
    • Gestionar suscripciones.
    • Completar o actualizar datos de facturación.
  6. Al finalizar, el cliente regresa a tu app (configura un return_url para la redirección de retorno).

📱 Ejemplo práctico: App del usuario​

Imagina una App con este flujo:

  1. El usuario hace clic en “Administrar métodos de pago” (accionador en la UI).
  2. La app solicita al backend que cree la sesión del portal para el customer_id correspondiente.
  3. El backend ejecuta el POST a https://api.debi-test.pro/v1/billing_portal/sessions con el customer_id.
  4. El backend recibe la URL temporal y la devuelve a la app.
  5. La app redirige al usuario a la URL del portal.
  6. El usuario realiza cambios (métodos de pago, suscripciones, facturación).
  7. Al cerrar, el portal redirige al usuario a la return_url configurada.

📝 Recomendaciones y notas importantes​

  • Mantén las claves secretas (sk_test_***) seguras en el backend; nunca las expongas desde el frontend.
  • Verifica que el customer_id exista y esté asociado al cliente autenticado antes de crear la sesión.
  • Maneja errores y estados expirados: si la URL retorna error por expiración, genera una nueva sesión.
  • Define y documenta la return_url para garantizar una experiencia de retorno consistente.
  • Registra auditorías de creación de sesiones para monitoreo y seguridad.

✅ Conclusión​

La autenticación por API del Portal de Clientes de Debi permite:

  • Una experiencia fluida para el cliente (sin reingresar correo).
  • Mayor seguridad mediante sesiones temporales.
  • Integración sencilla dentro de tus aplicaciones para gestionar pagos y suscripciones.

👉 Implementa este flujo para ofrecer a tus clientes control seguro y sin fricciones sobre sus pagos y métodos.