Al inicio puede parecer práctico resolver todo dentro del controller, pero con el tiempo esa decisión vuelve más difícil mantener, probar y escalar el proyecto. Por eso conviene separar responsabilidades entre Controllers, Form Requests, Services y Models.

La idea no es complicar la arquitectura, sino poner cada pieza en el lugar correcto.

Resumen rápido

Una forma sencilla de entenderlo es esta:

En otras palabras:

Request
  ↓
Form Request
  ↓
Controller
  ↓
Service
  ↓
Model / Base de datos
  ↓
Response

Qué es un Controller en Laravel

Un controller agrupa la lógica que responde a peticiones HTTP relacionadas con un recurso. Laravel recomienda usarlos para organizar el manejo de solicitudes que, de otra forma, terminarían como closures dentro de las rutas.

El controller debe actuar como coordinador. No debería cargar toda la lógica de negocio del sistema.

Responsabilidades recomendadas de un controller

• Recibir la petición.
• Usar un Form Request para validar.
• Buscar un modelo cuando sea algo simple.
• Llamar un Service cuando haya lógica de negocio.
• Regresar una vista, redirect o respuesta JSON.

Ejemplo de controller limpio

public function update(UpdateProductRequest $request, string $product)
{
    $product = Product::find($product);

    $product = $this->productService->update(
        $product,
        $request->validated()
    );

    return response()->json([
        'success' => true,
        'message' => 'Producto actualizado correctamente.',
        'product' => [
            'id' => $product->id,
            'name' => $product->name,
        ],
    ]);
}

Este controller no sabe todos los detalles de cómo se actualiza el producto. Solo controla el flujo.

Eso lo hace más fácil de leer, mantener y modificar.

Qué es un Form Request

Un Form Request es una clase especializada para validar y autorizar datos de entrada. Laravel permite crear estos archivos para encapsular validación y autorización en un lugar separado del controller.

Esto evita que el controller se llene de reglas como required, exists, max, email, validaciones condicionales o preparación de datos.

Responsabilidades recomendadas de un Form Request

• Validar campos requeridos.
• Validar formatos.
• Validar existencia de registros en base de datos.
• Preparar datos antes de validar.
• Autorizar si el usuario puede ejecutar la acción.

Ejemplo de Form Request

class UpdateProductRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'product_id' => ['required', 'integer', 'exists:products,id'],
            'name' => ['required', 'string', 'max:255'],
            'price' => ['required', 'numeric', 'min:0'],
        ];
    }

    public function authorize(): bool
    {
        return true;
    }
}

El controller ya no necesita preocuparse por esa preparación.

Qué es un Service

Un Service es una clase donde se concentra la lógica de negocio o los procesos importantes del sistema. Aunque Laravel no obliga a crear una carpeta Services, el framework sí facilita este patrón gracias a su Service Container y a la inyección de dependencias.

La pregunta clave para decidir si algo va a un Service es:

¿Esto solo controla una petición HTTP o representa una operación importante del negocio?

Si representa una operación del negocio, normalmente conviene moverlo a un Service.

Responsabilidades recomendadas de un Service

• Crear registros.
• Actualizar registros.
• Eliminar registros.
• Ejecutar transacciones.
• Aplicar reglas de negocio.
• Coordinar varias tablas.
• Calcular importes, descuentos, comisiones o estados.
• Consumir APIs externas.
• Disparar notificaciones, eventos o procesos relacionados.

Ejemplo de Service

class ProductService
{
    public function create(array $data): Product
    {
        return DB::transaction(function () use ($data) {
            return Product::create([
                'name' => $data['name'],
                'description' => $data['description'] ?? null,
                'price' => $data['price'],
                'enabled' => $data['enabled'] ?? true,
            ]);
        });
    }

    public function update(Product $product, array $data): Product
    {
        return DB::transaction(function () use ($product, $data) {
            $product->name = $data['name'];
            $product->description = $data['description'] ?? null;
            $product->price = $data['price'];
            $product->enabled = $data['enabled'] ?? $product->enabled;
            $product->save();

            return $product->fresh();
        });
    }

    public function delete(Product $product): void
    {
        DB::transaction(function () use ($product) {
            $product->delete();
        });
    }
}

Aunque algunos métodos parezcan simples al inicio, tenerlos en un Service permite que crezcan ordenadamente. Hoy un delete() puede borrar un registro; mañana puede validar permisos internos, eliminar relaciones, registrar historial y disparar una notificación.

Qué es un Model en Laravel

Un Model representa una tabla de base de datos dentro de Eloquent. Laravel indica que cada tabla suele tener un modelo correspondiente, y que estos modelos permiten consultar, insertar, actualizar y eliminar registros.

Pero eso no significa que toda la lógica de negocio deba vivir dentro del Model.

Responsabilidades recomendadas de un Model

• Definir la tabla si no sigue la convención.
• Definir campos fillable o guarded.
• Definir relaciones.
• Definir casts.
• Crear accessors y mutators.
• Crear scopes reutilizables.
• Agregar métodos simples propios de la entidad.

Ejemplo de Model

class Product extends Model
{
    protected $fillable = [
        'name',
        'description',
        'price',
        'enabled',
    ];

    protected function casts(): array
    {
        return [
            'price' => 'decimal:2',
            'enabled' => 'boolean',
        ];
    }

    public function scopeEnabled($query)
    {
        return $query->where('enabled', true);
    }

    public function isAvailable(): bool
    {
        return $this->enabled === true;
    }
}

Este tipo de lógica sí pertenece al modelo porque describe el comportamiento directo de la entidad Product.

En cambio, si el proceso implica cobrar, registrar historial, enviar notificaciones y actualizar varias tablas, eso ya debería ir a un Service.

Cuándo usar cada uno

Usa Controller cuando…

• Necesitas recibir una petición HTTP.
• Necesitas devolver una vista.
• Necesitas devolver JSON.
• Necesitas redireccionar.
• La acción solo coordina otras piezas.

public function index()
{
    $products = Product::enabled()
        ->orderBy('name')
        ->paginate(20);

    return view('products.index', compact('products'));
}

Una consulta sencilla para mostrar datos puede quedarse en el controller.

Usa Form Request cuando…

• Hay reglas de validación.
• Hay autorización de la acción.
• Necesitas preparar datos antes de validarlos.
• Quieres evitar que el controller se llene de reglas.

public function rules(): array
{
    return [
        'name' => ['required', 'string', 'max:255'],
        'email' => ['required', 'email'],
    ];
}

Usa Service cuando…

• La acción crea, actualiza o elimina información importante.
• La acción toca varias tablas.
• La lógica se reutilizará desde varios lugares.
• Hay transacciones.
• Hay integración con APIs externas.
• Hay reglas de negocio.

$order = $this->orderService->create($request->validated());

Usa Model cuando…

• Necesitas definir relaciones.
• Necesitas casts.
• Necesitas scopes.
• Necesitas accessors o mutators.
• Necesitas métodos simples de la entidad.

public function scopeEnabled($query)
{
    return $query->where('enabled', true);
}

Ejemplo completo: creación de una orden

Supongamos que tenemos un sistema donde un cliente puede crear una orden. La orden debe guardar productos, calcular total, registrar pagos pendientes y devolver una respuesta.

Si todo se mete en el controller, el método puede volverse enorme. Una mejor separación sería:

Ruta

Route::post('/orders', [OrderController::class, 'store'])
    ->name('orders.store');

Controller

class OrderController extends Controller
{
    public function __construct(
        private readonly OrderService $orderService
    ) {}

    public function store(StoreOrderRequest $request)
    {
        $order = $this->orderService->create($request->validated());

        return response()->json([
            'success' => true,
            'message' => 'Orden creada correctamente.',
            'order' => [
                'id' => $order->id,
                'total' => $order->total,
            ],
        ]);
    }
}

Form Request

class StoreOrderRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'customer_name' => ['required', 'string', 'max:255'],
            'items' => ['required', 'array', 'min:1'],
            'items.*.product_id' => ['required', 'integer', 'exists:products,id'],
            'items.*.quantity' => ['required', 'integer', 'min:1'],
        ];
    }
}

Service

class OrderService
{
    public function create(array $data): Order
    {
        return DB::transaction(function () use ($data) {
            $order = Order::create([
                'customer_name' => $data['customer_name'],
                'total' => 0,
                'status' => 'pending',
            ]);

            $total = 0;

            foreach ($data['items'] as $item) {
                $product = Product::findOrFail($item['product_id']);
                $subtotal = $product->price * $item['quantity'];

                $order->items()->create([
                    'product_id' => $product->id,
                    'quantity' => $item['quantity'],
                    'unit_price' => $product->price,
                    'subtotal' => $subtotal,
                ]);

                $total += $subtotal;
            }

            $order->update([
                'total' => $total,
            ]);

            return $order->fresh();
        });
    }
}

Model

class Order extends Model
{
    protected $fillable = [
        'customer_name',
        'total',
        'status',
    ];

    protected function casts(): array
    {
        return [
            'total' => 'decimal:2',
        ];
    }

    public function items()
    {
        return $this->hasMany(OrderItem::class);
    }

    public function isPending(): bool
    {
        return $this->status === 'pending';
    }
}

Con esta estructura, cada clase tiene una responsabilidad clara.

