feat(staff): expose scanner attempt history

ShopIt_API_Postman_Collection.json

@@ -1249,7 +1249,7 @@
                     "name": "Ticket",
                     "item": [
                         {
-                            "name": "List Ticket",
+                            "name": "List Scan Attempt",
                             "request": {
                                 "method": "GET",
                                 "header": [
@@ -5998,9 +5998,9 @@
                                         "type": "text"
                                     }
                                 ],
-                                "description": "Ruta Laravel: `GET /api/v1/scanner/tickets`\n\nControlador: `App\\Domains\\Ticket\\Controllers\\Scanner\\TicketController@index`\n\nRequiere autenticación Sanctum.",
+                                "description": "Ruta Laravel: `GET /api/v1/scanner/attempts`\n\nControlador: `App\\Domains\\Ticket\\Controllers\\Scanner\\ScanAttemptController`\n\nRequiere autenticación Sanctum.",
                                 "url": {
-                                    "raw": "{{base_url}}/api/v1/scanner/tickets?page=1&per_page=20",
+                                    "raw": "{{base_url}}/api/v1/scanner/attempts?page=1&per_page=20",
                                     "host": [
                                         "{{base_url}}"
                                     ],
@@ -6008,7 +6008,7 @@
                                         "api",
                                         "v1",
                                         "scanner",
-                                        "tickets"
+                                        "attempts"
                                     ],
                                     "query": [
                                         {
@@ -6086,11 +6086,16 @@
                                         "key": "Accept",
                                         "value": "application/json",
                                         "type": "text"
+                                    },
+                                    {
+                                        "key": "Content-Type",
+                                        "value": "application/json",
+                                        "type": "text"
                                     }
                                 ],
-                                "description": "Ruta Laravel: `POST /api/v1/scanner/tickets/{ticketUuid}/scan`\n\nControlador: `App\\Domains\\Ticket\\Controllers\\Scanner\\TicketController@scan`\n\nRequiere autenticación Sanctum.",
+                                "description": "Ruta Laravel: `POST /api/v1/scanner/tickets/scan`\n\nControlador: `App\\Domains\\Ticket\\Controllers\\Scanner\\TicketController@scan`\n\nRequiere autenticación Sanctum.",
                                 "url": {
-                                    "raw": "{{base_url}}/api/v1/scanner/tickets/{{ticket_uuid}}/scan",
+                                    "raw": "{{base_url}}/api/v1/scanner/tickets/scan",
                                     "host": [
                                         "{{base_url}}"
                                     ],
@@ -6099,10 +6104,18 @@
                                         "v1",
                                         "scanner",
                                         "tickets",
-                                        "{{ticket_uuid}}",
                                         "scan"
                                     ]
                                 },
+                                "body": {
+                                    "mode": "raw",
+                                    "raw": "{\n    \"data\": \"{{ticket_uuid}}\"\n}",
+                                    "options": {
+                                        "raw": {
+                                            "language": "json"
+                                        }
+                                    }
+                                },
                                 "auth": {
                                     "type": "bearer",
                                     "bearer": [

app/Domains/Auth/Models/User.php

@@ -6,6 +6,7 @@ use App\Domains\Authorization\Enums\RoleCode;
 use App\Domains\Authorization\Models\Role;
 use App\Domains\Catalog\Models\Category;
 use App\Domains\Tenant\Models\Tenant;
+use App\Domains\Ticket\Models\ScanAttempt;
 use Database\Factories\UserFactory;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Attributes\Hidden;
@@ -46,6 +47,12 @@ class User extends Authenticatable
         return $this->hasMany(LoginAttempt::class);
     }
 
+    /** @return HasMany<ScanAttempt, $this> */
+    public function scanAttempts(): HasMany
+    {
+        return $this->hasMany(ScanAttempt::class, 'scanner_user_id');
+    }
+
     /**
      * @return BelongsTo<Role, $this>
      */

app/Domains/Auth/Resources/UserResource.php

@@ -24,6 +24,11 @@ class UserResource extends JsonResource
             'telefono' => $this->telefono,
             'rol_codigo' => $this->rol_codigo,
             'tenant_codigo' => $this->tenant_codigo,
+            'categories' => $this->whenLoaded('scanCategories', fn () => $this->scanCategories
+                ->map(fn ($category) => [
+                    'id' => $category->id,
+                    'nombre' => $category->nombre,
+                ])->values()),
         ];
     }
 }

app/Domains/Auth/Services/ScannerContextService.php

@@ -19,6 +19,16 @@ class ScannerContextService
 
         $user->setRelation('tenant', $tenant);
 
+        if ($tenant->requiresScannerCategoryValidation()) {
+            $categories = $user->scanCategories()
+                ->orderBy('nombre')
+                ->get();
+
+            if ($categories->isNotEmpty()) {
+                $user->setRelation('scanCategories', $categories);
+            }
+        }
+
         return $user;
     }
 }

app/Domains/Staff/Controllers/AdminAppStaffController.php

@@ -6,6 +6,9 @@ use App\Domains\Staff\Requests\StoreStaffRequest;
 use App\Domains\Staff\Requests\UpdateStaffRequest;
 use App\Domains\Staff\Resources\StaffResource;
 use App\Domains\Staff\Services\StaffService;
+use App\Domains\Ticket\Requests\ScanAttemptIndexRequest;
+use App\Domains\Ticket\Resources\Scanner\ScanAttemptResource;
+use App\Domains\Ticket\Services\ScannerTicketService;
 use App\Http\Controllers\Controller;
 use Illuminate\Http\Request;
 use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
@@ -13,7 +16,10 @@ use Symfony\Component\HttpFoundation\Response;
 
 class AdminAppStaffController extends Controller
 {
-    public function __construct(private readonly StaffService $staffService) {}
+    public function __construct(
+        private readonly StaffService $staffService,
+        private readonly ScannerTicketService $scannerTicketService,
+    ) {}
 
     public function index(Request $request): AnonymousResourceCollection
     {
@@ -46,4 +52,18 @@ class AdminAppStaffController extends Controller
 
         return response()->noContent();
     }
+
+    public function scanAttempts(
+        ScanAttemptIndexRequest $request,
+        int $staff,
+    ): AnonymousResourceCollection {
+        $scanner = $this->staffService->find(
+            $request->user()->tenant()->firstOrFail(),
+            $staff,
+        );
+
+        return ScanAttemptResource::collection(
+            $this->scannerTicketService->attemptsByStaff($scanner, $request->validated())
+        );
+    }
 }

app/Domains/Staff/routes/api.php

@@ -6,5 +6,6 @@ use Illuminate\Support\Facades\Route;
 Route::prefix('v1/adminapp/tenant')
     ->middleware(['auth:sanctum', 'adminapp.tenant'])
     ->group(function (): void {
+        Route::get('staff/{staff}/scan-attempts', [AdminAppStaffController::class, 'scanAttempts']);
         Route::apiResource('staff', AdminAppStaffController::class)->except('show');
     });

app/Domains/Tenant/Models/Tenant.php

@@ -12,6 +12,7 @@ use App\Domains\Event\Models\EventDate;
 use App\Domains\Menu\Models\Menu;
 use App\Domains\Menu\Models\TenantMenu;
 use App\Domains\Tenant\Enums\CartEditingPolicy;
+use App\Domains\Ticket\Models\ScanAttempt;
 use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
@@ -195,6 +196,12 @@ class Tenant extends Model
         return $this->hasMany(Category::class, 'tenant_code', 'codigo');
     }
 
+    /** @return HasMany<ScanAttempt, $this> */
+    public function scanAttempts(): HasMany
+    {
+        return $this->hasMany(ScanAttempt::class, 'tenant_code', 'codigo');
+    }
+
     /**
      * @return BelongsToMany<SocialMedia, $this>
      */

