Consultar Usuarios

Pruebas
Producción

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

Endpoints para consultar información de usuarios, incluyendo listados, búsquedas y consultas específicas.

Endpoints Disponibles

GET /api/v1/users - Listar todos los usuarios
GET /api/v1/users/:id - Obtener usuario específico
GET /api/v1/users/my/information - Información del usuario autenticado

GET /api/v1/users

Obtiene una lista paginada de todos los usuarios del sistema.

Información General

Método: GET
Endpoint: /api/v1/users
Autenticación: Requerida (Bearer Token)
Permisos: Administrador o usuario con permisos de consulta
Paginación: Sí (15 elementos por página por defecto)

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
`page`	integer	No	Número de página (por defecto: 1)
`per_page`	integer	No	Elementos por página (por defecto: 15)
`filters`	string	No	Filtros avanzados en formato JSON

Filtros Disponibles

Campo	Descripción	Condiciones	Ejemplo
`name`	Nombre del usuario	`eq`, `sw`, `ew`, `ct`	`{"field":"name","condition":"sw","value":"Juan"}`
`last_name`	Apellido del usuario	`eq`, `sw`, `ew`, `ct`	`{"field":"last_name","condition":"ew","value":"Pérez"}`
`email`	Email del usuario	`eq`, `sw`, `ew`, `ct`	`{"field":"email","condition":"ew","value":"@gmail.com"}`
`created_at`	Fecha de creación	`eq`, `le`, `ge`, `bt`	`{"field":"created_at","condition":"le","value":"2025-01-17"}`
`updated_at`	Fecha de actualización	`eq`, `le`, `ge`, `bt`	`{"field":"updated_at","condition":"ge","value":"2024-01-01"}`
`status`	Estado del usuario	`eq`	`{"field":"status","condition":"eq","value":"active"}`

Ejemplos de Implementación

Listar Usuarios Básico

GET /api/v1/users

Respuesta Exitosa (200)

{
    "message": "Lista de usuarios",
    "status": "OK",
    "payload": {
        "items": [
            {
                "uuid": 123456789,
                "name": "Juan",
                "last_name": "Pérez",
                "email": "[email protected]",
                "status": "active",
                "created_at": "2025-01-17 10:30:00"
            },
            {
                "uuid": 987654321,
                "name": "María",
                "last_name": "González",
                "email": "[email protected]",
                "status": "active",
                "created_at": "2025-01-16 15:20:00"
            }
        ],
        "count": 2,
        "current_page": 1,
        "per_page": 15,
        "total_pages": 1
    }
}

Listar con Filtros Avanzados

GET /api/v1/users?filters=[{"field":"created_at","condition":"le","value":"2025-01-17"},{"field":"email","condition":"sw","value":"admin"}]

Listar con Paginación

GET /api/v1/users?page=2&per_page=10

GET /api/v1/users/:id

Obtiene la información detallada de un usuario específico.

Información General

Método: GET
Endpoint: /api/v1/users/:id
Autenticación: Requerida (Bearer Token)
Permisos: Administrador o el mismo usuario

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Parámetros de URL

Parámetro	Tipo	Requerido	Descripción
`id`	integer	Sí	ID del usuario a consultar

Ejemplo de Implementación

Solicitud

GET /api/v1/users/123456789

Respuesta Exitosa (201)

{
    "message": "Usuario encontrado",
    "status": "OK",
    "payload": {
        "uuid": 123456789,
        "name": "Juan",
        "last_name": "Pérez",
        "email": "[email protected]",
        "phone": "+593987654321",
        "status": "active",
        "created_at": "2025-01-17 10:30:00"
    }
}

Usuario No Encontrado (404)

{
    "message": "Usuario no encontrado",
    "status": "ERROR"
}

GET /api/v1/users/my/information

Obtiene la información completa del usuario autenticado, incluyendo empresa y permisos.

Información General

Método: GET
Endpoint: /api/v1/users/my/information
Autenticación: Requerida (Bearer Token)
Permisos: Usuario autenticado