El controller no calcula totales. El Form Request no guarda datos. El Service no genera respuestas HTTP. El Model no se encarga de coordinar todo el proceso.

Errores comunes al separar responsabilidades

1. Crear Services para todo

No todas las acciones necesitan un Service. Si solo vas a mostrar una vista con una consulta sencilla, el controller puede hacerlo.

2. Meter validaciones en el Service

La validación de entrada normalmente debe vivir en un Form Request. El Service debe recibir datos ya validados y ejecutar el proceso.

3. Regresar respuestas HTTP desde el Service

El Service no debería regresar response()->json() ni redirects. Eso le corresponde al controller.

4. Convertir el Model en una clase gigante

El Model debe representar la entidad, pero no coordinar procesos completos del sistema. Si una operación toca varias entidades o APIs externas, probablemente debe vivir en un Service.

5. No usar transacciones en procesos críticos

Cuando una operación crea o actualiza varios registros relacionados, conviene usar transacciones para evitar datos incompletos si algo falla a mitad del proceso.

Regla práctica para proyectos Laravel

Una convención sencilla para mantener el orden es esta:

Si una acción crea, actualiza o elimina información importante de la base de datos, o representa un proceso del negocio, la lógica principal debe ir en un Service.

Esto no significa que el controller nunca pueda consultar modelos. Para listados simples, vistas de edición o pantallas informativas, puede ser totalmente válido.

Pero cuando el método empieza a tener transacciones, ciclos, cálculos, integraciones, actualizaciones en varias tablas o condiciones del negocio, es momento de mover esa lógica a un Service.

Guía rápida

Conclusión

Separar Controllers, Form Requests, Services y Models no es solo una cuestión de estilo. Es una forma de mantener proyectos Laravel más claros, escalables y fáciles de modificar.

Un controller debe controlar el flujo de la petición. Un Form Request debe validar y preparar datos. Un Service debe ejecutar la lógica de negocio. Un Model debe representar la entidad y su relación con la base de datos.

La meta no es crear más archivos sin razón, sino evitar que una sola clase tenga demasiadas responsabilidades.

Cuando cada pieza cumple su función, el código se vuelve más fácil de leer, probar y mantener.

Fuentes consultadas

• Laravel Documentation: Controllers
• Laravel Documentation: Form Request Validation
• Laravel Documentation: Preparing Input for Validation
• Laravel Documentation: Service Container
• Laravel Documentation: Eloquent ORM

En este artículo explicaremos de forma práctica cuándo usar GET, cuándo usar POST y por qué no todas las acciones deberían ejecutarse desde un simple enlace.

La regla básica

Una forma sencilla de verlo es la siguiente:

GET  → consultar, mostrar o leer información.
POST → enviar información, ejecutar acciones o modificar el estado del sistema.

Esta diferencia es importante porque no todos los accesos a una URL deberían tener consecuencias dentro del sistema. Una ruta que solamente muestra información puede trabajar con GET. En cambio, una ruta que guarda, actualiza, elimina o dispara un proceso debería utilizar POST u otro método apropiado.

Cuándo usar GET

El método GET se utiliza principalmente para consultar información. Es decir, cuando el usuario entra a una URL y espera ver datos, una página, un listado o un formulario, pero sin modificar nada en el sistema.

Ejemplos comunes de rutas que sí pueden usar GET:

• Mostrar el listado de productos.
• Ver el detalle de un pedido.
• Abrir un formulario de registro.
• Consultar reportes.
• Filtrar información en una tabla.
• Mostrar una pantalla de configuración.

Ejemplo genérico en Laravel:

Route::get('/admin/productos', [ProductController::class, 'index'])
    ->name('admin.products.index');

En este caso, la ruta solamente muestra información. No guarda datos, no elimina registros y no dispara procesos internos. Por eso GET es adecuado.

Cuándo usar POST

El método POST se utiliza cuando el usuario va a enviar información o cuando una acción puede modificar el estado de la aplicación.

Ejemplos comunes de acciones que deberían usar POST:

• Guardar un producto.
• Crear un pedido.
• Registrar un cliente.
• Enviar un formulario.
• Ejecutar una sincronización.
• Procesar información externa.
• Generar una acción administrativa.

Ejemplo genérico:

Route::post('/admin/productos', [ProductController::class, 'store'])
    ->name('admin.products.store');

Aquí la ruta recibe información y crea un nuevo registro. Por lo tanto, usar POST es lo correcto.

¿Y si no estoy enviando parámetros?

Una duda común aparece cuando tenemos un botón que no envía datos visibles, pero sí ejecuta una acción. Por ejemplo:

• Sincronizar productos.
• Procesar pedidos pendientes.
• Actualizar inventario.
• Ejecutar una tarea interna.

En estos casos podría parecer práctico usar un enlace con href y una ruta GET, porque no estamos enviando campos de formulario. Sin embargo, la decisión no depende solamente de si enviamos parámetros, sino de lo que ocurre cuando se visita la URL.

Si al abrir la URL se ejecuta un proceso, se modifica información o se cambia el estado del sistema, entonces no debería ser GET. Debería ser POST.

Ejemplo: ejecutar una sincronización

Supongamos que tenemos una aplicación administrativa y queremos agregar un botón para sincronizar información con un servicio externo.

Una opción incorrecta sería hacerlo así:

<a href="/admin/sincronizar-productos" class="btn btn-primary">
    Sincronizar productos
</a>

Y definir la ruta como GET:

Route::get('/admin/sincronizar-productos', [SyncController::class, 'syncProducts']);

El problema es que esa URL ejecuta un proceso. No solo muestra información. Por lo tanto, puede activarse accidentalmente si el usuario recarga la página, abre el enlace en otra pestaña, el navegador intenta previsualizarlo o incluso si algún rastreador accede a esa URL.

La forma más adecuada sería usar una ruta POST:

Route::post('/admin/sincronizar-productos', [SyncController::class, 'syncProducts'])
    ->name('admin.products.sync');

Y ejecutarla desde un formulario:

<form action="{{ route('admin.products.sync') }}" method="POST">
    @csrf

    <button type="submit" class="btn btn-primary">
        Sincronizar productos
    </button>
</form>

Aunque el formulario no envíe campos adicionales, el uso de POST comunica correctamente que se trata de una acción, no de una simple consulta.

Por qué evitar GET para acciones importantes

Usar GET para ejecutar acciones puede provocar varios problemas:

• La acción puede ejecutarse accidentalmente al recargar la página.
• La URL puede compartirse o abrirse sin intención.
• Un navegador puede intentar previsualizar o precargar el enlace.
• Un bot o rastreador podría visitar la ruta.
• No se aprovecha la protección CSRF de la misma manera que con formularios POST.
• Se rompe la semántica de la aplicación, porque una consulta termina modificando el sistema.

Por eso, aunque usar GET pueda parecer más cómodo visualmente, no siempre es la opción correcta.

La importancia del CSRF

En frameworks como Laravel, los formularios POST suelen incluir un token CSRF para validar que la petición realmente fue generada desde la aplicación y no desde un sitio externo.

Ejemplo:

<form action="{{ route('admin.products.sync') }}" method="POST">
    @csrf

    <button type="submit">
        Ejecutar sincronización
    </button>
</form>

La directiva @csrf genera un token oculto que Laravel verifica al recibir la solicitud. Esto ayuda a proteger acciones sensibles como guardar información, eliminar registros o ejecutar procesos administrativos.

¿Qué pasa si el formulario afecta el diseño?

En ocasiones se evita usar un formulario porque visualmente no encaja bien dentro de un grupo de botones o dentro de una interfaz administrativa. Sin embargo, ese es un problema de presentación, no de arquitectura.

Podemos mantener el método correcto y ajustar el diseño con CSS:

<div class="btn-group" role="group">
    <a href="{{ route('admin.products.index') }}" class="btn btn-secondary">
        Regresar
    </a>

    <form action="{{ route('admin.products.sync') }}" method="POST" class="m-0 d-inline">
        @csrf
        <button type="submit" class="btn btn-primary">
            Sincronizar
        </button>
    </form>
</div>

También puede resolverse con una petición AJAX usando fetch, manteniendo el método POST y enviando el token CSRF en los encabezados.

<button type="button" id="btn-sync" class="btn btn-primary">
    Sincronizar
</button>

<script>
document.getElementById('btn-sync').addEventListener('click', function () {
    fetch('/admin/sincronizar-productos', {
        method: 'POST',
        headers: {
            'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content,
            'Accept': 'application/json'
        }
    });
});
</script>

Lo importante es no cambiar a GET solo porque estéticamente es más cómodo usar un enlace.

GET no debe tener efectos secundarios

Una buena práctica es que las rutas GET no tengan efectos secundarios importantes. Es decir, visitar una URL con GET no debería crear registros, eliminar información, actualizar inventario ni ejecutar procesos internos.

Por ejemplo, estas rutas deberían evitarse:

GET /admin/eliminar-producto/10
GET /admin/procesar-pedidos
GET /admin/sincronizar-inventario
GET /admin/ejecutar-comando

Aunque técnicamente puedan funcionar, no son una buena práctica porque una simple visita a la URL puede cambiar el estado del sistema.

Entonces, ¿cuándo usar cada uno?

Más allá de GET y POST