app/Domains/Ticket/Controllers/Scanner/ScanAttemptController.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Domains\Ticket\Controllers\Scanner;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Ticket\Requests\ScanAttemptIndexRequest;
+use App\Domains\Ticket\Resources\Scanner\ScanAttemptResource;
+use App\Domains\Ticket\Resources\Scanner\ScannerScanResultResource;
+use App\Domains\Ticket\Services\ScannerTicketService;
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+
+class ScanAttemptController extends Controller
+{
+    public function __construct(private readonly ScannerTicketService $ticketService) {}
+
+    public function __invoke(ScanAttemptIndexRequest $request): AnonymousResourceCollection
+    {
+        /** @var User $scanner */
+        $scanner = $request->user();
+
+        return ScanAttemptResource::collection(
+            $this->ticketService->attemptsBy($scanner, $request->validated())
+        );
+    }
+
+    public function show(Request $request, int $scanAttempt): ScannerScanResultResource
+    {
+        /** @var User $scanner */
+        $scanner = $request->user();
+
+        return ScannerScanResultResource::make(
+            $this->ticketService->scanAttemptDetail($scanner, $scanAttempt)
+        );
+    }
+}

app/Domains/Ticket/Controllers/Scanner/TicketController.php

@@ -3,28 +3,18 @@
 namespace App\Domains\Ticket\Controllers\Scanner;
 
 use App\Domains\Auth\Models\User;
-use App\Domains\Ticket\Requests\ScannerTicketIndexRequest;
+use App\Domains\Ticket\Resources\Scanner\ScannerScanResultResource;
-use App\Domains\Ticket\Resources\Scanner\ScannedTicketResource;
 use App\Domains\Ticket\Resources\TicketResource;
 use App\Domains\Ticket\Services\ScannerTicketService;
 use App\Http\Controllers\Controller;
+use Illuminate\Http\JsonResponse;
 use Illuminate\Http\Request;
-use Illuminate\Http\Resources\Json\AnonymousResourceCollection;
+use Symfony\Component\HttpFoundation\Response;
 
 class TicketController extends Controller
 {
     public function __construct(private readonly ScannerTicketService $ticketService) {}
 
-    public function index(ScannerTicketIndexRequest $request): AnonymousResourceCollection
-    {
-        /** @var User $scanner */
-        $scanner = $request->user();
-
-        return ScannedTicketResource::collection(
-            $this->ticketService->scannedBy($scanner, $request->validated())
-        );
-    }
-
     public function show(Request $request, string $ticketUuid): TicketResource
     {
         /** @var User $scanner */
@@ -35,13 +25,13 @@ class TicketController extends Controller
         );
     }
 
-    public function scan(Request $request, string $ticketUuid): TicketResource
+    public function scan(Request $request): JsonResponse
     {
         /** @var User $scanner */
         $scanner = $request->user();
 
-        return TicketResource::make(
+        return ScannerScanResultResource::make(
-            $this->ticketService->scan($scanner, $ticketUuid)
+            $this->ticketService->scan($scanner, $request->input('data'))
-        );
+        )->response()->setStatusCode(Response::HTTP_OK);
     }
 }

app/Domains/Ticket/Enums/ScanAttemptResult.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace App\Domains\Ticket\Enums;
+
+enum ScanAttemptResult: string
+{
+    case Processing = 'processing';
+    case Accepted = 'accepted';
+    case InvalidQr = 'invalid_qr';
+    case TicketNotFound = 'ticket_not_found';
+    case CategoryForbidden = 'category_forbidden';
+    case AlreadyScanned = 'already_scanned';
+    case Expired = 'expired';
+    case NotValid = 'not_valid';
+    case UnexpectedError = 'unexpected_error';
+}

app/Domains/Ticket/Models/ScanAttempt.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace App\Domains\Ticket\Models;
+
+use App\Domains\Auth\Models\User;
+use App\Domains\Tenant\Models\Tenant;
+use App\Domains\Ticket\Enums\ScanAttemptResult;
+use Illuminate\Database\Eloquent\Attributes\Fillable;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+#[Fillable([
+    'tenant_code',
+    'scanner_user_id',
+    'ticket_id',
+    'data',
+    'result',
+    'resolved_at',
+])]
+class ScanAttempt extends Model
+{
+    public const UPDATED_AT = null;
+
+    /** @return BelongsTo<User, $this> */
+    public function scanner(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'scanner_user_id')->withTrashed();
+    }
+
+    /** @return BelongsTo<Ticket, $this> */
+    public function ticket(): BelongsTo
+    {
+        return $this->belongsTo(Ticket::class);
+    }
+
+    /** @return BelongsTo<Tenant, $this> */
+    public function tenant(): BelongsTo
+    {
+        return $this->belongsTo(Tenant::class, 'tenant_code', 'codigo');
+    }
+
+    protected function casts(): array
+    {
+        return [
+            'scanner_user_id' => 'integer',
+            'ticket_id' => 'integer',
+            'result' => ScanAttemptResult::class,
+            'created_at' => 'datetime',
+            'resolved_at' => 'datetime',
+        ];
+    }
+}

app/Domains/Ticket/Models/Ticket.php

@@ -16,6 +16,7 @@ use Illuminate\Database\Eloquent\Attributes\Fillable;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Support\Collection;
 
 #[Fillable([
@@ -81,6 +82,12 @@ class Ticket extends Model
         return $this->belongsTo(User::class, 'scanner_user_id')->withTrashed();
     }
 