Headers Requeridos

Accept: application/json
Authorization: Bearer {token}

Ejemplo de Implementación

Solicitud

GET /api/v1/users/my/information

Respuesta Exitosa (201)

{
    "message": "Información del usuario",
    "status": "OK",
    "payload": {
        "user": {
            "uuid": 123456789,
            "name": "Juan",
            "last_name": "Pérez",
            "email": "[email protected]",
            "phone": "+593987654321",
            "status": "active"
        },
        "company": {
            "uuid": 987654321,
            "name": "Empresa Ejemplo",
            "ruc": "0123456789001",
            "address": "Dirección de la empresa"
        },
        "management": {
            "uuid": 555666777,
            "permissions": ["create_documents", "view_reports"]
        }
    }
}

Ejemplos de Código

# Listar usuarios
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/users" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

# Obtener usuario específico
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/users/123456789" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

# Mi información
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/users/my/information" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

# Con filtros
curl -X GET "https://dev-facturacion.e-dinky.test/api/v1/users?filters=[{\"field\":\"email\",\"condition\":\"ew\",\"value\":\"@gmail.com\"}]" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer {token}"

<?php

use Illuminate\Support\Facades\Http;

$token = 'your-api-token';

// Listar usuarios
$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get('https://dev-facturacion.e-dinky.test/api/v1/users');

if ($response->successful()) {
    $users = $response->json();
    foreach ($users['payload']['items'] as $user) {
        echo "Usuario: " . $user['name'] . " " . $user['last_name'] . "\n";
        echo "Email: " . $user['email'] . "\n";
        echo "Estado: " . $user['status'] . "\n\n";
    }
}

// Obtener usuario específico
$userId = 123456789;
$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get("https://dev-facturacion.e-dinky.test/api/v1/users/{$userId}");

if ($response->successful()) {
    $user = $response->json()['payload'];
    echo "Usuario encontrado: " . $user['name'] . " " . $user['last_name'];
} else {
    echo "Usuario no encontrado";
}

// Mi información
$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get('https://dev-facturacion.e-dinky.test/api/v1/users/my/information');

if ($response->successful()) {
    $info = $response->json()['payload'];
    echo "Mi nombre: " . $info['user']['name'];
    echo "Mi empresa: " . $info['company']['name'];
    echo "Mis permisos: " . implode(', ', $info['management']['permissions']);
}

// Con filtros
$filters = [
    ['field' => 'email', 'condition' => 'ew', 'value' => '@gmail.com'],
    ['field' => 'status', 'condition' => 'eq', 'value' => 'active']
];

$response = Http::withHeaders([
    'Accept' => 'application/json',
    'Authorization' => 'Bearer ' . $token,
])->get('https://dev-facturacion.e-dinky.test/api/v1/users', [
    'filters' => json_encode($filters),
    'page' => 1,
    'per_page' => 20
]);

if ($response->successful()) {
    $users = $response->json();
    echo "Usuarios encontrados: " . $users['payload']['count'];
}

const axios = require('axios');

const token = 'your-api-token';

const headers = {
    'Accept': 'application/json',
    'Authorization': `Bearer ${token}`
};

// Listar usuarios
const getUsers = async (page = 1, perPage = 15) => {
    try {
        const response = await axios.get('https://dev-facturacion.e-dinky.test/api/v1/users', {
            headers,
            params: { page, per_page: perPage }
        });

        console.log('Usuarios encontrados:', response.data.payload.count);
        response.data.payload.items.forEach(user => {
            console.log(`${user.name} ${user.last_name} - ${user.email}`);
        });

        return response.data;
    } catch (error) {
        console.error('Error obteniendo usuarios:', error.response?.data || error.message);
        throw error;
    }
};