En aplicaciones modernas también es común utilizar otros métodos HTTP:

• PUT: para actualizar completamente un recurso.
• PATCH: para actualizar parcialmente un recurso.
• DELETE: para eliminar un recurso.

Sin embargo, en formularios HTML tradicionales normalmente se trabaja con GET y POST. Frameworks como Laravel permiten simular métodos como PUT, PATCH o DELETE mediante campos ocultos.

<form action="{{ route('admin.products.destroy', $product) }}" method="POST">
    @csrf
    @method('DELETE')
    <button type="submit">
        Eliminar producto
    </button>
</form>

Esto permite mantener una estructura más clara y alineada con las buenas prácticas de desarrollo web.

Ejemplo práctico de flujo correcto

Supongamos que tenemos un módulo de pedidos y necesitamos estas acciones:

GET    /admin/pedidos              → Mostrar pedidos
GET    /admin/pedidos/15           → Ver detalle del pedido
GET    /admin/pedidos/create       → Mostrar formulario
POST   /admin/pedidos              → Guardar pedido
POST   /admin/pedidos/sincronizar  → Ejecutar sincronización
DELETE /admin/pedidos/15           → Eliminar pedido

Este tipo de estructura permite entender rápidamente qué hace cada ruta y qué impacto tiene dentro de la aplicación.

Conclusión

Elegir entre GET y POST no debería depender únicamente de si enviamos parámetros o de qué opción se ve mejor en la interfaz. La decisión debe basarse en la intención de la ruta.

Si la ruta solo consulta o muestra información, GET es correcto. Si la ruta guarda, modifica, elimina o ejecuta un proceso dentro del sistema, entonces debe usarse POST u otro método adecuado.

En proyectos reales, esta diferencia ayuda a construir aplicaciones más seguras, ordenadas y fáciles de mantener. Además, evita que acciones importantes se ejecuten accidentalmente desde una URL que debería ser únicamente de consulta.

La interfaz siempre se puede ajustar con CSS o JavaScript, pero la intención técnica de una ruta debe mantenerse clara desde el diseño de la aplicación.

Mantener actualizado el inventario entre un sistema interno y una plataforma externa es una tarea clave para cualquier negocio que vende productos en distintos canales. Cuando el stock no se sincroniza correctamente, pueden aparecer problemas como ventas sin existencia, información desactualizada o diferencias entre lo que ve el cliente y lo que realmente existe en almacén.

El reto de sincronizar inventario

En muchos sistemas, el inventario principal se administra desde una aplicación interna. Esta aplicación puede controlar productos, almacenes, existencias, movimientos, pedidos y configuraciones propias del negocio.

Por otro lado, una plataforma externa puede funcionar como canal de venta, catálogo público o punto de contacto con los clientes. El problema aparece cuando el stock cambia dentro del sistema interno, pero esa actualización no llega de inmediato a la plataforma externa.

Esto puede provocar que un producto aparezca disponible cuando realmente ya no hay existencias, o que el equipo operativo tenga que corregir manualmente la información en más de un lugar.

Por eso es importante diseñar un proceso de sincronización que permita mantener ambos sistemas alineados.

Definir una fuente principal de información

Antes de implementar la sincronización, es necesario definir qué sistema será la fuente principal del stock.

En la mayoría de los casos, el sistema interno debe ser la fuente confiable, ya que ahí se registran los movimientos reales de inventario. La plataforma externa solo debería recibir el dato actualizado.

Este principio evita conflictos como:

• Actualizar stock desde dos lugares diferentes.
• Sobrescribir información correcta con datos desactualizados.
• Perder control sobre qué sistema tiene la información válida.
• Generar diferencias entre almacenes y publicaciones externas.

Cuando el sistema interno es la fuente principal, la sincronización se vuelve más clara: se calcula el stock disponible internamente y después se envía hacia la plataforma externa.

Relacionar productos internos con elementos externos

Un paso fundamental es relacionar cada producto interno con su equivalente en la plataforma externa.

No se debe enviar stock si no existe una relación clara entre ambos elementos. De lo contrario, el sistema podría actualizar el producto equivocado o enviar información incorrecta.

Una relación puede contener datos generales como:

• Identificador del producto interno.
• Identificador del elemento externo.
• Estado de la relación.
• Última fecha de sincronización.
• Stock enviado más recientemente.

Esta relación permite saber qué elementos pueden sincronizarse y cuáles necesitan revisión antes de participar en el proceso.

Obtener el stock correcto

Cuando el sistema interno maneja varios almacenes, no siempre conviene enviar el stock total de todos ellos. En algunos casos, la plataforma externa debe trabajar únicamente con un almacén específico.

Por ejemplo, una empresa puede tener inventario en sucursales, almacenes físicos o puntos de distribución diferentes. La sincronización debe respetar la configuración del negocio y tomar el stock desde el almacén autorizado para ese canal.

También es recomendable validar que el stock enviado nunca sea negativo. Si el sistema interno llegara a tener un valor menor que cero por algún ajuste o movimiento pendiente, lo más seguro es enviar cero a la plataforma externa.

Separar la lógica usando Jobs

En Laravel, una buena práctica es separar este tipo de procesos en Jobs.

Un Job permite ejecutar la sincronización sin cargar toda la lógica dentro del controlador. Esto hace que el código sea más ordenado, más fácil de mantener y más flexible.

El flujo general puede verse así:

Usuario o tarea programada inicia la sincronización
↓
Laravel dispara un Job
↓
El Job busca productos relacionados
↓
Calcula el stock interno
↓
Envía la información al servicio externo
↓
Registra el resultado

Esta estructura permite ejecutar la misma lógica desde distintos puntos, como un botón manual, una tarea programada o un comando de consola.

Usar un servicio para comunicarse con la plataforma externa

La comunicación con la API externa debería estar aislada en una clase de servicio.

Esto evita que el controlador o el Job tengan demasiada responsabilidad. El servicio puede encargarse de preparar la petición, enviar el stock, interpretar la respuesta y devolver un resultado claro.

De forma conceptual, el servicio debería realizar estas tareas:

• Validar que exista una configuración activa.
• Obtener el token o credenciales necesarias.
• Enviar la cantidad disponible a la plataforma externa.
• Revisar si la respuesta fue exitosa.
• Detectar errores conocidos.
• Devolver el resultado al proceso principal.

Separar esta lógica facilita futuras modificaciones, especialmente si la plataforma externa cambia sus reglas, endpoints o formato de respuesta.

Actualizar información local solo cuando la API responda correctamente

Una parte importante del proceso es no asumir que la sincronización fue exitosa solo porque se envió una petición.

La plataforma externa puede rechazar el cambio por varias razones: credenciales inválidas, producto no encontrado, permisos insuficientes, reglas del canal o restricciones sobre ciertos campos.

Por eso, el sistema interno solo debería actualizar su registro local de “último stock sincronizado” cuando la API confirme que la operación fue aceptada.

Esto evita mostrar información incorrecta dentro del sistema administrativo.

Registrar una bitácora de sincronización

Toda integración con servicios externos debería contar con una bitácora.

La bitácora permite saber qué ocurrió en cada intento de sincronización. Esto es útil para auditoría, soporte y diagnóstico de errores.

Una buena bitácora puede registrar información como:

• Fecha del intento.
• Producto interno relacionado.
• Elemento externo actualizado.
• Stock calculado internamente.
• Stock enviado a la plataforma externa.
• Estado de la operación.
• Código de respuesta.
• Mensaje descriptivo del resultado.

Con esta información, el equipo puede saber si una actualización fue exitosa, si la plataforma externa rechazó el cambio o si ocurrió un problema de configuración.

Mostrar la bitácora en el panel administrativo

Guardar la bitácora en la base de datos es útil, pero mostrarla en la interfaz administrativa mejora mucho la experiencia del usuario.

Una pestaña de historial o bitácora permite revisar rápidamente los últimos intentos de sincronización sin entrar directamente a la base de datos.

Esta sección puede mostrar columnas como:

• Fecha.
• Producto.
• Stock interno.
• Stock enviado.
• Estado.
• Código de respuesta.
• Mensaje.

De esta manera, el usuario puede identificar rápidamente si una sincronización fue exitosa o si necesita atención.

Sincronización automática y sincronización manual

Una sincronización puede ejecutarse de forma automática mediante tareas programadas. Esto ayuda a mantener el inventario actualizado sin intervención constante del usuario.

Sin embargo, también es útil contar con una opción manual desde el panel administrativo.

El botón manual no reemplaza el proceso automático, sino que lo complementa. Puede servir cuando el usuario necesita actualizar el stock inmediatamente después de hacer cambios importantes en el inventario o en las relaciones con la plataforma externa.

Para evitar ejecuciones accidentales, conviene mostrar una confirmación antes de iniciar el proceso.

Manejo de errores

No todos los errores significan que la lógica interna esté mal. A veces la plataforma externa rechaza una actualización por sus propias reglas.

Algunos casos comunes son:

• Token expirado.
• Permisos insuficientes.
• Producto externo no encontrado.
• Campo no editable.
• Restricciones por estado del producto.
• Errores temporales del servicio externo.

Por eso es importante que el sistema muestre mensajes claros y registre la respuesta técnica para diagnóstico.

