Crear Usuarios

Pruebas
Producción

Dominio: https://test-api-factura.edw-dev.com

Endpoint para crear nuevos usuarios en el sistema con roles y permisos específicos.

Información General

Método: POST
Endpoint: /api/v1/users/create
Autenticación: Requerida (Bearer Token)
Permisos: Administrador o usuario con permisos de gestión
Tipo de contenido: application/json

Headers Requeridos

Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}

Parámetros del Cuerpo

Parámetro	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del usuario
`lastname`	string	Sí	Apellido del usuario
`email`	string	Sí	Email del usuario (debe ser único)
`password`	string	Sí	Contraseña del usuario (mínimo 8 caracteres)
`account_id`	integer	Sí	ID de la cuenta a la que pertenece
`roles`	array	No	Array de roles del usuario
`accounts`	array	No	Array de cuentas asociadas

Validaciones

Email: Debe ser único en el sistema
Contraseña: Mínimo 8 caracteres
Account ID: Debe existir en el sistema
Roles: Deben ser roles válidos existentes

Ejemplos de Implementación

Crear Usuario Básico

Solicitud

{
    "name": "Juan",
    "lastname": "Pérez",
    "email": "[email protected]",
    "password": "contraseña123",
    "account_id": 1,
    "roles": ["user"],
    "accounts": [1, 2]
}

Respuesta Exitosa (201)

{
    "message": "Usuario creado exitosamente",
    "status": "OK",
    "payload": {
        "uuid": 123456789,
        "name": "Juan",
        "lastname": "Pérez",
        "email": "[email protected]",
        "account_id": 1,
        "status": "active",
        "created_at": "2025-01-17 10:30:00"
    }
}

Crear Usuario Administrador

Solicitud

{
    "name": "María",
    "lastname": "González",
    "email": "[email protected]",
    "password": "AdminPass2024!",
    "account_id": 1,
    "roles": ["admin", "manager"],
    "accounts": [1, 2, 3]
}

Respuesta Exitosa (201)

{
    "message": "Usuario creado exitosamente",
    "status": "OK",
    "payload": {
        "uuid": 987654321,
        "name": "María",
        "lastname": "González",
        "email": "[email protected]",
        "account_id": 1,
        "status": "active",
        "roles": [
            {
                "id": 1,
                "name": "admin",
                "description": "Administrador del sistema"
            },
            {
                "id": 2,
                "name": "manager",
                "description": "Gerente de cuenta"
            }
        ],
        "created_at": "2025-01-17 10:30:00"
    }
}

Ejemplos de Código

curl -X POST "https://dev-facturacion.e-dinky.test/api/v1/users/create" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "name": "Juan",
    "lastname": "Pérez",
    "email": "[email protected]",
    "password": "contraseña123",
    "account_id": 1,
    "roles": ["user"],
    "accounts": [1, 2]
  }'

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

