Ejemplos prácticos

Estas recetas usan únicamente los endpoints documentados en API Reference. Cada sección muestra cómo unir rutas reales bajo /v1/user para resolver flujos cotidianos: autenticación passwordless, administración de perfil y registro de dispositivos.

Antes de ejecutar cualquiera de los ejemplos, revisa la guía de autenticación para decidir si firmarás con API keys o usarás un token devuelto por GET /v1/user/token.

Ejemplo 1 · Inicio de sesión passwordless con PIN

Este flujo crea (o busca) al usuario, envía un PIN de seis dígitos y lo valida para establecer las cookies de sesión de Gestiono.

1. POST /v1/user/login (opcional) para crear un registro preliminar si es un usuario nuevo.
2. GET /v1/user/login/pinRequest envía el código y responde 200 inmediatamente.
3. POST /v1/user/login/verifyPin valida el código ingresado por tu cliente y crea la cookie session-token.

Una vez que la sesión esté lista puedes ejecutar GET /v1/user desde el explorador interactivo usando el modo “Cookies”.

Ejemplo 2 · Gestiona el perfil y emite tokens reutilizables

Mantén actualizados los datos del usuario autenticado y genera un token bearer para integraciones que prefieren el header Authorization en lugar de recalcular la firma HMAC. Usa el token recibido para llamar endpoints autenticados sin volver a firmar. Si necesitas cerrar la sesión del usuario actual, manda un DELETE /v1/user/logout con ese mismo token.

Ejemplo 3 · Registrar dispositivos push y cerrar sesión

Cuando un usuario activa notificaciones Web Push, debes vincular el deviceId y el endpoint generado por el navegador a su cuenta. Posteriormente puedes revocar la sesión y limpiar esa suscripción en tu backend propio.

Si tu equipo de soporte necesita tomar control temporal de otra cuenta, combina este flujo con POST /v1/user/login/controller y luego elimina la sesión delegada con /logout.

Checklist antes de ir a producción

• ✅ Variables sensibles (API keys y tokens) almacenadas en un vault o secret manager.
• ✅ Retries con backoff para respuestas 429/5xx y validación de idempotencia en tu lado.
• ✅ Tests unitarios que cubren la firma HMAC y el flujo de PIN con datos controlados.
• ✅ Monitor de auditoría para /v1/user/login/controller y /logout.
• ✅ Limpieza programada de suscripciones push obsoletas mediante /logout + /subscribe.

Continúa con Primeros pasos, revisa cada endpoint en la referencia y consulta el sistema de eventos para automatizar reacciones ante cambios clave.