Un mensaje útil para el usuario debe explicar el problema sin saturarlo con detalles técnicos innecesarios.

Buenas prácticas

Al implementar sincronización de stock entre un sistema interno y una plataforma externa, conviene aplicar estas buenas prácticas:

• Definir claramente cuál sistema es la fuente principal del inventario.
• Sincronizar solo productos correctamente relacionados.
• Tomar el stock desde el almacén configurado.
• Evitar enviar cantidades negativas.
• Separar responsabilidades usando controladores, Jobs y servicios.
• Registrar cada intento en una bitácora.
• Actualizar datos locales solo cuando la API confirme éxito.
• Mostrar resultados de sincronización en el panel administrativo.
• Manejar errores de forma clara.
• Mantener una opción manual como apoyo al proceso automático.

Conclusión

Sincronizar stock entre un sistema interno y una plataforma externa no consiste solamente en enviar una cantidad mediante una API. También implica validar relaciones, respetar configuraciones, manejar errores, registrar evidencia y mantener consistencia entre ambos sistemas.

Laravel ofrece herramientas muy útiles para construir este tipo de procesos de forma ordenada, como Jobs, servicios, comandos de consola, tareas programadas y manejo de peticiones HTTP.

Una implementación bien diseñada permite que el sistema interno conserve el control principal del inventario, mientras la plataforma externa recibe actualizaciones confiables y trazables.

El resultado es una integración más segura, más fácil de mantener y más útil para los usuarios que necesitan operar productos en diferentes canales de venta.

Sin embargo, también puede pasar que una rama se cree desde una base incorrecta. Por ejemplo, en lugar de crear una nueva rama desde main, se crea desde otra rama de desarrollo que todavía no está lista para integrarse. Cuando esto ocurre, el Pull Request puede mostrar muchos commits adicionales que no pertenecen realmente al cambio que queremos subir.

El problema

Supongamos que tenemos una rama principal:

main

También existe una rama de desarrollo para una integración grande:

feature/integracion-api

Después se crea una nueva rama para una funcionalidad más pequeña, por ejemplo el registro del costo de envío:

feature/integracion-envios

El detalle es que esta última rama fue creada accidentalmente desde feature/integracion-api y no desde main. Entonces, al intentar crear un Pull Request hacia main, GitHub muestra que se van a aplicar muchos commits adicionales.

En ese punto la señal de alerta es clara: si la funcionalidad era pequeña, pero el Pull Request muestra demasiados commits o archivos que no corresponden, no conviene hacer el merge todavía.

Por qué no era buena idea hacer el merge directo

Si se hacía el merge directo de feature/integracion-envios hacia main, también se podían integrar cambios incompletos de la rama feature/integracion-api. Esto habría mezclado funcionalidades distintas y pudo provocar errores en producción o en el ambiente de pruebas.

El objetivo era integrar únicamente los commits relacionados con el registro del costo de envío, sin arrastrar el trabajo de otra rama.

La solución: crear una rama limpia desde main

La solución fue crear una nueva rama partiendo correctamente desde main y después aplicar únicamente los commits necesarios usando git cherry-pick.

El comando git cherry-pick permite tomar uno o varios commits específicos de otra rama y aplicarlos sobre la rama actual. Esto resulta útil cuando queremos rescatar cambios puntuales sin mezclar todo el historial de la rama original.

1. Actualizar la información del repositorio

Primero se actualiza la información del repositorio remoto:

git fetch origin

Este comando descarga las referencias más recientes de las ramas remotas, sin modificar directamente el código de la rama actual.

2. Cambiar a main y actualizarla

Después se cambia a la rama principal y se actualiza con los últimos cambios disponibles:

git checkout main
git pull origin main

Esto asegura que la nueva rama limpia se cree desde la versión más reciente de main.

3. Crear una nueva rama limpia

Con main actualizada, se crea una nueva rama limpia para la funcionalidad:

git checkout -b feature/integracion-envios-clean

Esta nueva rama ya no tendrá como base la rama de integración grande, sino directamente main.

4. Identificar los commits correctos

El siguiente paso es identificar los commits que realmente corresponden a la funcionalidad de envíos.

git log --oneline origin/feature/integracion-api..origin/feature/integracion-envios

Este comando ayuda a visualizar los commits que existen en la rama de envíos, pero que no forman parte de la rama base desde la que fue creada.

El resultado puede ser algo como:

abc1234 Agrega campo de costo de envío al pedido
def5678 Ajusta cálculo total incluyendo envío

En este ejemplo, esos dos commits serían los únicos que realmente se necesitan aplicar en la rama limpia.

5. Aplicar los commits con cherry-pick

Una vez identificados los commits correctos, se aplican sobre la rama limpia:

git cherry-pick abc1234 def5678

Con esto, Git toma los cambios introducidos por esos commits y los aplica sobre la rama actual, generando nuevos commits con esos mismos cambios.

Si durante el proceso aparecen conflictos, se deben resolver manualmente, agregar los archivos corregidos y continuar el cherry-pick:

git add .
git cherry-pick --continue

Si fuera necesario cancelar el proceso, se puede usar:

git cherry-pick --abort

6. Revisar los cambios antes de subir la rama

Antes de subir la nueva rama, se revisa el estado del repositorio:

git status

También es recomendable revisar qué archivos quedaron modificados:

git diff --name-only main...feature/integracion-envios-clean

La idea es confirmar que la rama limpia solo contiene archivos relacionados con la funcionalidad que se quiere integrar.

7. Subir la rama limpia al repositorio remoto

Una vez revisado todo, se sube la nueva rama a GitHub:

git push -u origin feature/integracion-envios-clean

Después de esto, ya es posible crear un nuevo Pull Request desde la rama limpia hacia main.

8. Crear el Pull Request correcto

En GitHub, el nuevo Pull Request debe quedar configurado de esta forma:

base: main
compare: feature/integracion-envios-clean

Ahora el Pull Request mostrará únicamente los commits necesarios y los archivos relacionados con el registro del costo de envío.

Esto permite hacer una revisión más clara, evitar mezclar funcionalidades y mantener la rama main limpia.

Flujo completo de comandos

El flujo completo quedaría de la siguiente manera:

git fetch origin

git checkout main
git pull origin main

git checkout -b feature/integracion-envios-clean

git log --oneline origin/feature/integracion-api..origin/feature/integracion-envios

git cherry-pick abc1234 def5678

git status

git diff --name-only main...feature/integracion-envios-clean

git push -u origin feature/integracion-envios-clean

Buenas prácticas para evitar este problema

Antes de empezar una nueva funcionalidad, es recomendable seguir este flujo:

git checkout main
git pull origin main
git checkout -b feature/nueva-funcionalidad

También conviene revisar la rama actual antes de crear una nueva:

git branch --show-current

Con este pequeño hábito se evitan muchos problemas al momento de crear Pull Requests.

Conclusión

Cuando una rama se crea desde la base incorrecta, no siempre es necesario rehacer todo el trabajo. Si los cambios están organizados en commits claros, podemos crear una rama limpia desde main y aplicar únicamente los commits necesarios con git cherry-pick.

En este caso, la solución fue evitar el merge directo, crear una nueva rama limpia, aplicar los commits correctos y generar un Pull Request más claro y seguro. Esto permitió integrar la funcionalidad sin arrastrar cambios de otra rama que todavía no estaba lista.

Este tipo de situaciones son comunes en proyectos reales, y aprender a resolverlas correctamente ayuda a mantener un historial limpio, reducir errores y mejorar el flujo de trabajo en equipo.

En este caso, el origen del problema estaba relacionado con Iconify, específicamente con el archivo iconify-icon.js y el uso de IntersectionObserver para renderizar o remover iconos dependiendo de si están visibles en pantalla.

El síntoma

El problema aparece únicamente en páginas con altura considerable, donde era necesario hacer scroll para revisar el contenido. Al avanzar hacia abajo, llegaba un punto en el que la pantalla se quedaba “atorada” y comenzaba a “saltar”, como si intentara regresar a una posición anterior.

Después de realizar un rastreo y de varias pruebas, el comportamiento desaparecía al quitar el archivo:

<script src="/assets/js/iconify-icon.js"></script>

Esto permitió confirmar que el problema no estaba en Bootstrap, DataTables, CSS personalizado ni en el layout principal, sino en la forma en que Iconify estaba administrando los iconos durante el scroll.

Por qué sucede

Algunas versiones de iconify-icon.js usan IntersectionObserver para detectar si un icono está visible dentro del viewport. Cuando el icono sale de pantalla, el script puede remover el SVG renderizado; cuando vuelve a entrar, lo renderiza nuevamente.

El comportamiento problemático se encuentra en una lógica similar a esta:

    this._observer = new IntersectionObserver((entries) => {
        const isVisible = entries.some((entry) => entry.isIntersecting);

        if (isVisible !== this._visible) {
            this._visible = isVisible;
            this._forceRender();
        }
    });
    

Y dentro de _forceRender() puede existir una lógica que elimina el icono del Shadow DOM cuando ya no está visible:

    _forceRender() {
        if (this._visible) {
            this._queueCheck();
        } else {
            const element = getRenderedIcon(this._shadowRoot);

            if (element) {
                this._shadowRoot.removeChild(element);
            }
        }
    }