+    /** @return HasMany<ScanAttempt, $this> */
+    public function scanAttempts(): HasMany
+    {
+        return $this->hasMany(ScanAttempt::class);
+    }
+
     /** @return BelongsTo<PurchaseItem, $this> */
     public function sourcePurchaseItem(): BelongsTo
     {

app/Domains/Ticket/Requests/ScanAttemptIndexRequest.php

@@ -4,7 +4,7 @@ namespace App\Domains\Ticket\Requests;
 
 use Illuminate\Foundation\Http\FormRequest;
 
-class ScannerTicketIndexRequest extends FormRequest
+class ScanAttemptIndexRequest extends FormRequest
 {
     public function authorize(): bool
     {

app/Domains/Ticket/Resources/Scanner/ScanAttemptResource.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Domains\Ticket\Resources\Scanner;
+
+use App\Domains\Ticket\Enums\ScanAttemptResult;
+use App\Domains\Ticket\Models\ScanAttempt;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin ScanAttempt */
+class ScanAttemptResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        return [
+            'id' => $this->id,
+            'data' => $this->data,
+            'ticket_id' => $this->ticket_id,
+            'ticket' => $this->ticket?->ticket,
+            'category' => $this->ticket?->sourceCatalogItem?->category?->nombre,
+            'attempted_at' => $this->created_at,
+            'resolved_at' => $this->resolved_at,
+            'result' => $this->result->value,
+            'result_label' => match ($this->result) {
+                ScanAttemptResult::Processing => 'Procesando',
+                ScanAttemptResult::Accepted => 'Verificado',
+                ScanAttemptResult::InvalidQr => 'QR inválido',
+                ScanAttemptResult::TicketNotFound => 'Ticket inexistente',
+                ScanAttemptResult::CategoryForbidden => 'Categoría no permitida',
+                ScanAttemptResult::AlreadyScanned => 'Ya escaneado',
+                ScanAttemptResult::Expired => 'Vencido',
+                ScanAttemptResult::NotValid => 'No válido',
+                ScanAttemptResult::UnexpectedError => 'Error',
+            },
+            'result_detail_label' => match ($this->result) {
+                ScanAttemptResult::Processing => 'Error',
+                ScanAttemptResult::Accepted => 'Verificado',
+                ScanAttemptResult::InvalidQr => 'QR no pertenece al evento',
+                ScanAttemptResult::TicketNotFound => 'Error',
+                ScanAttemptResult::CategoryForbidden => 'Error',
+                ScanAttemptResult::AlreadyScanned => 'Usado',
+                ScanAttemptResult::Expired => 'Vencido',
+                ScanAttemptResult::NotValid => 'No válido',
+                ScanAttemptResult::UnexpectedError => 'Error',
+            },
+            'can_view_ticket' => $this->ticket !== null
+                && $this->result !== ScanAttemptResult::CategoryForbidden,
+        ];
+    }
+}

app/Domains/Ticket/Resources/Scanner/ScannedTicketResource.php

@@ -1,24 +0,0 @@
-<?php
-
-namespace App\Domains\Ticket\Resources\Scanner;
-
-use App\Domains\Ticket\Models\Ticket;
-use Illuminate\Http\Request;
-use Illuminate\Http\Resources\Json\JsonResource;
-
-/** @mixin Ticket */
-class ScannedTicketResource extends JsonResource
-{
-    /** @return array<string, mixed> */
-    public function toArray(Request $request): array
-    {
-        return [
-            'product' => $this->name,
-            'id' => $this->id,
-            'ticket' => $this->ticket,
-            'used_at' => $this->used_at,
-            'expires_at' => $this->getEffectiveExpiresAt(),
-            'status' => $this->status,
-        ];
-    }
-}

app/Domains/Ticket/Resources/Scanner/ScannerScanResultResource.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Domains\Ticket\Resources\Scanner;
+
+use App\Domains\Ticket\Models\ScanAttempt;
+use App\Domains\Ticket\Resources\TicketResource;
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+
+/** @mixin ScanAttempt */
+class ScannerScanResultResource extends JsonResource
+{
+    /** @return array<string, mixed> */
+    public function toArray(Request $request): array
+    {
+        $ticket = $this->ticket;
+        $client = $ticket?->user;
+
+        return [
+            'scan_attempt' => ScanAttemptResource::make($this->resource),
+            'ticket' => $ticket === null ? null : TicketResource::make($ticket),
+            'client' => $client === null ? null : [
+                'id' => $client->id,
+                'nombre_apellido' => $client->nombre_apellido,
+            ],
+        ];
+    }
+}

app/Domains/Ticket/Services/ScannerTicketService.php

@@ -3,46 +3,119 @@
 namespace App\Domains\Ticket\Services;
 
 use App\Domains\Auth\Models\User;
+use App\Domains\Ticket\Enums\ScanAttemptResult;
+use App\Domains\Ticket\Models\ScanAttempt;
 use App\Domains\Ticket\Models\Ticket;
 use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\ModelNotFoundException;
 use Illuminate\Pagination\LengthAwarePaginator;
 use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
 use Illuminate\Validation\ValidationException;
+use Throwable;
 
 class ScannerTicketService
 {
+    private const INVALID_QR_MESSAGE = 'El QR proporcionado es inválido.';
+
     /**
      * @param  array{q?: string|null, page?: int, per_page?: int}  $filters
-     * @return LengthAwarePaginator<Ticket>
+     * @return LengthAwarePaginator<ScanAttempt>
      */
-    public function scannedBy(User $scanner, array $filters = []): LengthAwarePaginator
+    public function attemptsBy(User $scanner, array $filters = []): LengthAwarePaginator
     {
         $search = trim((string) ($filters['q'] ?? ''));
 
-        return $this->baseQuery()
+        return ScanAttempt::query()
+            ->with('ticket.sourceCatalogItem.category')
             ->where('tenant_code', $scanner->tenant_codigo)
             ->where('scanner_user_id', $scanner->getKey())
             ->when($search !== '', function (Builder $query) use ($search): void {
-                $usedAtDate = $this->parseSearchDate($search);
+                $attemptedAtDate = $this->parseSearchDate($search);
 
-                $query->where(function (Builder $searchQuery) use ($search, $usedAtDate): void {
+                $query->where(function (Builder $searchQuery) use ($search, $attemptedAtDate): void {
-                    $searchQuery->where('ticket', 'like', "%{$search}%");
+                    $searchQuery->where('data', 'like', "%{$search}%");
 
                     if (ctype_digit($search)) {
                         $searchQuery->orWhere('id', (int) $search);
                     }
 
-                    if ($usedAtDate !== null) {
+                    if ($attemptedAtDate !== null) {
-                        $searchQuery->orWhereDate('used_at', $usedAtDate);
+                        $searchQuery->orWhereDate('created_at', $attemptedAtDate);
                     }
                 });
             })
-            ->orderByDesc('used_at')
+            ->orderByDesc('created_at')
             ->orderByDesc('id')
             ->paginateFromRequest()
             ->withQueryString();
     }
 
+    /**
+     * @param  array{q?: string|null, page?: int, per_page?: int}  $filters
+     * @return LengthAwarePaginator<ScanAttempt>
+     */
+    public function attemptsByStaff(User $scanner, array $filters = []): LengthAwarePaginator
+    {
+        $search = trim((string) ($filters['q'] ?? ''));
+
+        return ScanAttempt::query()
+            ->with('ticket.sourceCatalogItem.category')
+            ->where('tenant_code', $scanner->tenant_codigo)
+            ->where('scanner_user_id', $scanner->getKey())
+            ->when($search !== '', function (Builder $query) use ($search): void {
+                $attemptedAtDate = $this->parseSearchDate($search);
+                $attemptedAtDayMonth = $this->parseSearchDayMonth($search);
+
+                $query->where(function (Builder $searchQuery) use (
+                    $search,
+                    $attemptedAtDate,
+                    $attemptedAtDayMonth,
+                ): void {
+                    $searchQuery
+                        ->whereHas(
+                            'ticket.sourceCatalogItem.category',
+                            fn (Builder $categoryQuery): Builder => $categoryQuery
+                                ->where('nombre', 'like', "%{$search}%")
+                        )
+                        ->orWhere('created_at', 'like', "%{$search}%");
+
+                    if (ctype_digit($search)) {
+                        $searchQuery->orWhere('ticket_id', (int) $search);
+                    }
+
+                    if ($attemptedAtDate !== null) {
+                        $searchQuery->orWhereDate('created_at', $attemptedAtDate);
+                    }
+
+                    if ($attemptedAtDayMonth !== null) {
+                        $searchQuery->orWhere(function (Builder $dateQuery) use ($attemptedAtDayMonth): void {
+                            $dateQuery
+                                ->whereDay('created_at', $attemptedAtDayMonth['day'])
+                                ->whereMonth('created_at', $attemptedAtDayMonth['month']);
+                        });
+                    }
+                });
+            })
+            ->orderByDesc('created_at')
+            ->orderByDesc('id')
+            ->paginateFromRequest()
+            ->withQueryString();
+    }
+
+    public function scanAttemptDetail(User $scanner, int $scanAttemptId): ScanAttempt
+    {
+        $scanAttempt = ScanAttempt::query()
+            ->with('ticket')
+            ->where('tenant_code', $scanner->tenant_codigo)
+            ->where('scanner_user_id', $scanner->getKey())
+            ->findOrFail($scanAttemptId);
+
+        $scanAttempt->ticket?->loadMissing($this->relations());
+
+        return $scanAttempt;
+    }
+
     private function parseSearchDate(string $search): ?string
     {
         if (preg_match('/^(\d{4})-(\d{2})-(\d{2})$/', $search, $matches) === 1) {
@@ -67,6 +140,19 @@ class ScannerTicketService
         return null;
     }
 
+    /** @return array{day: int, month: int}|null */
+    private function parseSearchDayMonth(string $search): ?array
+    {
+        if (preg_match('/^(\d{1,2})\/(\d{1,2})$/', $search, $matches) !== 1) {
+            return null;
+        }
+
+        $day = (int) $matches[1];
+        $month = (int) $matches[2];
+
+        return checkdate($month, $day, 2000) ? compact('day', 'month') : null;
+    }
+
     public function detail(User $scanner, string $ticketUuid): Ticket
     {
         $query = $this->baseQuery()
@@ -90,42 +176,119 @@ class ScannerTicketService
         return $query->firstOrFail();
     }
 
-    public function scan(User $scanner, string $ticketUuid): Ticket
+    public function scan(User $scanner, mixed $scannedData): ScanAttempt
     {
-        return DB::transaction(function () use ($scanner, $ticketUuid): Ticket {
+        $scanAttempt = ScanAttempt::query()->create([
-            $ticket = $this->baseQuery()
+            'tenant_code' => $scanner->tenant_codigo,
-                ->where('tenant_code', $scanner->tenant_codigo)
+            'scanner_user_id' => $scanner->getKey(),
-                ->where('ticket', $ticketUuid)
+            'data' => $this->serializeScannedData($scannedData),
-                ->lockForUpdate()
+            'result' => ScanAttemptResult::Processing,
-                ->firstOrFail();
+        ]);
 
-            if (! $this->scannerCanScan($scanner, $ticket)) {
+        if (! is_string($scannedData) || ! Str::isUuid($scannedData)) {
-                throw ValidationException::withMessages([
+            $this->resolveScanAttempt($scanAttempt, ScanAttemptResult::InvalidQr);
-                    'ticket' => __('api.ticket.scanner_category_forbidden'),
-                ]);
-            }
 
-            if ($ticket->is_used) {
+            throw ValidationException::withMessages([
-                throw ValidationException::withMessages([
+                'data' => self::INVALID_QR_MESSAGE,
-                    'ticket' => __('api.ticket.already_scanned'),
+            ]);
-                ]);
+        }
-            }
 
-            if (! $ticket->is_valid) {
+        $ticketId = null;
-                throw ValidationException::withMessages([
+        $failureResult = null;
-                    'ticket' => $ticket->is_expired
-                        ? __('api.ticket.expired_for_scan')
-                        : __('api.ticket.not_valid_for_scan'),
-                ]);
-            }
 
-            $ticket->forceFill([
+        try {
-                'used_at' => now(),
+            return DB::transaction(function () use (
-                'scanner_user_id' => $scanner->getKey(),
+                $scanner,
-            ])->save();
+                $scannedData,
+                $scanAttempt,
+                &$ticketId,
+                &$failureResult,
+            ): ScanAttempt {
+                $ticket = $this->baseQuery()
+                    ->where('tenant_code', $scanner->tenant_codigo)
+                    ->where('ticket', $scannedData)
+                    ->lockForUpdate()
+                    ->firstOrFail();
+                $ticketId = (int) $ticket->getKey();
 
-            return $ticket->refresh()->load($this->relations());
+                if (! $this->scannerCanScan($scanner, $ticket)) {
-        });
+                    $failureResult = ScanAttemptResult::CategoryForbidden;
+
+                    throw ValidationException::withMessages([
+                        'ticket' => __('api.ticket.scanner_category_forbidden'),
+                    ]);
+                }
+
+                if ($ticket->is_used) {
+                    $failureResult = ScanAttemptResult::AlreadyScanned;
+
+                    throw ValidationException::withMessages([
+                        'ticket' => __('api.ticket.already_scanned'),
+                    ]);
+                }
+
+                if (! $ticket->is_valid) {
+                    $failureResult = $ticket->is_expired
+                        ? ScanAttemptResult::Expired
+                        : ScanAttemptResult::NotValid;
+
+                    throw ValidationException::withMessages([
+                        'ticket' => $ticket->is_expired
+                            ? __('api.ticket.expired_for_scan')
+                            : __('api.ticket.not_valid_for_scan'),
+                    ]);
+                }
+
+                $ticket->forceFill([
+                    'used_at' => now(),
+                    'scanner_user_id' => $scanner->getKey(),
+                ])->save();
+
+                $this->resolveScanAttempt(
+                    $scanAttempt,
+                    ScanAttemptResult::Accepted,
+                    $ticketId,
+                );
+
+                $ticket = $ticket->refresh()->load($this->relations());
+
+                return $scanAttempt->refresh()->setRelation('ticket', $ticket);
+            });
+        } catch (Throwable $exception) {
+            $result = $exception instanceof ModelNotFoundException
+                ? ScanAttemptResult::TicketNotFound
+                : ($failureResult ?? ScanAttemptResult::UnexpectedError);
+
+            $this->resolveScanAttempt($scanAttempt, $result, $ticketId);
+
+            throw $exception;
+        }
+    }
+
+    private function resolveScanAttempt(
+        ScanAttempt $scanAttempt,
+        ScanAttemptResult $result,
+        ?int $ticketId = null,
+    ): void {
+        $scanAttempt->forceFill([
+            'ticket_id' => $ticketId,
+            'result' => $result,
+            'resolved_at' => now(),
+        ])->save();
+    }
+
+    private function serializeScannedData(mixed $scannedData): ?string
+    {
+        if ($scannedData === null || is_string($scannedData)) {
+            return $scannedData;
+        }
+
+        $encoded = json_encode(
+            $scannedData,
+            JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE,
+        );
+
+        return $encoded === false ? get_debug_type($scannedData) : $encoded;
     }
 
     /** @return Builder<Ticket> */

app/Domains/Ticket/routes/scanner.php

@@ -1,14 +1,18 @@
 <?php
 
+use App\Domains\Ticket\Controllers\Scanner\ScanAttemptController;
 use App\Domains\Ticket\Controllers\Scanner\TicketController;
 use Illuminate\Support\Facades\Route;
 
-Route::prefix('v1/scanner/tickets')
+Route::middleware(['auth:sanctum', 'scanner.tenant'])
-    ->middleware(['auth:sanctum', 'scanner.tenant'])
     ->group(function (): void {
-        Route::get('/', [TicketController::class, 'index']);
+        Route::get('v1/scanner/attempts', ScanAttemptController::class);
-        Route::get('{ticketUuid}', [TicketController::class, 'show'])
+        Route::get('v1/scanner/attempts/{scanAttempt}', [ScanAttemptController::class, 'show'])
-            ->whereUuid('ticketUuid');
+            ->whereNumber('scanAttempt');
-        Route::post('{ticketUuid}/scan', [TicketController::class, 'scan'])
+
-            ->whereUuid('ticketUuid');
+        Route::prefix('v1/scanner/tickets')->group(function (): void {
+            Route::post('scan', [TicketController::class, 'scan']);
+            Route::get('{ticketUuid}', [TicketController::class, 'show'])
+                ->whereUuid('ticketUuid');
+        });
     });

database/migrations/2026_09_07_000000_create_scan_attempts_table.php

@@ -0,0 +1,46 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    public function up(): void
+    {
+        Schema::create('scan_attempts', function (Blueprint $table): void {
+            $table->id();
+            $table->string('tenant_code');
+            $table->foreignId('scanner_user_id')
+                ->nullable()
+                ->constrained('users')
+                ->cascadeOnUpdate()
+                ->nullOnDelete();
+            $table->foreignId('ticket_id')
+                ->nullable()
+                ->constrained('tickets')
+                ->cascadeOnUpdate()
+                ->nullOnDelete();
+            $table->text('data')->nullable();
+            $table->string('result', 32);
+            $table->timestamp('resolved_at')->nullable();
+            $table->timestamp('created_at')->useCurrent();
+
+            $table->foreign('tenant_code')
+                ->references('codigo')
+                ->on('tenants')
+                ->cascadeOnUpdate()
+                ->restrictOnDelete();
+
+            $table->index(['scanner_user_id', 'created_at']);
+            $table->index(['tenant_code', 'created_at']);
+            $table->index(['ticket_id', 'created_at']);
+            $table->index(['tenant_code', 'result', 'created_at']);
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::dropIfExists('scan_attempts');
+    }
+};

postman/generate-shopit-collection.php

@@ -113,6 +113,7 @@ function bodyFor(string $method, string $uri): ?array
         'POST api/v1/scanner/password/reset-attempts' => ['email' => '{{scanner_email}}'],
         'POST api/v1/scanner/password/reset-attempts/validate' => ['email' => '{{scanner_email}}', 'codigo' => '{{reset_code}}'],
         'POST api/v1/scanner/password/reset' => ['email' => '{{scanner_email}}', 'codigo' => '{{reset_code}}', 'password' => '{{scanner_password}}', 'password_confirmation' => '{{scanner_password}}'],
+        'POST api/v1/scanner/tickets/scan' => ['data' => '{{ticket_uuid}}'],
     ];
 
     if (isset($exact[$key])) {
@@ -201,7 +202,7 @@ function queryFor(string $uri): array
             ['key' => 'page', 'value' => '1'],
             ['key' => 'per_page', 'value' => '20'],
         ],
-        'api/v1/scanner/tickets' => [['key' => 'q', 'value' => '', 'disabled' => true], ['key' => 'page', 'value' => '1'], ['key' => 'per_page', 'value' => '20']],
+        'api/v1/scanner/attempts' => [['key' => 'q', 'value' => '', 'disabled' => true], ['key' => 'page', 'value' => '1'], ['key' => 'per_page', 'value' => '20']],
         'api/storage-test/s3/temporary-url' => [['key' => 'path', 'value' => '{{s3_path}}'], ['key' => 'expires_in_minutes', 'value' => '60']],
         default => [],
     };

tests/Feature/Auth/ScannerMeControllerTest.php

@@ -8,6 +8,7 @@ use App\Domains\Authorization\Enums\PermissionCode;
 use App\Domains\Authorization\Enums\RoleCode;
 use App\Domains\Authorization\Models\Permission;
 use App\Domains\Authorization\Models\Role;
+use App\Domains\Catalog\Models\Category;
 use App\Domains\Menu\Models\Menu;
 use App\Domains\Tenant\Models\Tenant;
 use Illuminate\Foundation\Testing\RefreshDatabase;
@@ -85,6 +86,65 @@ class ScannerMeControllerTest extends TestCase
         $this->getJson('/api/v1/scanner/me')->assertForbidden();
     }
 
+    public function test_it_returns_assigned_scan_categories_when_validation_is_enabled(): void
+    {
+        $this->createScannerRole();
+        $tenant = $this->createTenant();
+        $scanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $tenant->codigo,
+        ]);
+        $meals = Category::query()->create(['tenant_code' => $tenant->codigo, 'nombre' => 'Comidas']);
+        $entries = Category::query()->create(['tenant_code' => $tenant->codigo, 'nombre' => 'Entradas']);
+        $scanner->scanCategories()->attach([$meals->id, $entries->id]);
+        Sanctum::actingAs($scanner);
+
+        $this->getJson('/api/v1/scanner/me')
+            ->assertOk()
+            ->assertJsonPath('data.user.categories.0.id', $meals->id)
+            ->assertJsonPath('data.user.categories.0.nombre', 'Comidas')
+            ->assertJsonPath('data.user.categories.1.id', $entries->id)
+            ->assertJsonPath('data.user.categories.1.nombre', 'Entradas');
+    }
+
+    public function test_it_omits_scan_categories_when_validation_is_disabled_or_none_are_assigned(): void
+    {
+        $this->createScannerRole();
+        $tenant = $this->createTenant();
+        $scanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $tenant->codigo,
+        ]);
+        Sanctum::actingAs($scanner);
+
+        $this->getJson('/api/v1/scanner/me')
+            ->assertOk()
+            ->assertJsonMissingPath('data.user.categories');
+
+        $category = Category::query()->create(['tenant_code' => $tenant->codigo, 'nombre' => 'Entradas']);
+        $scanner->scanCategories()->attach($category);
+        $tenant->update(['scanner_category_validation_enabled' => false]);
+
+        $this->getJson('/api/v1/scanner/me')
+            ->assertOk()
+            ->assertJsonMissingPath('data.user.categories');
+    }
+
+    private function createScannerRole(): Role
+    {
+        $role = Role::query()->create([
+            'codigo' => RoleCode::Scanner->value,
+            'nombre' => 'Scanner',
+        ]);
+        $permission = Permission::query()->create([
+            'codigo' => PermissionCode::ScanTickets->value,
+            'nombre' => 'Escanear tickets',
+        ]);
+        $role->permissions()->attach($permission->codigo);
+
+        return $role;
+    }
+
     private function createTenant(): Tenant
     {
         $logo = Attachment::query()->create([

tests/Feature/Staff/StaffControllerTest.php

@@ -7,10 +7,13 @@ use App\Domains\Attachable\Models\Attachment;
 use App\Domains\Auth\Models\ResetPasswordAttempt;
 use App\Domains\Auth\Models\User;
 use App\Domains\Authorization\Enums\RoleCode;
+use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Category;
 use App\Domains\Notification\Events\PasswordResetRequested;
 use App\Domains\Tenant\Models\Tenant;
 use App\Domains\Tenant\Models\WebsiteType;
+use App\Domains\Ticket\Enums\ScanAttemptResult;
+use App\Domains\Ticket\Models\ScanAttempt;
 use App\Domains\Ticket\Models\Ticket;
 use Database\Seeders\AuthorizationSeeder;
 use Illuminate\Foundation\Testing\RefreshDatabase;
@@ -264,6 +267,159 @@ class StaffControllerTest extends TestCase
         $this->getJson('/api/v1/adminapp/tenant/staff')->assertForbidden();
     }
 
+    public function test_adminapp_can_search_staff_scan_attempts_by_ticket_id_category_and_date(): void
+    {
+        $scanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $this->tenant->codigo,
+        ]);
+        $otherScanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $this->tenant->codigo,
+        ]);
+        $category = $this->createCategory('Alojamiento');
+        $catalogItem = CatalogItem::query()->create([
+            'tenant_code' => $this->tenant->codigo,
+            'category_id' => $category->id,
+            'slug' => 'alojamiento-test',
+            'nombre' => 'Hotel',
+            'precio' => 100,
+        ]);
+        $ticket = Ticket::query()->create([
+            'tenant_code' => $this->tenant->codigo,
+            'ticket' => (string) Str::uuid(),
+            'source_catalog_item_id' => $catalogItem->id,
+            'user_id' => $this->admin->id,
+        ]);
+        $matching = $this->createScanAttempt($scanner, 'matching-qr', [
+            'ticket_id' => $ticket->id,
+            'created_at' => '2026-08-11 14:30:00',
+        ]);
+        $this->createScanAttempt($scanner, 'another-qr', [
+            'created_at' => '2026-08-22 22:22:22',
+        ]);
+        $this->createScanAttempt($otherScanner, 'matching-qr', [
+            'ticket_id' => $ticket->id,
+            'created_at' => '2026-08-11 14:30:00',
+        ]);
+        Sanctum::actingAs($this->admin);
+
+        $this->getJson(
+            "/api/v1/adminapp/tenant/staff/{$scanner->id}/scan-attempts?q={$ticket->id}"
+        )->assertOk()
+            ->assertJsonFragment([
+                'id' => $matching->id,
+                'ticket_id' => $ticket->id,
+            ]);
+
+        $assertSingleMatchingAttempt = function (string $search) use ($scanner, $matching, $ticket): void {
+            $this->getJson(
+                "/api/v1/adminapp/tenant/staff/{$scanner->id}/scan-attempts?q=".urlencode($search).'&per_page=1'
+            )
+                ->assertOk()
+                ->assertJsonCount(1, 'data')
+                ->assertJsonPath('data.0.id', $matching->id)
+                ->assertJsonPath('data.0.ticket_id', $ticket->id)
+                ->assertJsonPath('data.0.category', 'Alojamiento')
+                ->assertJsonPath('data.0.result_label', 'Verificado')
+                ->assertJsonPath('meta.current_page', 1)
+                ->assertJsonPath('meta.per_page', 1)
+                ->assertJsonPath('meta.total', 1);
+        };
+
+        $assertSingleMatchingAttempt('alojamiento');
+        $assertSingleMatchingAttempt('11/08/26');
+    }
+
+    public function test_adminapp_cannot_list_scan_attempts_for_non_scanner_staff(): void
+    {
+        $customer = User::factory()->create([
+            'rol_codigo' => RoleCode::User->value,
+            'tenant_codigo' => $this->tenant->codigo,
+        ]);
+        Sanctum::actingAs($this->admin);
+
+        $this->getJson("/api/v1/adminapp/tenant/staff/{$customer->id}/scan-attempts")
+            ->assertNotFound();
+    }
+
+    public function test_adminapp_can_search_staff_scan_attempts_by_day_and_month_across_years(): void
+    {
+        $scanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $this->tenant->codigo,
+        ]);
+        $firstMatch = $this->createScanAttempt($scanner, 'first-match', [
+            'created_at' => '2024-09-07 10:00:00',
+        ]);
+        $secondMatch = $this->createScanAttempt($scanner, 'second-match', [
+            'created_at' => '2026-09-07 10:00:00',
+        ]);
+        $this->createScanAttempt($scanner, 'different-day', [
+            'created_at' => '2026-09-08 10:00:00',
+        ]);
+        Sanctum::actingAs($this->admin);
+
+        $this->getJson("/api/v1/adminapp/tenant/staff/{$scanner->id}/scan-attempts?q=07%2F09")
+            ->assertOk()
+            ->assertJsonCount(2, 'data')
+            ->assertJsonPath('data.0.id', $secondMatch->id)
+            ->assertJsonPath('data.1.id', $firstMatch->id)
+            ->assertJsonPath('meta.total', 2);
+    }
+
+    public function test_adminapp_datetime_search_matches_text_in_any_datetime_component(): void
+    {
+        $scanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $this->tenant->codigo,
+        ]);
+        $matches = [
+            $this->createScanAttempt($scanner, 'year-match', [
+                'created_at' => '2007-11-12 10:00:08',
+            ]),
+            $this->createScanAttempt($scanner, 'month-match', [
+                'created_at' => '2026-07-12 10:00:08',
+            ]),
+            $this->createScanAttempt($scanner, 'day-match', [
+                'created_at' => '2026-11-07 10:00:08',
+            ]),
+            $this->createScanAttempt($scanner, 'seconds-match', [
+                'created_at' => '2026-11-12 10:00:07',
+            ]),
+        ];
+        $this->createScanAttempt($scanner, 'no-match', [
+            'created_at' => '2026-11-12 10:00:08',
+        ]);
+        Sanctum::actingAs($this->admin);
+
+        $response = $this->getJson(
+            "/api/v1/adminapp/tenant/staff/{$scanner->id}/scan-attempts?q=07"
+        )->assertOk()
+            ->assertJsonCount(4, 'data')
+            ->assertJsonPath('meta.total', 4);
+
+        foreach ($matches as $match) {
+            $response->assertJsonFragment(['id' => $match->id]);
+        }
+    }
+
+    /** @param array<string, mixed> $attributes */
+    private function createScanAttempt(User $scanner, string $data, array $attributes = []): ScanAttempt
+    {
+        $attempt = new ScanAttempt;
+        $attempt->forceFill(array_merge([
+            'tenant_code' => $this->tenant->codigo,
+            'scanner_user_id' => $scanner->id,
+            'data' => $data,
+            'result' => ScanAttemptResult::Accepted,
+            'resolved_at' => now(),
+        ], $attributes));
+        $attempt->save();
+
+        return $attempt;
+    }
+
     private function createAttachment(string $filename): Attachment
     {
         return Attachment::query()->create([

tests/Feature/Ticket/PrepareLoadTestTicketsCommandTest.php

@@ -68,7 +68,7 @@ class PrepareLoadTestTicketsCommandTest extends TestCase
 
         $first = $rows[0];
         $this->withToken($first['scanner_token'])
-            ->postJson("/api/v1/scanner/tickets/{$first['ticket_uuid']}/scan")
+            ->postJson('/api/v1/scanner/tickets/scan', ['data' => $first['ticket_uuid']])
             ->assertOk()
             ->assertJsonPath('data.ticket', $first['ticket_uuid']);
 

tests/Feature/Ticket/ScannerTicketControllerTest.php

@@ -10,6 +10,8 @@ use App\Domains\Catalog\Models\CatalogItem;
 use App\Domains\Catalog\Models\Category;
 use App\Domains\Tenant\Models\Tenant;
 use App\Domains\Tenant\Models\WebsiteType;
+use App\Domains\Ticket\Enums\ScanAttemptResult;
+use App\Domains\Ticket\Models\ScanAttempt;
 use App\Domains\Ticket\Models\Ticket;
 use Database\Seeders\AuthorizationSeeder;
 use Illuminate\Foundation\Testing\RefreshDatabase;
@@ -50,108 +52,163 @@ class ScannerTicketControllerTest extends TestCase
 
     public function test_scanner_routes_require_authentication_and_scan_permission(): void
     {
-        $this->getJson('/api/v1/scanner/tickets')->assertUnauthorized();
+        $this->getJson('/api/v1/scanner/attempts')->assertUnauthorized();
 
         Sanctum::actingAs(User::factory()->create([
             'rol_codigo' => RoleCode::User->value,
             'tenant_codigo' => $this->tenant->codigo,
         ]));
 
-        $this->getJson('/api/v1/scanner/tickets')->assertForbidden();
+        $this->getJson('/api/v1/scanner/attempts')->assertForbidden();
     }
 
-    public function test_scanner_can_list_only_its_scanned_tickets_using_adminapp_format(): void
+    public function test_scanner_can_list_only_its_scan_attempts(): void
     {
-        $older = $this->createTicket('11111111-1111-4111-8111-111111111111', [
+        $olderTicket = $this->createTicket('11111111-1111-4111-8111-111111111111');
-            'used_at' => now()->subMinutes(2),
+        $newerTicket = $this->createTicket('22222222-2222-4222-8222-222222222222');
-            'scanner_user_id' => $this->scanner->id,
+        $older = $this->createScanAttempt($olderTicket->ticket, [
+            'ticket_id' => $olderTicket->id,
+            'created_at' => now()->subMinutes(2),
         ]);
-        $newer = $this->createTicket('22222222-2222-4222-8222-222222222222', [
+        $newer = $this->createScanAttempt($newerTicket->ticket, [
-            'used_at' => now()->subMinute(),
+            'ticket_id' => $newerTicket->id,
-            'scanner_user_id' => $this->scanner->id,
+            'created_at' => now()->subMinute(),
         ]);
         $otherScanner = User::factory()->create([
             'rol_codigo' => RoleCode::Scanner->value,
             'tenant_codigo' => $this->tenant->codigo,
         ]);
-        $this->createTicket('33333333-3333-4333-8333-333333333333', [
+        $this->createScanAttempt('not-this-scanner', [], $otherScanner);
-            'used_at' => now(),
-            'scanner_user_id' => $otherScanner->id,
-        ]);
 
         Sanctum::actingAs($this->scanner);
 
-        $this->getJson('/api/v1/scanner/tickets')
+        $this->getJson('/api/v1/scanner/attempts')
             ->assertOk()
             ->assertJsonCount(2, 'data')
             ->assertJsonPath('data.0.id', $newer->id)
-            ->assertJsonPath('data.0.ticket', $newer->ticket)
+            ->assertJsonPath('data.0.data', $newer->data)
-            ->assertJsonPath('data.0.status', Ticket::STATUS_USED)
+            ->assertJsonPath('data.0.ticket_id', $newerTicket->id)
+            ->assertJsonPath('data.0.ticket', $newerTicket->ticket)
+            ->assertJsonPath('data.0.resolved_at', $newer->resolved_at->toJSON())
+            ->assertJsonPath('data.0.result', ScanAttemptResult::Accepted->value)
+            ->assertJsonPath('data.0.result_label', 'Verificado')
+            ->assertJsonPath('data.0.result_detail_label', 'Verificado')
+            ->assertJsonPath('data.0.can_view_ticket', true)
             ->assertJsonPath('data.1.id', $older->id)
             ->assertJsonPath('meta.current_page', 1)
             ->assertJsonPath('meta.total', 2);
     }
 
-    public function test_scanner_ticket_history_supports_id_search_and_pagination(): void
+    public function test_scanner_attempt_history_supports_data_search_and_pagination(): void
     {
-        $matching = $this->createTicket('aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa', [
+        $matching = $this->createScanAttempt('aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa');
-            'used_at' => now(),
+        $this->createScanAttempt('bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb');
-            'scanner_user_id' => $this->scanner->id,
-        ]);
-        $this->createTicket('bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb', [
-            'used_at' => now()->subMinute(),
-            'scanner_user_id' => $this->scanner->id,
-        ]);
 
         Sanctum::actingAs($this->scanner);
 
-        $this->getJson('/api/v1/scanner/tickets?q=aaaaaaaa&per_page=1')
+        $this->getJson('/api/v1/scanner/attempts?q=aaaaaaaa&per_page=1')
             ->assertOk()
             ->assertJsonCount(1, 'data')
-            ->assertJsonPath('data.0.ticket', $matching->ticket)
+            ->assertJsonPath('data.0.data', $matching->data)
             ->assertJsonPath('meta.current_page', 1)
             ->assertJsonPath('meta.per_page', 1)
             ->assertJsonPath('meta.total', 1);
     }
 
-    public function test_scanner_ticket_history_can_be_searched_by_database_id(): void
+    public function test_scanner_attempt_history_can_be_searched_by_database_id(): void
     {
-        $matching = $this->createTicket('cccccccc-cccc-4ccc-8ccc-cccccccccccc', [
+        $matching = $this->createScanAttempt('cccccccc-cccc-4ccc-8ccc-cccccccccccc');
-            'used_at' => now(),
+        $this->createScanAttempt('dddddddd-dddd-4ddd-8ddd-dddddddddddd');
-            'scanner_user_id' => $this->scanner->id,
-        ]);
-        $this->createTicket('dddddddd-dddd-4ddd-8ddd-dddddddddddd', [
-            'used_at' => now()->subMinute(),
-            'scanner_user_id' => $this->scanner->id,
-        ]);
 
         Sanctum::actingAs($this->scanner);
 
-        $this->getJson("/api/v1/scanner/tickets?q={$matching->id}")
+        $this->getJson("/api/v1/scanner/attempts?q={$matching->id}")
             ->assertOk()
             ->assertJsonCount(1, 'data')
             ->assertJsonPath('data.0.id', $matching->id);
     }
 
-    public function test_scanner_ticket_history_can_be_searched_by_used_date(): void
+    public function test_scanner_attempt_history_can_be_searched_by_attempt_date(): void
     {
-        $matching = $this->createTicket('eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee', [
+        $matching = $this->createScanAttempt('eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee', [
-            'used_at' => '2026-08-11 14:30:00',
+            'created_at' => '2026-08-11 14:30:00',
-            'scanner_user_id' => $this->scanner->id,
         ]);
-        $this->createTicket('ffffffff-ffff-4fff-8fff-ffffffffffff', [
+        $this->createScanAttempt('ffffffff-ffff-4fff-8fff-ffffffffffff', [
-            'used_at' => '2026-08-10 14:30:00',
+            'created_at' => '2026-08-10 14:30:00',
-            'scanner_user_id' => $this->scanner->id,
         ]);
 
         Sanctum::actingAs($this->scanner);
 
-        $this->getJson('/api/v1/scanner/tickets?q=11%2F08%2F26')
+        $this->getJson('/api/v1/scanner/attempts?q=11%2F08%2F26')
             ->assertOk()
             ->assertJsonCount(1, 'data')
             ->assertJsonPath('data.0.id', $matching->id);
     }
 
+    public function test_scanner_can_read_its_scan_attempt_detail(): void
+    {
+        $ticket = $this->createTicket('abababab-abab-4bab-8bab-abababababab');
+        $scanAttempt = $this->createScanAttempt($ticket->ticket, [
+            'ticket_id' => $ticket->id,
+        ]);
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson("/api/v1/scanner/attempts/{$scanAttempt->id}")
+            ->assertOk()
+            ->assertJsonPath('data.scan_attempt.id', $scanAttempt->id)
+            ->assertJsonPath('data.scan_attempt.ticket_id', $ticket->id)
+            ->assertJsonPath('data.scan_attempt.result', ScanAttemptResult::Accepted->value)
+            ->assertJsonPath('data.scan_attempt.result_label', 'Verificado')
+            ->assertJsonPath('data.scan_attempt.result_detail_label', 'Verificado')
+            ->assertJsonPath('data.ticket.id', $ticket->id)
+            ->assertJsonPath('data.ticket.ticket', $ticket->ticket)
+            ->assertJsonPath('data.ticket.client', $this->ticketOwner->nombre_apellido)
+            ->assertJsonPath('data.client.id', $this->ticketOwner->id)
+            ->assertJsonPath('data.client.nombre_apellido', $this->ticketOwner->nombre_apellido);
+    }
+
+    public function test_scanner_cannot_read_another_scanners_attempt_detail(): void
+    {
+        $otherScanner = User::factory()->create([
+            'rol_codigo' => RoleCode::Scanner->value,
+            'tenant_codigo' => $this->tenant->codigo,
+        ]);
+        $scanAttempt = $this->createScanAttempt('not-this-scanner', [], $otherScanner);
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson("/api/v1/scanner/attempts/{$scanAttempt->id}")
+            ->assertNotFound();
+    }
+
+    public function test_scan_attempt_detail_returns_null_ticket_and_client_when_unassociated(): void
+    {
+        $scanAttempt = $this->createScanAttempt('not-a-ticket', [
+            'result' => ScanAttemptResult::TicketNotFound,
+        ]);
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson("/api/v1/scanner/attempts/{$scanAttempt->id}")
+            ->assertOk()
+            ->assertJsonPath('data.scan_attempt.id', $scanAttempt->id)
+            ->assertJsonPath('data.scan_attempt.result_label', 'Ticket inexistente')
+            ->assertJsonPath('data.scan_attempt.result_detail_label', 'Error')
+            ->assertJsonPath('data.ticket', null)
+            ->assertJsonPath('data.client', null);
+    }
+
+    public function test_scan_attempt_detail_returns_specific_invalid_qr_label(): void
+    {
+        $scanAttempt = $this->createScanAttempt('not-a-valid-qr', [
+            'result' => ScanAttemptResult::InvalidQr,
+        ]);
+        Sanctum::actingAs($this->scanner);
+
+        $this->getJson("/api/v1/scanner/attempts/{$scanAttempt->id}")
+            ->assertOk()
+            ->assertJsonPath('data.scan_attempt.result_label', 'QR inválido')
+            ->assertJsonPath('data.scan_attempt.result_detail_label', 'QR no pertenece al evento');
+    }
+
     public function test_scanner_can_read_an_authorized_ticket_detail_by_uuid(): void
     {
         $ticket = $this->createTicket('44444444-4444-4444-8444-444444444444');
@@ -203,25 +260,67 @@ class ScannerTicketControllerTest extends TestCase
         $ticket = $this->createTicket('77777777-7777-4777-8777-777777777777');
         Sanctum::actingAs($this->scanner);
 
-        $this->postJson("/api/v1/scanner/tickets/{$ticket->ticket}/scan")
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $ticket->ticket])
             ->assertOk()
-            ->assertJsonPath('data.ticket', $ticket->ticket)
+            ->assertJsonPath('data.scan_attempt.data', $ticket->ticket)
-            ->assertJsonPath('data.scanner_user_id', $this->scanner->id)
+            ->assertJsonPath('data.scan_attempt.ticket_id', $ticket->id)
-            ->assertJsonPath('data.is_valid', false)
+            ->assertJsonPath('data.scan_attempt.ticket', $ticket->ticket)
-            ->assertJsonPath('data.is_used', true);
+            ->assertJsonPath('data.scan_attempt.result', ScanAttemptResult::Accepted->value)
+            ->assertJsonPath('data.scan_attempt.result_label', 'Verificado')
+            ->assertJsonPath('data.scan_attempt.result_detail_label', 'Verificado')
+            ->assertJsonPath('data.ticket.ticket', $ticket->ticket)
+            ->assertJsonPath('data.ticket.scanner_user_id', $this->scanner->id)
+            ->assertJsonPath('data.ticket.is_valid', false)
+            ->assertJsonPath('data.ticket.is_used', true)
+            ->assertJsonPath('data.ticket.client', $this->ticketOwner->nombre_apellido)
+            ->assertJsonPath('data.client.id', $this->ticketOwner->id)
+            ->assertJsonPath('data.client.nombre_apellido', $this->ticketOwner->nombre_apellido);
 
         $this->assertDatabaseHas('tickets', [
             'id' => $ticket->id,
             'scanner_user_id' => $this->scanner->id,
         ]);
         $this->assertNotNull($ticket->fresh()->used_at);
+
+        $scanAttempt = ScanAttempt::query()->sole();
+        $this->assertSame($ticket->ticket, $scanAttempt->data);
+        $this->assertSame(ScanAttemptResult::Accepted, $scanAttempt->result);
+        $this->assertTrue($scanAttempt->scanner->is($this->scanner));
+        $this->assertTrue($scanAttempt->ticket->is($ticket));
+        $this->assertTrue($scanAttempt->tenant->is($this->tenant));
+        $this->assertNotNull($scanAttempt->resolved_at);
+    }
+
+    public function test_scan_requires_a_uuid_in_the_data_field(): void
+    {
+        Sanctum::actingAs($this->scanner);
+
+        $this->postJson('/api/v1/scanner/tickets/scan')
+            ->assertUnprocessable()
+            ->assertJsonPath('message', 'El QR proporcionado es inválido.')
+            ->assertJsonPath('errors.data.0', 'El QR proporcionado es inválido.');
+
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => 'not-a-uuid'])
+            ->assertUnprocessable()
+            ->assertJsonPath('message', 'El QR proporcionado es inválido.')
+            ->assertJsonPath('errors.data.0', 'El QR proporcionado es inválido.');
+
+        $scanAttempts = ScanAttempt::query()->orderBy('id')->get();
+        $this->assertCount(2, $scanAttempts);
+        $this->assertNull($scanAttempts[0]->data);
+        $this->assertSame('not-a-uuid', $scanAttempts[1]->data);
+        $this->assertTrue($scanAttempts->every(
+            fn (ScanAttempt $scanAttempt): bool => $scanAttempt->result === ScanAttemptResult::InvalidQr
+                && $scanAttempt->scanner_user_id === $this->scanner->id
+                && $scanAttempt->resolved_at !== null
+        ));
     }
 
     public function test_ticket_cannot_be_scanned_twice(): void
     {
         $ticket = $this->createTicket('88888888-8888-4888-8888-888888888888');
         Sanctum::actingAs($this->scanner);
-        $this->postJson("/api/v1/scanner/tickets/{$ticket->ticket}/scan")->assertOk();
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $ticket->ticket])->assertOk();
 
         $otherScanner = User::factory()->create([
             'rol_codigo' => RoleCode::Scanner->value,
@@ -230,10 +329,15 @@ class ScannerTicketControllerTest extends TestCase
         $otherScanner->scanCategories()->attach($this->category);
         Sanctum::actingAs($otherScanner);
 
-        $this->postJson("/api/v1/scanner/tickets/{$ticket->ticket}/scan")
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $ticket->ticket])
             ->assertUnprocessable()
             ->assertJsonValidationErrors('ticket');
         $this->assertSame($this->scanner->id, $ticket->fresh()->scanner_user_id);
+        $this->assertDatabaseHas('scan_attempts', [
+            'scanner_user_id' => $otherScanner->id,
+            'ticket_id' => $ticket->id,
+            'result' => ScanAttemptResult::AlreadyScanned->value,
+        ]);
     }
 
     public function test_scanner_cannot_scan_a_ticket_from_an_unassigned_category(): void
@@ -249,10 +353,15 @@ class ScannerTicketControllerTest extends TestCase
         );
         Sanctum::actingAs($this->scanner);
 
-        $this->postJson("/api/v1/scanner/tickets/{$ticket->ticket}/scan")
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $ticket->ticket])
             ->assertUnprocessable()
             ->assertJsonValidationErrors('ticket');
         $this->assertNull($ticket->fresh()->used_at);
+        $this->assertDatabaseHas('scan_attempts', [
+            'scanner_user_id' => $this->scanner->id,
+            'ticket_id' => $ticket->id,
+            'result' => ScanAttemptResult::CategoryForbidden->value,
+        ]);
     }
 
     public function test_scanner_can_read_and_scan_any_category_when_tenant_disables_validation(): void
@@ -274,9 +383,9 @@ class ScannerTicketControllerTest extends TestCase
             ->assertOk()
             ->assertJsonPath('data.id', $ticket->id);
 
-        $this->postJson("/api/v1/scanner/tickets/{$ticket->ticket}/scan")
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $ticket->ticket])
             ->assertOk()