$response = Http::withHeaders([
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->post('https://dev-facturacion.e-dinky.test/api/v1/users/create', [
    'name' => 'Juan',
    'lastname' => 'Pérez',
    'email' => '[email protected]',
    'password' => 'contraseña123',
    'account_id' => 1,
    'roles' => ['user'],
    'accounts' => [1, 2]
]);

if ($response->successful()) {
    $user = $response->json();
    echo "Usuario creado: " . $user['payload']['uuid'];
    echo "Email: " . $user['payload']['email'];
    echo "Estado: " . $user['payload']['status'];
} else {
    echo "Error: " . $response->body();
}

const axios = require('axios');

const createUser = async () => {
    const token = 'your-api-token';

    const config = {
        method: 'post',
        url: 'https://dev-facturacion.e-dinky.test/api/v1/users/create',
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': `Bearer ${token}`
        },
        data: {
            name: 'Juan',
            lastname: 'Pérez',
            email: '[email protected]',
            password: 'contraseña123',
            account_id: 1,
            roles: ['user'],
            accounts: [1, 2]
        }
    };

    try {
        const response = await axios(config);
        console.log('Usuario creado:', response.data.payload.uuid);
        console.log('Email:', response.data.payload.email);
        console.log('Estado:', response.data.payload.status);
        return response.data;
    } catch (error) {
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Uso
createUser()
    .then(result => console.log('Éxito:', result))
    .catch(error => console.error('Error:', error));

Tipos de Roles Disponibles

Rol	Descripción	Permisos Típicos
`admin`	Administrador del sistema	Acceso completo a todas las funciones
`manager`	Gerente de cuenta	Gestión de usuarios y documentos
`user`	Usuario estándar	Creación y consulta de documentos
`viewer`	Solo lectura	Consulta de documentos y reportes
`accountant`	Contador	Gestión contable y reportes

Códigos de Respuesta

Código	Descripción	Acción
`201`	Usuario creado exitosamente	Continuar con el flujo
`400`	Datos inválidos	Revisar formato de datos
`401`	Token inválido	Renovar autenticación
`403`	Sin permisos	Verificar permisos de usuario
`404`	Email ya existe	Usar email diferente
`422`	Error de validación	Corregir datos según errores
`500`	Error del servidor	Reintentar más tarde

Errores Comunes

Email Ya Registrado (404)

{
    "message": "El email ya está registrado",
    "status": "ERROR"
}

Solución: Usar un email diferente o verificar si el usuario ya existe.

Error de Validación (422)

{
    "message": "Los datos proporcionados no son válidos",
    "errors": {
        "email": [
            "El campo email es obligatorio"
        ],
        "password": [
            "La contraseña debe tener al menos 8 caracteres"
        ],
        "account_id": [
            "La cuenta especificada no existe"
        ]
    }
}

Soluciones:

Verificar que todos los campos requeridos estén presentes
Asegurar que la contraseña tenga al menos 8 caracteres
Confirmar que el account_id existe en el sistema
Validar formato del email

Sin Permisos (403)

{
    "message": "No tienes permisos para realizar esta acción",
    "status": "ERROR"
}

Solución: Verificar que el usuario autenticado tenga permisos de administrador o gestión de usuarios.

Mejores Prácticas

1. Validación de Datos

// Validar email antes de enviar
const validateEmail = (email) => {
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return emailRegex.test(email);
};

// Validar contraseña
const validatePassword = (password) => {
    return password.length >= 8 &&
           /[A-Z]/.test(password) &&
           /[a-z]/.test(password) &&
           /[0-9]/.test(password);
};

2. Manejo de Errores

// Manejar diferentes tipos de errores
try {
    $response = Http::post($url, $data);

    if ($response->status() === 404) {
        // Email ya existe
        return ['error' => 'Email ya registrado'];
    }

    if ($response->status() === 422) {
        // Errores de validación
        $errors = $response->json()['errors'];
        return ['validation_errors' => $errors];
    }

    return $response->json();
} catch (Exception $e) {
    Log::error('Error creando usuario: ' . $e->getMessage());
    throw $e;
}

3. Asignación de Roles

// Asignar roles según el tipo de usuario
const assignRolesByUserType = (userType) => {
    const roleMapping = {
        'admin': ['admin', 'manager', 'user'],
        'manager': ['manager', 'user'],
        'employee': ['user'],
        'viewer': ['viewer']
    };

    return roleMapping[userType] || ['user'];
};

4. Generación de Contraseñas Seguras

// Generar contraseña temporal segura
function generateSecurePassword($length = 12) {
    $characters = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*';
    $password = '';

    for ($i = 0; $i < $length; $i++) {
        $password .= $characters[random_int(0, strlen($characters) - 1)];
    }

    return $password;
}

Flujo Recomendado

Validar permisos del usuario autenticado
- Verificar que tenga rol de administrador
- Confirmar permisos de gestión de usuarios
Validar datos de entrada
- Verificar formato de email
- Validar fortaleza de contraseña
- Confirmar existencia de account_id
Verificar unicidad del email
- Consultar si el email ya existe
- Manejar caso de email duplicado
Crear usuario
- Enviar solicitud POST
- Manejar respuesta y errores
Procesar resultado
- Notificar al nuevo usuario
- Registrar en logs de auditoría
- Actualizar interfaz de usuario

Consideraciones de Seguridad

Contraseñas: Nunca almacenar contraseñas en texto plano
Tokens: Usar tokens con tiempo de expiración
Permisos: Verificar permisos antes de cada operación
Auditoría: Registrar todas las creaciones de usuarios
Validación: Validar todos los datos de entrada
Rate Limiting: Implementar límites de velocidad

Casos de Uso Específicos

1. Crear Usuario para Nueva Empresa

{
    "name": "Admin",
    "lastname": "Empresa",
    "email": "[email protected]",
    "password": "TempPass2024!",
    "account_id": 123,
    "roles": ["admin"],
    "accounts": [123]
}

2. Crear Usuario Empleado

{
    "name": "Carlos",
    "lastname": "Empleado",
    "email": "[email protected]",
    "password": "EmpleadoPass123",
    "account_id": 123,
    "roles": ["user"],
    "accounts": [123]
}

3. Crear Usuario Contador

{
    "name": "Ana",
    "lastname": "Contadora",
    "email": "[email protected]",
    "password": "ContadorPass456",
    "account_id": 123,
    "roles": ["accountant", "user"],
    "accounts": [123, 124]
}

Notas Importantes

👤 Usuario único: Cada email debe ser único en el sistema
🔐 Seguridad: Las contraseñas se encriptan automáticamente
📧 Notificaciones: El usuario recibe email de bienvenida
🏢 Cuentas múltiples: Un usuario puede pertenecer a varias cuentas
🎭 Roles múltiples: Un usuario puede tener varios roles
⚡ Activación: Los usuarios se crean en estado activo por defecto
📊 Auditoría: Todas las creaciones se registran en logs
🔄 Estados: Los usuarios pueden estar activos, inactivos o suspendidos
🚫 Eliminación: Los usuarios no se eliminan, se desactivan
📱 API: Endpoint disponible para integraciones externas