En teoría, esto busca optimizar el rendimiento. Pero en páginas largas, con muchos iconos y contenido dinámico, puede causar el efecto contrario: cada vez que el usuario hace scroll, el script modifica el DOM, el navegador recalcula layout, el observer vuelve a detectar cambios y se puede producir un ciclo de renderizado/recalculo.

La solución aplicada

La solución fue desactivar ese comportamiento de observación de visibilidad y mantener los iconos renderizados de forma estable. Esto evita que Iconify quite y vuelva a insertar SVGs durante el scroll.

Antes de modificar el archivo, es recomendable hacer un respaldo:

cp public/assets/js/iconify-icon.js public/assets/js/iconify-icon.backup.js

Después, se pueden aplicar los siguientes ajustes dentro del archivo iconify-icon.js.

1. Ajustar connectedCallback()

Busca una función similar a esta:

connectedCallback() {
    this._connected = true;
    this.startObserver();
}

Y cámbiala por:

connectedCallback() {
    this._connected = true;
    this._visible = true;
    this._queueCheck();
}

Con este cambio, al conectar el elemento al DOM, el icono se considera visible y se renderiza sin iniciar el observer.

2. Corregir la lógica de noobserver

En algunas versiones, el manejo del atributo noobserver puede estar invertido. Si encuentras algo similar a esto:

case "noobserver":
    this.hasAttribute("noobserver") ? this.startObserver() : this.stopObserver();
    break;

Cámbialo por:

case "noobserver":
    this.hasAttribute("noobserver") ? this.stopObserver() : this.startObserver();
    break;

Esto hace que, si el elemento tiene el atributo noobserver, el observer se detenga en lugar de iniciarse.

3. Reemplazar startObserver()

Busca el método startObserver(). Normalmente contiene una instancia de IntersectionObserver, similar a esta:

startObserver() {
    if (!this._observer && !this.hasAttribute("noobserver")) {
        try {
            this._observer = new IntersectionObserver((entries) => {
                const isVisible = entries.some((entry) => entry.isIntersecting);

                if (isVisible !== this._visible) {
                    this._visible = isVisible;
                    this._forceRender();
                }
            });

            this._observer.observe(this);
        } catch (error) {
            if (this._observer) {
                try {
                    this._observer.disconnect();
                } catch (error) {}

                this._observer = null;
            }
        }
    }
}

Reemplázalo por una versión simple:

startObserver() {
    this._visible = true;
    this._queueCheck();
}

Este es el cambio principal. El icono se mantiene renderizado y ya no se elimina o reconstruye durante el scroll.

4. Ajustar _forceRender()

Busca una función similar a esta:

_forceRender() {
    if (this._visible) {
        this._queueCheck();
    } else {
        const element = getRenderedIcon(this._shadowRoot);

        if (element) {
            this._shadowRoot.removeChild(element);
        }
    }
}

Y cámbiala por:

_forceRender() {
    this._visible = true;
    this._queueCheck();
}

Con esto se evita que cualquier flujo interno vuelva a remover el SVG del Shadow DOM.

Cómo evitar problemas de caché

Después de modificar el archivo, es importante forzar al navegador a cargar la nueva versión. Una forma sencilla es agregar un parámetro de versión al script:

<script src="/assets/js/iconify-icon.js?v=1.0.2"></script>

También puedes limpiar caché manualmente o compilar nuevamente los assets si el archivo forma parte de un proceso de build.

Alternativa: usar un patch separado

Si no quieres modificar directamente la librería, puedes crear un archivo adicional que se cargue después de iconify-icon.js. Esta opción es útil cuando el archivo original pertenece a una plantilla o paquete de terceros.

<script src="/assets/js/iconify-icon.js"></script>
<script src="/assets/js/iconify-icon-noobserver-patch.js"></script>

Sin embargo, si el problema está dentro de la clase registrada como Web Component, modificar directamente el método dentro del archivo original suele ser más estable, siempre que se haga con respaldo y control de versiones.

Cuándo conviene aplicar esta solución

Este ajuste puede ser útil cuando se cumplen varias de estas condiciones:

• La página tiene muchos iconos generados con <iconify-icon>.
• El problema aparece únicamente en páginas largas con scroll.
• El salto desaparece al quitar iconify-icon.js.
• No existen errores claros en consola.
• El navegador muestra actividad alta de renderizado o recalculado de estilos.

Recomendaciones finales

Antes de modificar una librería de terceros, conviene confirmar que realmente es la causa del problema. Para hacerlo puedes probar lo siguiente:

• Desactivar temporalmente el script sospechoso.
• Probar la misma página con pocos iconos.
• Revisar si el problema aparece solo al hacer scroll.
• Validar que no existan scripts duplicados.
• Hacer respaldo del archivo original antes de editarlo.

En este caso, la solución fue mantener los iconos renderizados y desactivar la observación de visibilidad con IntersectionObserver. Con ello se evita que el navegador entre en un ciclo de recalculado al hacer scroll y la interfaz vuelve a comportarse de forma estable.

Conclusión

Los bugs de scroll pueden ser difíciles de detectar porque no siempre generan errores en consola. Muchas veces el problema no está en el CSS, sino en scripts que modifican el DOM mientras el usuario navega por la página.

Cuando una librería intenta optimizar el renderizado quitando y agregando elementos durante el scroll, puede terminar provocando saltos visuales, congelamientos o recalculados constantes. En interfaces administrativas con muchos iconos, desactivar ese comportamiento puede ser una solución práctica y efectiva.

Este es uno de los problemas más frecuentes durante el desarrollo local y suele estar relacionado con una causa muy específica: la discrepancia de protocolos en la URI de redirección (redirect_uri).

A continuación, veremos por qué ocurre este problema y cómo solucionarlo para que tu flujo de autenticación funcione correctamente tanto en desarrollo como en producción.

El origen del problema: la seguridad en OAuth 2.0

OAuth 2.0 es el estándar utilizado por numerosas plataformas y servicios para permitir que aplicaciones externas accedan a recursos protegidos de forma segura. Durante la configuración de una aplicación, normalmente se debe registrar una o más URI de redirección.

Estas direcciones son utilizadas por el proveedor de autenticación para devolver al usuario a tu aplicación una vez que ha iniciado sesión y autorizado el acceso.

El conflicto suele aparecer debido a la diferencia entre los requisitos de seguridad de la plataforma y las características de un entorno local de desarrollo:

