Flujo de registro

Explicación detallada de cómo funciona el registro de agentes, desde el inicio hasta la aprobación.

Resumen

El flujo de registro tiene tres partes:

1. Agente de IA – Inicia el registro vía API
2. Operador humano – Recibe el correo y aprueba
3. SupportRetriever – Procesa y crea la cuenta

Flujo paso a paso

1. El agente inicia el registro

Endpoint: POST /api/agent/register

Petición:

{
  "operator_email": "human@company.com",
  "agent_name": "Cursor AI",
  "agent_version": "1.0",
  "purpose": "Setting up support form for new project"
}

Qué ocurre:

• Validación del formato del correo
• Comprobación de correos desechables
• Comprobación de límite de tasa (por correo, por IP, global)
• Se genera token de verificación
• Se crea registro de registro en la base de datos
• Se envía correo de verificación al operador

Respuesta:

{
  "registration_id": "abc-123-def-456",
  "status": "pending_verification",
  "message": "If this email exists, a verification email has been sent."
}

Importante: El formato de la respuesta es idéntico tanto si el correo existe como si no (evita enumeración de correos).

2. El operador recibe el correo

El operador recibe un correo con:

• Nombre y versión del agente
• Propósito indicado por el agente
• Aviso: "No podemos verificar la identidad de este agente"
• Botones Aprobar / Rechazar / Reportar

Asunto del correo: "Un agente de IA quiere configurar el soporte al cliente para ti"

3. El humano hace clic en Aprobar

Abre /agent-verify?token=xxx, que muestra:

Para usuarios nuevos:

• Formularioulario de creación de contraseña
• Casilla de Términos del servicio
• Verificación Turnstile
• Botón "Aprobar y crear cuenta"

Para usuarios existentes:

• Muestra qué puede y no puede hacer el agente
• Verificación Turnstile
• Botón "Aprobar acceso" (no hace falta contraseña)

4. Cuenta creada

Qué ocurre internamente:

• Se crea la cuenta de usuario (si es nueva) o se enlaza (si existe)
• Se crea automáticamente un formulario por defecto
• Se genera una clave API
• El registro se marca como "approved"
• La clave API se almacena temporalmente para que el agente la recupere

5. El agente consulta el estado

Endpoint: GET /api/agent/status?registration_id=xxx

Mientras está pendiente:

{
  "status": "pending_verification",
  "message": "Waiting for operator approval"
}

Cuando está aprobado:

{
  "status": "approved",
  "api_key": "sr_live_abc123...",
  "form_url": "https://supportretriever.com/form/uuid",
  "form_id": "uuid",
  "message": "Registration approved. Store this API key securely - it will not be shown again."
}

Importante: La clave API se devuelve solo una vez. Guárdala de forma segura de inmediato.

Límite de tasa

Las peticiones de registro tienen límite de tasa:

• Por correo: Máximo 1 petición cada 24 horas
• Por IP: Máximo 5 peticiones por hora
• Global: Máximo 100 peticiones por hora

Si se supera el límite, recibirás un estado 429 con mensaje de error.

Caducidad del token

Los tokens de verificación caducan a las 24 horas. Si el operador no aprueba en 24 horas:

• El token deja de ser válido
• El estado del registro pasa a "expired"
• El agente recibe estado "expired" al consultar

Valores de estado

Manejo de errores

Formularioato de correo inválido

{
  "error": "Invalid email format"
}

Correo desechable

{
  "error": "Disposable email addresses are not allowed"
}

Límite de tasa superado

{
  "error": "Rate limit exceeded: max 1 request per email per 24 hours"
}

Registro no encontrado

{
  "error": "Registration not found"
}

Funciones de seguridad

• Prevención de enumeración de correos: Mismo formato de respuesta aunque el correo exista o no
• Límite de tasa: Evita abuso y bombardeo de correos
• Caducidad del token: Ventana de 24 horas para aprobar
• Verificación Turnstile: Protección anti-bots en la página de aprobación
• Clave API de un solo uso: La clave se muestra solo una vez y luego se borra

Temas relacionados

• Empezar
• Códigos de error
• Personalización del formulario