-            ->assertJsonPath('data.scanner_user_id', $this->scanner->id);
+            ->assertJsonPath('data.ticket.scanner_user_id', $this->scanner->id);
     }
 
     public function test_disabled_category_validation_does_not_allow_scanning_another_tenant(): void
@@ -297,8 +406,15 @@ class ScannerTicketControllerTest extends TestCase
 
         $this->getJson("/api/v1/scanner/tickets/{$foreignTicket->ticket}")
             ->assertNotFound();
-        $this->postJson("/api/v1/scanner/tickets/{$foreignTicket->ticket}/scan")
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $foreignTicket->ticket])
             ->assertNotFound();
+        $this->assertDatabaseHas('scan_attempts', [
+            'tenant_code' => $this->tenant->codigo,
+            'scanner_user_id' => $this->scanner->id,
+            'ticket_id' => null,
+            'data' => $foreignTicket->ticket,
+            'result' => ScanAttemptResult::TicketNotFound->value,
+        ]);
     }
 
     public function test_adminapp_cannot_access_scanner_routes_even_with_scan_permission(): void
@@ -311,10 +427,30 @@ class ScannerTicketControllerTest extends TestCase
         $ticket = $this->createTicket((string) Str::uuid());
         Sanctum::actingAs($admin);
 
-        $this->getJson('/api/v1/scanner/tickets')->assertForbidden();
+        $this->getJson('/api/v1/scanner/attempts')->assertForbidden();
         $this->getJson("/api/v1/scanner/tickets/{$ticket->ticket}")->assertForbidden();
-        $this->postJson("/api/v1/scanner/tickets/{$ticket->ticket}/scan")->assertForbidden();
+        $this->postJson('/api/v1/scanner/tickets/scan', ['data' => $ticket->ticket])->assertForbidden();
         $this->assertNull($ticket->fresh()->used_at);
+        $this->assertDatabaseCount('scan_attempts', 0);
+    }
+
+    /** @param array<string, mixed> $attributes */
+    private function createScanAttempt(
+        ?string $data,
+        array $attributes = [],
+        ?User $scanner = null,
+    ): ScanAttempt {
+        $scanAttempt = new ScanAttempt;
+        $scanAttempt->forceFill(array_merge([
+            'tenant_code' => $this->tenant->codigo,
+            'scanner_user_id' => ($scanner ?? $this->scanner)->id,
+            'data' => $data,
+            'result' => ScanAttemptResult::Accepted,
+            'resolved_at' => now(),
+        ], $attributes));
+        $scanAttempt->save();
+
+        return $scanAttempt;
     }
 
     /** @param array<string, mixed> $attributes */