// Obtener usuario específico
const getUserById = async (userId) => {
    try {
        const response = await axios.get(`https://dev-facturacion.e-dinky.test/api/v1/users/${userId}`, {
            headers
        });

        console.log('Usuario encontrado:', response.data.payload.name);
        return response.data.payload;
    } catch (error) {
        if (error.response?.status === 404) {
            console.log('Usuario no encontrado');
            return null;
        }
        console.error('Error:', error.response?.data || error.message);
        throw error;
    }
};

// Mi información
const getMyInformation = async () => {
    try {
        const response = await axios.get('https://dev-facturacion.e-dinky.test/api/v1/users/my/information', {
            headers
        });

        const { user, company, management } = response.data.payload;
        console.log('Mi información:');
        console.log('Nombre:', user.name, user.last_name);
        console.log('Empresa:', company.name);
        console.log('Permisos:', management.permissions.join(', '));

        return response.data.payload;
    } catch (error) {
        console.error('Error obteniendo mi información:', error.response?.data || error.message);
        throw error;
    }
};

// Buscar con filtros
const searchUsers = async (filters) => {
    try {
        const response = await axios.get('https://dev-facturacion.e-dinky.test/api/v1/users', {
            headers,
            params: {
                filters: JSON.stringify(filters)
            }
        });

        console.log('Usuarios filtrados:', response.data.payload.count);
        return response.data.payload.items;
    } catch (error) {
        console.error('Error en búsqueda:', error.response?.data || error.message);
        throw error;
    }
};

// Ejemplos de uso
(async () => {
    try {
        // Listar usuarios
        await getUsers(1, 10);

        // Obtener usuario específico
        await getUserById(123456789);

        // Mi información
        await getMyInformation();

        // Buscar usuarios con Gmail
        const gmailUsers = await searchUsers([
            { field: 'email', condition: 'ew', value: '@gmail.com' }
        ]);
        console.log('Usuarios con Gmail:', gmailUsers.length);

    } catch (error) {
        console.error('Error en operaciones:', error);
    }
})();

Sistema de Filtros Avanzados

Condiciones Disponibles

Condición	Descripción	Ejemplo
`eq`	Igual a	`{"field":"status","condition":"eq","value":"active"}`
`sw`	Comienza con	`{"field":"name","condition":"sw","value":"Juan"}`
`ew`	Termina con	`{"field":"email","condition":"ew","value":"@gmail.com"}`
`ct`	Contiene	`{"field":"name","condition":"ct","value":"Car"}`
`le`	Menor o igual	`{"field":"created_at","condition":"le","value":"2025-01-17"}`
`ge`	Mayor o igual	`{"field":"created_at","condition":"ge","value":"2024-01-01"}`
`bt`	Entre valores	`{"field":"created_at","condition":"bt","value":["2024-01-01","2025-01-17"]}`

Ejemplos de Filtros Complejos

Usuarios Activos Creados Este Mes

[
    {"field":"status","condition":"eq","value":"active"},
    {"field":"created_at","condition":"ge","value":"2025-01-01"}
]

Usuarios con Email Corporativo

[
    {"field":"email","condition":"ew","value":"@empresa.com"}
]

Usuarios por Rango de Fechas

[
    {"field":"created_at","condition":"bt","value":["2024-01-01","2024-12-31"]}
]

Códigos de Respuesta

Código	Descripción	Acción
`200`	Consulta exitosa	Procesar datos
`201`	Usuario encontrado	Mostrar información
`400`	Parámetros inválidos	Revisar filtros
`401`	Token inválido	Renovar autenticación
`403`	Sin permisos	Verificar permisos
`404`	Usuario no encontrado	Verificar ID
`422`	Filtros inválidos	Corregir formato
`500`	Error del servidor	Reintentar más tarde

Mejores Prácticas

1. Paginación Eficiente

// Implementar paginación progresiva
const loadUsersPage = async (page, perPage = 15) => {
    const response = await getUsers(page, perPage);
    const { items, current_page, total_pages } = response.payload;

    console.log(`Página ${current_page} de ${total_pages}`);

    // Cargar siguiente página si existe
    if (current_page < total_pages) {
        const nextPage = await loadUsersPage(page + 1, perPage);
        return [...items, ...nextPage];
    }

    return items;
};

