Creación de Cuentas (Intents)

La creación de una cuenta comercio se inicializa mediante la creación de una Intención de Registro (Intent). Este proceso genera una sesión temporal y segura.

Crear Intent de Onboarding

Genera una URL única para que el comercio cliente complete su afiliación.

• Endpoint: api/v2/onboarding/intent
• Método: POST

Headers

X-API-KEY: <TU_MASTER_API_KEY>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <UUID_V4> (Requerido)

Idempotencia Obligatoria

Para mantener un estándar unificado en toda la API de Vendis (al igual que en Pay-In y Pay-Out) y prevenir registros duplicados accidentales por fallas en la red, la creación de intents requiere obligatoriamente idempotencia en las cabeceras.

• Header: Idempotency-Key (Mandatorio)
• Formato: Un identificador único de tipo UUID v4 (ej. e1a50a12-872f-4b08-8e6d-5a8b79c2356c).
• Comportamiento: Si tu sistema reintenta la petición con el mismo Idempotency-Key, Vendis retornará en caché el intent de onboarding previamente creado, evitando generar registros huérfanos.

Parámetros de Petición (Body JSON)

Atributo	Tipo	Obligatorio	Descripción
success_url	string	No	URL de redirección (callback) tras una activación exitosa.
cancel_url	string	No	URL de redirección si el comercio aborta el proceso.
metadata	object	No	Objeto de clave-valor para almacenar datos de trazabilidad (ej. tenant_id, user_id). Se devolverá intacto en el Webhook.

Ejemplo de Petición:

{
    "success_url": "https://dashboard.tu-ecommerce.com/onboarding/success",
    "metadata": {
        "tenant_id": "T-9872",
        "plan": "premium"
    }
}

Ejemplo de Respuesta (HTTP 201 Created):

{
  "code": "ONB-XXXX-XXXX",
  "url": "https://onboarding.vendis.com/start/onb_abcdef123...",
  "expires_at": "2026-04-24T15:51:00Z"
}

Nota: Para conocer la estructura de errores de validación (HTTP 422) y errores generales (401, 500, etc.), por favor revisa la sección de Códigos HTTP y Errores.

---

Expiración y Duración del Intent

Para garantizar la seguridad del flujo de afiliación y evitar enlaces de registro huérfanos o reutilizados de forma indebida, todo intent está sujeto a estrictas reglas de expiración.

Reglas de Duración

• Tiempo de Vida Útil (TTL): Por defecto, la URL de onboarding generada en el campo url tiene una vigencia de 120 minutos (2 horas) a partir del instante de su creación.
• Fecha Límite Explícita (expires_at): La respuesta de la API siempre retorna el campo expires_at en formato estándar ISO 8601 (UTC). Representa el momento exacto en el que el intent dejará de ser utilizable.
• Sesión Única: Una vez que el comercio completa exitosamente el registro (completed) o lo cancela (cancelled), el intent se marca de forma definitiva como cerrado y la URL expira inmediatamente, impidiendo reingresos accidentales.

¿Qué ocurre cuando un Intent expira?

Si el comercio intenta ingresar a la url de onboarding tras haber superado la fecha y hora indicadas en expires_at:

1. El navegador del cliente mostrará una pantalla de error nativa de Vendis indicando que "El enlace de registro ha expirado".
2. El estado del intent en las consultas de API cambiará automáticamente a expired.
3. No se permitirá reanudar el formulario de registro ni procesar ningún pago de activación con ese token.

Estrategia de Recuperación Recomendada para el Integrador

Cuando desarrolles la integración con Vendis, es fundamental implementar un flujo de reintento amigable para los comercios cuyas sesiones hayan expirado:

1. Evitar almacenamiento persistente de URLs: No guardes la URL de onboarding indefinidamente en tus bases de datos. Utilízala únicamente para la redirección inmediata del usuario.
2. Botón de Reintento ("Generar Nuevo Enlace"): En tu panel de administración o portal de partners, si detectas que el comercio no completó la afiliación dentro de las 2 horas, preséntale una opción clara para "Generar nuevo enlace de registro".
3. Flujo de Regeneración: Cuando el comercio haga clic en este botón:
   • Tu sistema debe consumir nuevamente el endpoint POST /api/v2/onboarding/intent (usando una nueva Idempotency-Key o simplemente solicitando un nuevo intent para ese comercio).
   • Redirige al comercio inmediatamente a la nueva URL devuelta.