soft_usite/API_ADMIN_GUIA.md

API Admin — Guia de Implementacion

Stack: Laravel + MongoDB + Laravel Sanctum Prefijo base: /api/admin/* Seguridad: Bearer Token (Sanctum) + rol administrador

---

1. Archivos creados / modificados

Archivo	Descripcion
app/Http/Middleware/AdminApiMiddleware.php	Verifica rol=administrador. Retorna JSON 403 (sin redirect).
app/Http/Kernel.php	Registra alias admin.api
app/Http/Controllers/Api/Admin/UsuarioController.php	CRUD usuarios + activar/desactivar
app/Http/Controllers/Api/Admin/VcardController.php	Listar, ver, editar vcards; por usuario
app/Http/Controllers/Api/Admin/MembresiaController.php	Ver/activar/desactivar membresia + cambiar plan
app/Http/Controllers/Api/Admin/PagoController.php	Historial HealthPagos + transacciones wallet
app/Http/Controllers/Api/Admin/LogController.php	Log de movimientos global y por usuario
app/Http/Controllers/Api/Admin/MiniWebController.php	Miniwebs con usuario y vcard vinculada
routes/api.php	34 rutas nuevas bajo /api/admin/*

---

2. Implementar en otro proyecto

2.1 Requisitos previos

• Laravel >= 10
• mongodb/laravel-mongodb instalado
• laravel/sanctum configurado
• Modelo User con HasApiTokens y relacion rol() -> Rol
• Modelo Rol con campo nombre (valor "administrador")

2.2 Copiar estos archivos

app/Http/Middleware/AdminApiMiddleware.php
app/Http/Controllers/Api/Admin/UsuarioController.php
app/Http/Controllers/Api/Admin/VcardController.php
app/Http/Controllers/Api/Admin/MembresiaController.php
app/Http/Controllers/Api/Admin/PagoController.php
app/Http/Controllers/Api/Admin/LogController.php
app/Http/Controllers/Api/Admin/MiniWebController.php

2.3 Registrar middleware en app/Http/Kernel.php

protected $routeMiddleware = [
    // ... existentes ...
    'admin.api' => \App\Http\Middleware\AdminApiMiddleware::class,
];

2.4 Agregar rutas en routes/api.php

use App\Http\Controllers\Api\Admin\UsuarioController   as AdminUsuario;
use App\Http\Controllers\Api\Admin\VcardController     as AdminVcard;
use App\Http\Controllers\Api\Admin\MembresiaController as AdminMembresia;
use App\Http\Controllers\Api\Admin\PagoController      as AdminPago;
use App\Http\Controllers\Api\Admin\LogController       as AdminLog;
use App\Http\Controllers\Api\Admin\MiniWebController   as AdminMiniWeb;

Route::middleware(['auth:sanctum', 'admin.api'])->prefix('admin')->name('admin.')->group(function () {

    // Usuarios
    Route::get('usuarios',                         [AdminUsuario::class,  'index']);
    Route::get('usuarios/{id}',                    [AdminUsuario::class,  'show']);
    Route::put('usuarios/{id}',                    [AdminUsuario::class,  'update']);
    Route::post('usuarios/{id}/activar',           [AdminUsuario::class,  'activar']);
    Route::post('usuarios/{id}/desactivar',        [AdminUsuario::class,  'desactivar']);

    // VCards
    Route::get('vcards',                           [AdminVcard::class,    'index']);
    Route::get('vcards/{id}',                      [AdminVcard::class,    'show']);
    Route::put('vcards/{id}',                      [AdminVcard::class,    'update']);
    Route::get('usuarios/{userId}/vcards',         [AdminVcard::class,    'byUsuario']);

    // Membresias
    Route::get('planes',                                 [AdminMembresia::class, 'planes']);
    Route::get('usuarios/{id}/membresia',                [AdminMembresia::class, 'show']);
    Route::post('usuarios/{id}/activar-membresia',       [AdminMembresia::class, 'activar']);
    Route::post('usuarios/{id}/desactivar-membresia',    [AdminMembresia::class, 'desactivar']);
    Route::post('usuarios/{id}/cambiar-plan',            [AdminMembresia::class, 'cambiarPlan']);

    // Pagos
    Route::get('pagos',                            [AdminPago::class,     'index']);
    Route::get('transacciones',                    [AdminPago::class,     'transacciones']);
    Route::get('usuarios/{userId}/pagos',          [AdminPago::class,     'byUsuario']);
    Route::get('usuarios/{userId}/transacciones',  [AdminPago::class,     'transaccionesByUsuario']);

    // Logs
    Route::get('logs',                             [AdminLog::class,      'index']);
    Route::get('usuarios/{userId}/logs',           [AdminLog::class,      'byUsuario']);

    // MiniWebs
    Route::get('miniwebs',                         [AdminMiniWeb::class,  'index']);
    Route::get('miniwebs/{id}',                    [AdminMiniWeb::class,  'show']);
    Route::get('usuarios/{userId}/miniwebs',       [AdminMiniWeb::class,  'byUsuario']);
});

---

3. Flujo de autenticacion

Login

POST /api/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "secret"
}

Respuesta:

{
  "access_token": "1|abc123...",
  "token_type": "Bearer",
  "user": { ... }
}

Usar token en cada peticion

Authorization: Bearer 1|abc123...

Logout

POST /api/logout
Authorization: Bearer 1|abc123...

---

4. Referencia de endpoints

Usuarios /api/admin/usuarios

Metodo	Ruta	Descripcion	Query params
GET	/api/admin/usuarios	Lista paginada	search, estado, plan_id, per_page
GET	/api/admin/usuarios/{id}	Detalle: plan, vcards, wallet, perfil	—
PUT	/api/admin/usuarios/{id}	Edita name, email, rol_id, plan_id	—
POST	/api/admin/usuarios/{id}/activar	Activa cuenta (estado=true)	—
POST	/api/admin/usuarios/{id}/desactivar	Desactiva cuenta (estado=false)	—

Ejemplo PUT:

{ "name": "Juan Garcia", "email": "juan@empresa.com", "plan_id": "664abc123" }

---

VCards /api/admin/vcards

Metodo	Ruta	Descripcion	Query params
GET	/api/admin/vcards	Lista paginada	search, estado, user_id, per_page
GET	/api/admin/vcards/{id}	Detalle con usuario	—
PUT	/api/admin/vcards/{id}	Edita datos basicos	—
GET	/api/admin/usuarios/{userId}/vcards	Vcards de un usuario	—

Campos editables: nombre, cargo, descripcion, telefono, whatsapp, email, empresa, direccion, website, pais, ciudad, estado, privacidad, es_borrador

---

Membresias

Metodo	Ruta	Descripcion	Body
GET	/api/admin/planes	Lista planes activos	—
GET	/api/admin/usuarios/{id}/membresia	Estado de membresia	—
POST	/api/admin/usuarios/{id}/activar-membresia	Activa/renueva	{ "anual": true, "dias": 365 }
POST	/api/admin/usuarios/{id}/cambiar-plan	Cambia plan	{ "plan_id": "abc", "anual": false }
POST	/api/admin/usuarios/{id}/desactivar-membresia	Desactiva	—

Logica activar-membresia:

• Si ya tiene membresia vigente, los dias se SUMAN (no se pisa la fecha).
• anual:true = +365 dias. anual:false = +30 dias (o los dias que se indiquen).

---

Pagos

Metodo	Ruta	Descripcion	Query params
GET	/api/admin/pagos	Historial global HealthPagos	user_id, estado, moneda, desde, hasta, per_page
GET	/api/admin/transacciones	Transacciones wallet global	type, status, per_page
GET	/api/admin/usuarios/{id}/pagos	Pagos de un usuario + total pagado	—
GET	/api/admin/usuarios/{id}/transacciones	Wallet de un usuario	—

Valores estado (HealthPago): pendiente, completado, fallido Valores type (Transaction): deposit, withdraw, transfer_in, transfer_out, purchase, adjustment Valores status (Transaction): pending, completed, failed

---

Logs

Metodo	Ruta	Descripcion	Query params
GET	/api/admin/logs	Log global de movimientos	user_id, type, search, desde, hasta, per_page
GET	/api/admin/usuarios/{id}/logs	Logs de un usuario	—

Valores type: create, edit, delete, delete cuenta

---

MiniWebs

Metodo	Ruta	Descripcion	Query params
GET	/api/admin/miniwebs	Lista paginada	search, user_id, per_page
GET	/api/admin/miniwebs/{id}	Detalle con usuario + vcard vinculada	—
GET	/api/admin/usuarios/{id}/miniwebs	Miniwebs de un usuario	—

---

5. Respuestas de error

HTTP	Cuando
401	Token ausente o invalido
403	Autenticado pero sin rol administrador
404	Recurso no encontrado
422	Validacion fallida

Ejemplo 403:

{
  "error": "Acceso denegado. Se requieren privilegios de administrador.",
  "code": 403
}

---

6. Modelos requeridos

Modelo	Coleccion MongoDB	Relaciones usadas
User	users	rol, plan, perfil, wallet, vcards, setup
Vcard	vcard	user
Planes	planes	tarifas
HealthPago	health_pagos	—
Transaction	transactions	wallet
Wallet	wallets	user
Log	log	user
MiniWeb	miniwebs	user, vcard
Rol	rol	—

---

7. Paginacion

Todos los listados retornan estructura estandar de Laravel:

{
  "current_page": 1,
  "data": [ ... ],
  "per_page": 20,
  "total": 150,
  "last_page": 8,
  "next_page_url": "https://...",
  "prev_page_url": null
}

Maximo per_page: 100

---

8. Prueba rapida con curl

# 1. Login y guardar token
TOKEN=$(curl -s -X POST https://tudominio.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"secret"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")

# 2. Listar usuarios
curl https://tudominio.com/api/admin/usuarios \
  -H "Authorization: Bearer $TOKEN"

# 3. Vcards de un usuario
curl https://tudominio.com/api/admin/usuarios/USER_ID/vcards \
  -H "Authorization: Bearer $TOKEN"

# 4. Activar membresia anual
curl -X POST https://tudominio.com/api/admin/usuarios/USER_ID/activar-membresia \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"anual": true}'

# 5. Cambiar plan
curl -X POST https://tudominio.com/api/admin/usuarios/USER_ID/cambiar-plan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "PLAN_ID"}'

# 6. Historial de pagos con filtros
curl "https://tudominio.com/api/admin/pagos?estado=completado&desde=2026-01-01&per_page=50" \
  -H "Authorization: Bearer $TOKEN"

# 7. Logs de un usuario
curl https://tudominio.com/api/admin/usuarios/USER_ID/logs \
  -H "Authorization: Bearer $TOKEN"

# 8. MiniWebs con busqueda
curl "https://tudominio.com/api/admin/miniwebs?search=empresa" \
  -H "Authorization: Bearer $TOKEN"