2. Cache de Consultas

// Implementar cache para consultas frecuentes
class UserService {
    private $cache;

    public function getUsers($filters = [], $page = 1) {
        $cacheKey = 'users_' . md5(json_encode($filters) . $page);

        if ($this->cache->has($cacheKey)) {
            return $this->cache->get($cacheKey);
        }

        $users = $this->apiCall('/api/v1/users', $filters, $page);
        $this->cache->put($cacheKey, $users, 300); // 5 minutos

        return $users;
    }
}

3. Manejo de Errores

// Manejo robusto de errores
const safeGetUser = async (userId) => {
    try {
        const user = await getUserById(userId);
        return { success: true, data: user };
    } catch (error) {
        if (error.response?.status === 404) {
            return { success: false, error: 'Usuario no encontrado' };
        }
        if (error.response?.status === 403) {
            return { success: false, error: 'Sin permisos para ver este usuario' };
        }
        return { success: false, error: 'Error del servidor' };
    }
};

4. Búsqueda Inteligente

// Implementar búsqueda inteligente
function smartUserSearch($query) {
    $filters = [];

    // Si parece un email
    if (filter_var($query, FILTER_VALIDATE_EMAIL)) {
        $filters[] = ['field' => 'email', 'condition' => 'eq', 'value' => $query];
    }
    // Si es numérico, buscar por ID
    elseif (is_numeric($query)) {
        return getUserById($query);
    }
    // Buscar en nombre y apellido
    else {
        $filters[] = ['field' => 'name', 'condition' => 'ct', 'value' => $query];
        $filters[] = ['field' => 'last_name', 'condition' => 'ct', 'value' => $query];
    }

    return searchUsers($filters);
}

Casos de Uso Específicos

1. Dashboard de Administración

// Obtener estadísticas de usuarios
const getUserStats = async () => {
    const [activeUsers, inactiveUsers, recentUsers] = await Promise.all([
        searchUsers([{field: 'status', condition: 'eq', value: 'active'}]),
        searchUsers([{field: 'status', condition: 'eq', value: 'inactive'}]),
        searchUsers([{field: 'created_at', condition: 'ge', value: '2025-01-01'}])
    ]);

    return {
        active: activeUsers.length,
        inactive: inactiveUsers.length,
        recent: recentUsers.length
    };
};

2. Búsqueda de Usuarios por Empresa

// Buscar usuarios de una empresa específica
function getUsersByCompany($companyId) {
    $filters = [
        ['field' => 'account_id', 'condition' => 'eq', 'value' => $companyId],
        ['field' => 'status', 'condition' => 'eq', 'value' => 'active']
    ];

    return searchUsers($filters);
}

3. Exportar Lista de Usuarios

// Exportar todos los usuarios a CSV
const exportUsersToCSV = async () => {
    let allUsers = [];
    let page = 1;
    let hasMore = true;

    while (hasMore) {
        const response = await getUsers(page, 100);
        allUsers = [...allUsers, ...response.payload.items];
        hasMore = page < response.payload.total_pages;
        page++;
    }

    const csv = allUsers.map(user =>
        `${user.name},${user.last_name},${user.email},${user.status}`
    ).join('\n');

    return 'Nombre,Apellido,Email,Estado\n' + csv;
};

Notas Importantes

📄 Paginación: Todos los listados están paginados por defecto
🔍 Filtros: Sistema avanzado de filtros disponible
🔐 Permisos: Verificar permisos antes de consultar
⚡ Performance: Usar paginación para grandes volúmenes
💾 Cache: Implementar cache para consultas frecuentes
🔄 Tiempo real: Los datos se actualizan en tiempo real
📊 Estadísticas: Usar para generar reportes y dashboards
🚫 Privacidad: Respetar permisos de acceso a información
📱 Responsive: Adaptar paginación según dispositivo
🔗 Enlaces: Usar IDs para navegación entre usuarios