Saltar al contenido principal

Cambiar Código de Referido

Permite al usuario autenticado cambiar su código de referido a uno personalizado, validando formato, unicidad y frecuencia de cambio.

PATCH/auth/account/code/referral

Actualiza el código de referido del usuario autenticado con un valor personalizado

Contexto de Uso​

Este endpoint permite a un usuario autenticado personalizar su código de referido, que otros usuarios pueden utilizar al registrarse.

  • El código debe ser único en todo el sistema
  • Debe cumplir un formato específico
  • Solo se puede cambiar cada cierto tiempo (rate limit, por ejemplo cada 30 días)
  • El nuevo código reemplaza al anterior y se mostrará en el perfil del usuario / sección de referidos

Autenticación requerida: JWT Token válido en el header Authorization: Bearer <token>

Autenticación​

Token de Acceso Requerido

Este endpoint requiere un JWT token válido en el header de autorización:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

El backend obtiene la identidad del usuario a partir del token, por lo que no es necesario enviar el ID de usuario en el body.

Body de la Petición​

Estructura del Body​

{
  "newCode": "mi_codigo_123"
}
CampoTipoRequeridoDescripción
newCodestringSíNuevo código de referido del usuario

Reglas del Código de Referido​

  • Longitud: mínimo 4 y máximo 16 caracteres

  • Caracteres permitidos:

    • Letras: a-z, A-Z
    • Números: 0-9
    • Guion bajo: _

  • No se permiten:

    • Espacios
    • Símbolos como -, !, @, #, etc.

Ejemplos válidos:

  • juan23
  • swap_bits
  • USER_2024
  • miCodigo123

Ejemplos inválidos:

  • aa → longitud menor a 4
  • esto-es-invalido → contiene -
  • mi codigo → contiene espacio
  • codigo! → contiene !

Si el formato es inválido, el backend devolverá un error de validación.

Comportamiento del Endpoint​

Internamente, el backend realiza:

  • Validación de formato del código (newCode)
  • Verifica que el código no esté ya en uso por otro usuario
  • Verifica que el usuario no haya cambiado su código recientemente (rate limit)
  • Actualiza el código de referido del usuario si todas las validaciones pasan

Los detalles de implementación (base de datos, servicios, etc.) están encapsulados en el backend y no son visibles desde el frontend.

Respuesta Exitosa​

Código de Referido Actualizado

Cuando el cambio es exitoso, el backend responde con:

{
  "code": 1024,
  "message": "Referral code changed successfully",
  "data": {
    "status": "success",
    "code": "mi_codigo_custom"
  }
}

El campo data.code contiene el código de referido final que quedó registrado (por ejemplo en minúsculas si el backend lo normaliza).

Errores Comunes​

Errores Típicos

A continuación se listan algunos errores que el frontend debe manejar:

1. 401 - Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized"
}
  • Token ausente o inválido
  • Token expirado

2. 4001 - Usuario No Encontrado

{
  "code": 4001,
  "message": "User not found"
}
  • El usuario asociado al token ya no existe en el sistema

3. 4018 - Código de Referido ya en Uso

{
  "code": 4018,
  "message": "Referral code already in use"
}
  • Otro usuario ya está usando ese código
  • El frontend debería mostrar un mensaje tipo: “Ese código ya está en uso, elige otro”

4. 4030 - Rate Limit / Cambio Reciente

{
  "code": 4030,
  "message": "Referral code was changed recently"
}
  • El usuario intentó cambiar su código antes del tiempo mínimo permitido (por ejemplo, dentro de los últimos 30 días)
  • El frontend puede mostrar algo como: “Solo puedes cambiar tu código de referido cada 30 días”

5. Error Genérico (500)

{
  "statusCode": 500,
  "message": "Internal server error"
}
  • Error inesperado del servidor
  • El frontend debería mostrar un mensaje genérico y opcionalmente permitir reintentar

Ejemplos de Uso​

cURL​

curl -X PATCH 'https://api.swapbits.co/auth/account/code/referral' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -d '{
    "newCode": "mi_codigo_123"
  }'

JavaScript (Fetch API)​

async function changeReferralCode(accessToken, newCode) {
  const response = await fetch('https://api.swapbits.co/auth/account/code/referral', {
    method: 'PATCH',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ newCode }),
  });

  const result = await response.json();

  if (response.ok && result.code === 1024) {
    console.log('Código actualizado:', result.data.code);
    return result.data.code;
  } else {
    throw new Error(result.message || 'Error al cambiar código de referido');
  }
}

TypeScript (Axios)​

import axios from 'axios';

interface ChangeReferralCodeResponse {
  code: number;
  message: string;
  data: {
    status: string;
    code: string;
  };
}

export async function changeReferralCode(
  accessToken: string,
  newCode: string,
): Promise<ChangeReferralCodeResponse> {
  const response = await axios.patch<ChangeReferralCodeResponse>(
    'https://api.swapbits.co/auth/account/code/referral',
    { newCode },
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
      },
    },
  );

  return response.data;
}

Recomendaciones para el Frontend​

  • Validar el formato básico del código en el cliente (longitud y caracteres) para evitar requests innecesarios.

  • Normalizar el valor antes de enviarlo (por ejemplo, recortar espacios y, si quieres, pasarlo a minúsculas para mostrarlo consistente).

  • Manejar explícitamente los códigos de error:

    • 4018 → mostrar “Código ya en uso”
    • 4030 → mostrar “Solo puedes cambiar tu código cada X días”

  • Actualizar en la UI el código de referido con el valor devuelto en data.code.

Enlaces Relacionados​