1. Las plataformas exigen HTTPS: Muchos proveedores requieren que la redirect_uri utilice un protocolo seguro (https://) para proteger el intercambio de información sensible.
2. Los entornos locales suelen usar HTTP: Herramientas de desarrollo como Laragon, XAMPP, WAMP o configuraciones locales de servidores web suelen funcionar inicialmente mediante http://.

Cuando la aplicación genera una URL con HTTPS pero el servidor local no está preparado para responder mediante ese protocolo, el navegador no puede establecer la conexión. Por otro lado, si se utiliza HTTP, muchos proveedores rechazarán la solicitud por razones de seguridad o porque la URL no coincide exactamente con la registrada.

La solución en 3 pasos

La clave consiste en lograr que tu entorno local soporte HTTPS y que las URLs generadas por tu aplicación coincidan exactamente con las registradas en el proveedor de autenticación.

Paso 1: Habilitar HTTPS en tu entorno local

Configura un certificado SSL local para que tu aplicación pueda responder mediante HTTPS.

Algunas opciones comunes son:

• Laragon: Permite habilitar certificados SSL locales de forma automática.
• Laravel Valet: Puede generar certificados locales seguros mediante comandos específicos.
• mkcert: Herramienta ampliamente utilizada para crear certificados confiables en entornos de desarrollo.
• Docker o servidores personalizados: Configura certificados SSL dentro del contenedor o servidor correspondiente.

Una vez configurado, tu aplicación debería ser accesible mediante una URL similar a:

https://miaplicacion.local

Paso 2: Generar URLs seguras desde la aplicación

Es importante que la URI de redirección se genere utilizando HTTPS para garantizar que coincida con la configuración registrada en el proveedor.

Por ejemplo, en Laravel:

$redirect_uri = secure_url(route('oauth.callback', [], false));

El objetivo no es utilizar una función específica, sino asegurarse de que la URL enviada al proveedor tenga exactamente el protocolo HTTPS esperado.

Paso 3: Verificar la configuración del proveedor

La URI configurada en el panel del proveedor debe coincidir exactamente con la generada por tu aplicación.

Ejemplos:

• Correcto: https://miaplicacion.local/oauth/callback
• Incorrecto: http://miaplicacion.local/oauth/callback
• Incorrecto: https://miaplicacion.local/oauth/callback/
• Incorrecto: https://www.miaplicacion.local/oauth/callback (si el dominio registrado no incluye www)

Las plataformas suelen realizar comparaciones estrictas, por lo que cualquier diferencia en protocolo, dominio, ruta, mayúsculas o barras finales puede provocar errores de autenticación.

Buenas prácticas adicionales

Además de corregir el problema inmediato, es recomendable seguir estas prácticas:

• Mantener la misma estructura de URLs entre desarrollo, pruebas y producción.
• Utilizar variables de entorno para configurar dominios y rutas de autenticación.
• Evitar construir manualmente las URLs de redirección cuando el framework puede generarlas automáticamente.
• Verificar periódicamente la configuración registrada en los proveedores externos.
• Probar el flujo completo de autenticación antes de desplegar cambios en producción.

Conclusión

La mayoría de los problemas relacionados con OAuth 2.0 en entornos de desarrollo no provienen de errores en el código, sino de diferencias entre la configuración local y los requisitos de seguridad exigidos por los proveedores de autenticación.

Al habilitar HTTPS localmente, generar URLs seguras desde la aplicación y asegurarte de que las URIs registradas coincidan exactamente con las utilizadas en el código, podrás evitar errores de autenticación y contar con un flujo de integración mucho más estable y seguro.

Estos mismos principios aplican a cualquier integración basada en OAuth 2.0, independientemente del proveedor o servicio externo con el que estés trabajando.

En este artículo, exploraremos las mejores prácticas para implementar OAuth 2.0 en Laravel, protegiendo las credenciales de tu aplicación y evitando vulnerabilidades críticas.

¿Por qué no deberías guardar tokens en texto plano?

Cuando trabajas con integraciones de terceros, el flujo de OAuth 2.0 te entrega un access_token y, a menudo, un refresh_token. El error más común en desarrolladores junior es guardar estas cadenas directamente en la base de datos como texto plano.

Si un atacante lograra vulnerar tu base de datos, tendría acceso total a las cuentas de tus clientes en esas plataformas externas. En Laravel, la solución es sumamente sencilla gracias a sus Facades de encriptación.

Al guardar tus credenciales, asegúrate de utilizar la función nativa de Laravel para encriptar los datos sensibles, de manera que solo tu aplicación pueda interpretarlos usando la llave maestra (APP_KEY) de tu entorno.

Creando una arquitectura segura en la Base de Datos

Otro aspecto vital es la separación de responsabilidades. No mezcles la configuración de tus APIs con la tabla general de usuarios de tu sistema.

Lo ideal es diseñar una tabla específica (por ejemplo, api_configurations) que contenga únicamente los datos de autenticación: el App ID, el Secret Key y los tokens. Esto te permite aplicar reglas estrictas de acceso, implementar restricciones de unicidad para evitar duplicados en las configuraciones y aislar la información crítica del resto de la lógica de negocio.

El flujo de autorización y el control de Callbacks

OAuth 2.0 requiere que el usuario sea redirigido a la plataforma externa para dar su consentimiento y luego regrese a tu aplicación a través de una URL de retorno (Callback).

Un buen desarrollador debe blindar esta ruta de retorno. Nunca asumas que la redirección viene con los parámetros correctos. Es indispensable:

• Validar que el código de autorización realmente venga en la URL.
• Implementar validaciones de estado para evitar peticiones redundantes.
• Manejar bloqueos para que un usuario no pueda acceder a rutas de “desconexión” si la cuenta ya ha sido desvinculada previamente.

Conclusión: La seguridad no es opcional

Conectar una API es un logro técnico, pero asegurarla es lo que distingue a un desarrollo amateur de uno profesional. Laravel nos ofrece todas las herramientas necesarias —desde rutas nombradas hasta encriptación nativa y middlewares— para que nuestras integraciones sean robustas y a prueba de balas.

En este artículo veremos cómo migrar la autenticación de un proyecto desde HTTPS con token hacia SSH, cómo validar que la conexión funcione correctamente y qué hacer cuando Git no permite cambiar de rama porque existen archivos locales modificados, como puede pasar con archivos de configuración en Laravel.

El problema: el token de acceso ya venció

Supongamos que tenemos un proyecto Laravel en un servidor de pruebas o demo. Al intentar ejecutar comandos como git fetch, git pull o git checkout, GitHub responde con un error de autenticación porque el token que se usaba anteriormente ya venció.

En muchos casos, aunque ya hayamos creado una llave SSH en el servidor, Git seguirá usando el token anterior si el repositorio todavía tiene configurada una URL remota con HTTPS.

Es decir, crear una llave SSH no cambia automáticamente la forma en que Git se conecta al repositorio. También debemos actualizar la URL remota del proyecto.

1. Revisar la URL remota actual

Primero debemos entrar a la carpeta del proyecto y revisar qué URL remota está usando Git.

cd /ruta/general/del/proyecto

git remote -v

Si la respuesta muestra una URL similar a esta:

origin  https://github.com/usuario/repositorio.git (fetch)
origin  https://github.com/usuario/repositorio.git (push)

significa que el proyecto todavía está usando HTTPS.

En algunos casos, incluso puede aparecer un token dentro de la URL, algo parecido a esto:

origin  https://TOKEN@github.com/usuario/repositorio.git

Ese es el escenario que debemos corregir.

2. Cambiar la URL remota de HTTPS a SSH

Para que Git use la llave SSH, debemos cambiar la URL remota del repositorio usando el comando git remote set-url.

git remote set-url origin git@github.com:usuario/repositorio.git

Este comando cambia el origen del repositorio para que Git deje de usar HTTPS y empiece a usar SSH.

Después podemos verificar nuevamente la configuración:

git remote -v

La salida esperada sería algo como:

origin  git@github.com:usuario/repositorio.git (fetch)
origin  git@github.com:usuario/repositorio.git (push)

3. Probar la conexión SSH con GitHub

Antes de intentar descargar ramas o actualizar el proyecto, conviene probar que la llave SSH realmente esté funcionando.

ssh -T git@github.com

Si la autenticación es correcta, GitHub responderá con un mensaje indicando que la conexión fue exitosa, aunque no permita acceso de shell. Esto es normal.

Una respuesta esperada puede ser similar a:

Hi usuario! You've successfully authenticated, but GitHub does not provide shell access.

Con eso confirmamos que la autenticación SSH ya está funcionando.

4. Descargar información actualizada del repositorio

Una vez configurada la URL SSH, podemos ejecutar:

git fetch origin

Este comando descarga la información actualizada de las ramas remotas sin mezclar cambios todavía en la rama actual.

5. Cambiar a una rama remota

Si necesitamos crear una rama local a partir de una rama remota, podemos usar:

git checkout -b nombre-rama origin/nombre-rama

Sin embargo, en proyectos reales puede aparecer un error indicando que un archivo local tiene cambios y que Git necesita sobrescribirlo para cambiar de rama.

Un caso común en Laravel puede ser un archivo como:

config/app.php

6. ¿Por qué pasa este error?

Git protege los cambios locales para evitar que se pierdan accidentalmente. Si tenemos modificaciones en un archivo y la rama a la que queremos cambiar también modifica ese archivo, Git detiene el proceso.

A veces se intenta usar el comando assume-unchanged para que Git ignore temporalmente un archivo:

git update-index --assume-unchanged config/app.php

Este comando puede ayudar en algunos escenarios locales, pero no es una solución ideal para manejar archivos de configuración modificados en servidores o ambientes de demo.

Además, aunque un archivo esté marcado como assume-unchanged, Git aún puede bloquear operaciones si necesita proteger cambios locales antes de cambiar de rama.

7. Revisar si un archivo está marcado como assume-unchanged

Podemos revisar el estado del archivo con:

git ls-files -v config/app.php

Si el archivo aparece con una letra minúscula al inicio, significa que está marcado como assume-unchanged.

8. Quitar assume-unchanged

Antes de resolver el conflicto, es recomendable quitar esa marca para que Git vuelva a tratar el archivo normalmente.

git update-index --no-assume-unchanged config/app.php

9. Opción segura: guardar temporalmente los cambios con stash

Si necesitamos conservar los cambios locales del archivo, podemos guardarlos temporalmente con git stash.

git stash push -m "Backup config app" -- config/app.php

Después ya podemos intentar cambiar de rama:

git checkout -b nombre-rama origin/nombre-rama

Y si necesitamos recuperar los cambios guardados:

git stash pop

Si al recuperar los cambios aparecen conflictos, deberán resolverse manualmente.

10. Opción rápida: descartar cambios locales

Si los cambios locales no son importantes, podemos descartarlos.

git restore config/app.php

Después intentamos nuevamente cambiar de rama:

git checkout -b nombre-rama origin/nombre-rama

Esta opción debe usarse con cuidado, porque elimina los cambios locales del archivo.

11. Mejor práctica en Laravel: usar .env para configuración por ambiente

En Laravel, lo más recomendable es evitar modificar archivos como config/app.php directamente en cada servidor. Si una configuración cambia dependiendo del ambiente, lo ideal es manejarla desde el archivo .env.

Por ejemplo, en lugar de dejar un valor fijo dentro de config/app.php, podemos leerlo desde una variable de entorno:

'custom_product' => env('APP_CUSTOM_PRODUCT', false),

Y en el archivo .env del servidor:

APP_CUSTOM_PRODUCT=true

De esta manera cada ambiente puede tener su propia configuración sin modificar archivos versionados en Git.

12. Flujo recomendado completo

Un flujo seguro para este tipo de situación sería:

cd /ruta/general/del/proyecto

git remote -v

git remote set-url origin git@github.com:usuario/repositorio.git

git remote -v

ssh -T git@github.com

git fetch origin

git update-index --no-assume-unchanged config/app.php

git stash push -m "Backup config app" -- config/app.php

git checkout -b nombre-rama origin/nombre-rama

Si después necesitamos recuperar los cambios locales:

git stash pop

Conclusión

Cuando un proyecto deja de autenticarse con GitHub porque venció un access token, una buena solución es migrar la conexión del repositorio a SSH. Para que esto funcione, no basta con crear la llave SSH: también debemos cambiar la URL remota del repositorio.

Además, si Git bloquea un cambio de rama por archivos modificados, debemos decidir si queremos conservar esos cambios con git stash o descartarlos con git restore.

En proyectos Laravel, la recomendación más limpia es mantener los archivos de configuración versionados sin modificaciones locales y mover los valores específicos de cada ambiente al archivo .env. Esto evita conflictos, mejora el flujo de despliegue y reduce errores al trabajar con ramas en Git.

Si necesitas ayuda para crear un proyecto de software en Maria Tech contamos con los expertos para apoyarte.

Sin embargo, cuando el formulario se envía por medio de Ajax, especialmente desde modales o componentes dinámicos, surge una duda común: ¿cómo devolvemos los errores de validación en formato JSON sin dejar de usar la estructura nativa de Laravel?

En este artículo veremos una forma práctica de trabajar con Request validation con formularios Ajax, respuestas JSON y códigos HTTP correctos.

El problema común

En un formulario tradicional, si la validación falla, Laravel redirige automáticamente al usuario a la página anterior y muestra los errores en la vista.

Pero cuando usamos Ajax, no queremos una redirección. Queremos una respuesta JSON que podamos procesar desde JavaScript para mostrar los errores dentro de un modal, un toast o una alerta.

Una solución rápida suele ser hacer la validación directamente en el controlador:

$validator = Validator::make($request->all(), $rules, $messages);

if ($validator->fails()) {
    return response()->json([
        'success' => false,
        'errors' => $validator->errors()->all(),
    ], 422);
}

Aunque esto funciona, tiene una desventaja importante: la validación queda mezclada dentro del controlador. Conforme el proyecto crece, esto vuelve el código más difícil de mantener.

La mejor opción: seguir usando Form Request

Laravel permite seguir usando Form Requests aun cuando el formulario se envía por Ajax. Lo único que necesitamos es personalizar la respuesta cuando la validación falla.

Primero, podemos crear un Form Request:

php artisan make:request Admin/User/StoreUserRequest

Luego definimos las reglas de validación:

namespace App\Http\Requests\Admin\User;

use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

class StoreUserRequest extends FormRequest
{
    public function authorize(): bool
    {
        return true;
    }

    public function rules(): array
    {
        return [
            'name' => ['required', 'string', 'max:255'],
            'last_name' => ['required', 'string', 'max:255'],
            'email' => ['required', 'email', 'max:255', Rule::unique('users', 'email')],
            'phone' => ['nullable', 'digits:10'],
            'id_profile_type' => ['required', 'exists:profile_types,id'],
            'password' => ['required', 'string', 'min:8', 'confirmed'],
            'enabled' => ['nullable', 'boolean'],
        ];
    }
}

Personalizar la respuesta JSON de validación

Por defecto, Laravel devuelve los errores agrupados por campo:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "Este correo electrónico ya está registrado."
        ],
        "password": [
            "La contraseña debe tener al menos 8 caracteres."
        ]
    }
}

Este formato es útil cuando queremos marcar errores campo por campo. Pero si nuestra interfaz usa modales y queremos mostrar una lista general de errores, puede ser más cómodo devolver una lista plana.

Para eso podemos sobrescribir el método failedValidation dentro del StoreUserRequest:

use Illuminate\Contracts\Validation\Validator;
use Illuminate\Http\Exceptions\HttpResponseException;

protected function failedValidation(Validator $validator): void
{
    throw new HttpResponseException(response()->json([
        'success' => false,
        'message' => 'Hay errores en el formulario.',
        'errors' => $validator->errors()->all(),
    ], 422));
}

Con esto, la respuesta quedará así:

{
    "success": false,
    "message": "Hay errores en el formulario.",
    "errors": [
        "El nombre es obligatorio.",
        "Este correo electrónico ya está registrado.",
        "La contraseña debe tener al menos 8 caracteres."
    ]
}

Controlador limpio usando el Form Request

Una vez que el Form Request está listo, el controlador puede mantenerse limpio:

use App\Http\Requests\Admin\User\StoreUserRequest;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Hash;
use Throwable;

public function store(StoreUserRequest $request): JsonResponse
{
    try {
        $validated = $request->validated();

        $user = User::create([
            'name' => $validated['name'],
            'last_name' => $validated['last_name'],
            'email' => $validated['email'],
            'phone' => $validated['phone'] ?? null,
            'id_profile_type' => $validated['id_profile_type'],
            'password' => Hash::make($validated['password']),
            'enabled' => $validated['enabled'] ?? 1,
        ]);

        return response()->json([
            'success' => true,
            'message' => 'Usuario registrado correctamente.',
            'user_id' => $user->id,
        ], 201);

    } catch (Throwable $e) {
        report($e);

        return response()->json([
            'success' => false,
            'message' => 'No fue posible registrar el usuario. Inténtalo nuevamente.',
        ], 500);
    }
}

Códigos HTTP recomendados

Es importante regresar códigos HTTP correctos para que el frontend pueda interpretar bien la respuesta.

• 200: operación correcta.
• 201: registro creado correctamente.
• 401: usuario no autenticado.
• 403: usuario autenticado, pero sin permisos.
• 404: recurso no encontrado.
• 422: error de validación.
• 500: error inesperado del servidor.

Para formularios Ajax, una convención práctica sería:

Validación fallida  → 422
Creación correcta   → 201
Actualización       → 200
Eliminación         → 200
No encontrado       → 404
Sin permisos        → 403
Error inesperado    → 500

Conclusión

Usar Form Requests con formularios Ajax es una forma limpia y profesional de validar datos en Laravel sin sacrificar la experiencia de usuario.

La clave está en no llevar las reglas de validación al controlador, sino mantenerlas dentro del Request y personalizar la respuesta JSON cuando la validación falla.

Con esta estructura logramos:

• Controladores más limpios.
• Validaciones reutilizables.
• Respuestas JSON consistentes.
• Códigos HTTP correctos.
• Mejor integración con formularios en modales.
• Mejor experiencia de usuario usando Ajax.

Esta forma de trabajo es especialmente útil en paneles administrativos, sistemas internos, CRMs, ERPs y plataformas donde los formularios se muestran en modales o secciones dinámicas.

Si necesitas ayuda para crear un proyecto de software en Maria Tech contamos con los expertos para apoyarte.

En este artículo veremos cómo estructurar un proceso de recuperación de contraseña en Laravel 13 para dos tipos de usuarios: administradores y clientes. El objetivo es mantener una arquitectura limpia, segura y fácil de mantener.

Contexto del problema

Laravel Breeze instala un sistema de autenticación funcional, pero por defecto está pensado para trabajar principalmente con una sola tabla de usuarios, normalmente users.

Sin embargo, en proyectos más completos podemos necesitar algo como esto:

• Administradores: usuarios internos del sistema, almacenados en la tabla users.
• Clientes: usuarios externos que acceden al sitio o portal del cliente, almacenados en la tabla customers.

En este escenario no conviene mezclar ambos tipos de usuario en la misma tabla, porque normalmente tienen permisos, vistas, reglas de negocio y flujos diferentes.

Estructura recomendada

app/
├── Http/
│   ├── Controllers/
│   │   ├── Admin/
│   │   │   └── Auth/
│   │   │       ├── PasswordResetLinkController.php
│   │   │       └── NewPasswordController.php
│   │   └── Customer/
│   │       └── Auth/
│   │           ├── PasswordResetLinkController.php
│   │           └── NewPasswordController.php

resources/
├── views/
│   ├── admin/
│   │   └── auth/
│   │       ├── forgot-password.blade.php
│   │       └── reset-password.blade.php
│   └── customer/
│       └── auth/
│           ├── forgot-password.blade.php
│           └── reset-password.blade.php

routes/
├── admin.php
└── customer.php

La idea es separar cada flujo para evitar dependencias innecesarias y tener rutas, controladores, vistas y brokers independientes.

Configuración de autenticación

En config/auth.php podemos definir un guard y un provider para cada tipo de usuario.

<?php

use App\Models\User;
use App\Models\Customer;

return [

    'defaults' => [
        'guard' => 'web',
        'passwords' => 'users',
    ],

    'guards' => [
        'web' => [
            'driver' => 'session',
            'provider' => 'users',
        ],

        'customer' => [
            'driver' => 'session',
            'provider' => 'customers',
        ],
    ],

    'providers' => [
        'users' => [
            'driver' => 'eloquent',
            'model' => User::class,
        ],

        'customers' => [
            'driver' => 'eloquent',
            'model' => Customer::class,
        ],
    ],

    'passwords' => [
        'users' => [
            'provider' => 'users',
            'table' => 'password_reset_tokens',
            'expire' => 60,
            'throttle' => 60,
        ],

        'customers' => [
            'provider' => 'customers',
            'table' => 'customer_password_reset_tokens',
            'expire' => 60,
            'throttle' => 60,
        ],
    ],

];

El punto clave está en la sección passwords. Ahí definimos dos brokers: users para administradores y customers para clientes. Cada broker usa su propio provider y su propia tabla de tokens.

Migración para tokens de clientes

Schema::create('customer_password_reset_tokens', function (Blueprint $table) {
    $table->string('email')->primary();
    $table->string('token');
    $table->timestamp('created_at')->nullable();
});

Esto permite que el flujo de administradores y clientes quede completamente separado.

Rutas para administradores

use App\Http\Controllers\Admin\Auth\PasswordResetLinkController;
use App\Http\Controllers\Admin\Auth\NewPasswordController;
use Illuminate\Support\Facades\Route;

Route::middleware('admin.guest')->group(function () {
    Route::get('/forgot-password', [PasswordResetLinkController::class, 'create'])
        ->name('password.request');

    Route::post('/forgot-password', [PasswordResetLinkController::class, 'store'])
        ->name('password.email');

    Route::get('/reset-password/{token}', [NewPasswordController::class, 'create'])
        ->name('password.reset');

    Route::post('/reset-password', [NewPasswordController::class, 'store'])
        ->name('password.store');
});

Rutas para clientes

use App\Http\Controllers\Customer\Auth\PasswordResetLinkController;
use App\Http\Controllers\Customer\Auth\NewPasswordController;
use Illuminate\Support\Facades\Route;

Route::middleware('customer.guest')->group(function () {
    Route::get('/forgot-password', [PasswordResetLinkController::class, 'create'])
        ->name('password.request');

    Route::post('/forgot-password', [PasswordResetLinkController::class, 'store'])
        ->name('password.email');

    Route::get('/reset-password/{token}', [NewPasswordController::class, 'create'])
        ->name('password.reset');

    Route::post('/reset-password', [NewPasswordController::class, 'store'])
        ->name('password.store');
});

Controlador para enviar el enlace de recuperación

El controlador encargado de enviar el enlace de recuperación debe usar el broker correcto.

Administrador

namespace App\Http\Controllers\Admin\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Password;
use Illuminate\Validation\ValidationException;

class PasswordResetLinkController extends Controller
{
    public function create()
    {
        return view('admin.auth.forgot-password');
    }

    public function store(Request $request)
    {
        $request->validate([
            'email' => ['required', 'email'],
        ]);

        $status = Password::broker('users')->sendResetLink(
            $request->only('email')
        );

        if ($status === Password::RESET_LINK_SENT) {
            return back()->with('status', __($status));
        }

        throw ValidationException::withMessages([
            'email' => __($status),
        ]);
    }
}

Cliente

namespace App\Http\Controllers\Customer\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Password;
use Illuminate\Validation\ValidationException;

class PasswordResetLinkController extends Controller
{
    public function create()
    {
        return view('customer.auth.forgot-password');
    }

    public function store(Request $request)
    {
        $request->validate([
            'email' => ['required', 'email'],
        ]);

        $status = Password::broker('customers')->sendResetLink(
            $request->only('email')
        );

        if ($status === Password::RESET_LINK_SENT) {
            return back()->with('status', __($status));
        }

        throw ValidationException::withMessages([
            'email' => __($status),
        ]);
    }
}

El cambio central es el broker:

Password::broker('users')      // Administradores
Password::broker('customers')  // Clientes

Controlador para actualizar la contraseña

Administrador

namespace App\Http\Controllers\Admin\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Auth\Events\PasswordReset;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Password;
use Illuminate\Support\Str;
use Illuminate\Validation\Rules;

class NewPasswordController extends Controller
{
    public function create(Request $request)
    {
        return view('admin.auth.reset-password', [
            'request' => $request,
        ]);
    }

    public function store(Request $request)
    {
        $request->validate([
            'token' => ['required'],
            'email' => ['required', 'email'],
            'password' => ['required', 'confirmed', Rules\Password::defaults()],
        ]);

        $status = Password::broker('users')->reset(
            $request->only('email', 'password', 'password_confirmation', 'token'),
            function ($user) use ($request) {
                $user->forceFill([
                    'password' => Hash::make($request->password),
                    'remember_token' => Str::random(60),
                ])->save();

                event(new PasswordReset($user));
            }
        );

        return $status === Password::PASSWORD_RESET
            ? redirect()->route('admin.login')->with('status', __($status))
            : back()->withInput($request->only('email'))
                ->withErrors(['email' => __($status)]);
    }
}

Cliente

namespace App\Http\Controllers\Customer\Auth;

use App\Http\Controllers\Controller;
use Illuminate\Auth\Events\PasswordReset;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Support\Facades\Password;
use Illuminate\Support\Str;
use Illuminate\Validation\Rules;

class NewPasswordController extends Controller
{
    public function create(Request $request)
    {
        return view('customer.auth.reset-password', [
            'request' => $request,
        ]);
    }

    public function store(Request $request)
    {
        $request->validate([
            'token' => ['required'],
            'email' => ['required', 'email'],
            'password' => ['required', 'confirmed', Rules\Password::defaults()],
        ]);

        $status = Password::broker('customers')->reset(
            $request->only('email', 'password', 'password_confirmation', 'token'),
            function ($customer) use ($request) {
                $customer->forceFill([
                    'password' => Hash::make($request->password),
                    'remember_token' => Str::random(60),
                ])->save();

                event(new PasswordReset($customer));
            }
        );

        return $status === Password::PASSWORD_RESET
            ? redirect()->route('customer.login')->with('status', __($status))
            : back()->withInput($request->only('email'))
                ->withErrors(['email' => __($status)]);
    }
}

Personalizar la URL del correo de recuperación

Un detalle importante es que Laravel genera el enlace de recuperación usando una notificación. Si no personalizamos ese enlace, puede terminar enviando al usuario al flujo equivocado.

Para resolverlo, podemos agregar la lógica en app/Providers/AppServiceProvider.php.

namespace App\Providers;

use App\Models\Customer;
use App\Models\User;
use Illuminate\Auth\Notifications\ResetPassword;
use Illuminate\Support\Facades\URL;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        //
    }

    public function boot(): void
    {
        ResetPassword::createUrlUsing(function (object $notifiable, string $token): string {
            if ($notifiable instanceof Customer) {
                return URL::route('customer.password.reset', [
                    'token' => $token,
                    'email' => $notifiable->getEmailForPasswordReset(),
                ]);
            }

            if ($notifiable instanceof User) {
                return URL::route('admin.password.reset', [
                    'token' => $token,
                    'email' => $notifiable->getEmailForPasswordReset(),
                ]);
            }

            return URL::route('customer.password.reset', [
                'token' => $token,
                'email' => $notifiable->getEmailForPasswordReset(),
            ]);
        });
    }
}

Con esto, cuando el modelo sea User, Laravel enviará al flujo de administrador. Cuando el modelo sea Customer, enviará al flujo de cliente.

Vistas de recuperación de contraseña

En cada formulario es importante apuntar a la ruta correcta.

Formulario para solicitar enlace

Administrador:

<form method="POST" action="{{ route('admin.password.email') }}">
    @csrf
    <input type="email" name="email" required>
    <button type="submit">
        Enviar enlace
    </button>
</form>

Cliente:

<form method="POST" action="{{ route('customer.password.email') }}">
    @csrf
    <input type="email" name="email" required>
    <button type="submit">
        Enviar enlace
    </button>
</form>

Formulario para crear nueva contraseña

Administrador:

<form method="POST" action="{{ route('admin.password.store') }}">
    @csrf
    <input type="hidden" name="token" value="{{ $request->route('token') }}">
    <input type="email" name="email" value="{{ old('email', $request->email) }}" required>
    <input type="password" name="password" required>
    <input type="password" name="password_confirmation" required>
    <button type="submit">
        Actualizar contraseña
    </button>
</form>

Cliente:

<form method="POST" action="{{ route('customer.password.store') }}">
    @csrf
    <input type="hidden" name="token" value="{{ $request->route('token') }}">
    <input type="email" name="email" value="{{ old('email', $request->email) }}" required>
    <input type="password" name="password" required>
    <input type="password" name="password_confirmation" required>
    <button type="submit">
        Actualizar contraseña
    </button>
</form>

Buenas prácticas

• Usar modelos separados cuando los usuarios internos y externos tienen responsabilidades diferentes.
• Separar rutas, vistas y controladores por tipo de usuario.
• Usar un broker de contraseña diferente para cada tabla.
• Personalizar la URL del correo para evitar que el usuario llegue al flujo equivocado.
• No depender completamente de la estructura por defecto de Breeze cuando el proyecto requiere múltiples áreas de autenticación.
• Mantener nombres claros como Admin y Customer para facilitar el mantenimiento.

Conclusión

La recuperación de contraseña para múltiples tipos de usuarios en Laravel requiere separar correctamente guards, providers, brokers, rutas, controladores y vistas. Aunque Breeze ofrece una buena base inicial, en proyectos con administradores y clientes conviene tomar el control del flujo para evitar cruces entre autenticaciones.

La clave está en usar un broker distinto para cada tipo de usuario:

Password::broker('users')      // Administradores
Password::broker('customers')  // Clientes

Y personalizar el enlace generado por correo desde AppServiceProvider, para que cada usuario llegue al formulario correcto.

Con esta estructura, el sistema queda más limpio, seguro y preparado para crecer.

¡Si te ha servido de algo este artículo no olvides dejarnos un comentario!