En este artículo vamos a ver por qué vale la pena dedicarles pruebas propias, qué conviene verificar exactamente, y cómo escribirlas y ejecutarlas paso a paso. Los ejemplos usan Eloquent, el ORM de Laravel, pero las ideas se trasladan a cualquier ORM con relaciones.

El problema: las relaciones fallan en silencio

Una relación mal definida no suele lanzar un error inmediato. El código compila, la aplicación arranca, y todo parece funcionar hasta que, en algún punto, una consulta devuelve una colección vacía donde debería haber datos, o carga el registro equivocado.

El caso más común aparece cuando el nombre de la clave foránea no sigue la convención que el ORM espera. Eloquent asume un patrón de nombres por defecto: para una relación hacia una tabla documentos, busca una columna documento_id. Si tu base de datos usa otra convención, el ORM buscará una columna que no existe y la relación devolverá vacío, sin quejarse.

Este tipo de fallo es especialmente traicionero porque no se manifiesta donde está el error, sino mucho más adelante, en una vista que no muestra datos o en un reporte con totales incompletos. Una prueba de relación lo atrapa en el acto.

Dónde vive la prueba

En Laravel, las pruebas viven en el directorio tests/, dividido en dos carpetas:

• tests/Unit/ para pruebas que no tocan la base de datos.
• tests/Feature/ para las que sí.

Las pruebas de relaciones van en tests/Feature/, porque necesitan crear registros y consultarlos.

Para crear el archivo:

php artisan make:test DocumentoRelacionesTest

Eso genera tests/Feature/DocumentoRelacionesTest.php.

El esqueleto de la clase

<?php

namespace Tests\Feature;

use App\Models\Documento;
use App\Models\Impuesto;
use App\Models\LineaDeDetalle;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class DocumentoRelacionesTest extends TestCase
{
    use RefreshDatabase;

    // Aquí van los casos
}

RefreshDatabase es la pieza clave: ejecuta las migraciones antes de la suite y envuelve cada prueba en una transacción que se revierte al terminar. Así cada caso arranca con una base limpia y no puedes ensuciar datos reales por accidente.

Cada caso es un método público cuyo nombre empieza con test, o que lleva el atributo #[Test] si prefieres nombres sin prefijo.

Los cuatro casos que conviene cubrir

1. Que la relación carga en ambos sentidos

Las relaciones tienen dos extremos y ambos pueden estar mal definidos de forma independiente. Si un padre tiene muchos hijos, verifica que desde el padre llegas a todos sus hijos, y que desde un hijo llegas a su padre.

Aquí es donde las factories hacen el trabajo pesado. Una factory es una receta para crear registros de prueba con valores realistas y, bien configurada, encadena automáticamente la creación de los registros de los que depende:

public function test_la_linea_llega_a_su_documento()
{
    // Crea la línea y, de forma automática, su documento padre
    $linea = LineaDeDetalle::factory()->create();

    $this->assertNotNull($linea->documento);
    $this->assertSame($linea->id_documento, $linea->documento->id);
}

public function test_el_documento_ve_todas_sus_lineas()
{
    $documento = Documento::factory()->create();

    LineaDeDetalle::factory()->count(3)->create([
        'id_documento' => $documento->id,
    ]);

    $this->assertCount(3, $documento->lineas);
}

Nota el fresh() que no aparece aquí y sí en otros casos: $documento->lineas se carga por primera vez en el momento de la aserción, así que todavía no hay nada en caché. Si hubieras accedido a la relación antes de crear las líneas, Eloquent devolvería la colección vacía que ya tenía guardada.

2. Que la carga anticipada funciona

La carga anticipada, o eager loading, evita el problema de las N+1 consultas: en lugar de una consulta por cada registro relacionado, se hacen dos en total. Es fácil creer que la tienes y que no esté surtiendo efecto.

La forma de comprobarlo es contar las consultas que realmente se ejecutan:

use Illuminate\Support\Facades\DB;

public function test_la_carga_anticipada_evita_consultas_por_cada_linea()
{
    Documento::factory()->count(5)->hasLineas(3)->create();

    DB::enableQueryLog();

    Documento::with('lineas')->get()->each(
        fn ($documento) => $documento->lineas->count()
    );

    // Una consulta para documentos, una para todas las líneas
    $this->assertCount(2, DB::getQueryLog());
}

Si quitas el with('lineas'), esta prueba falla con seis consultas en vez de dos. Esa es la señal de que la aserción está midiendo lo que crees.

3. Que el borrado se comporta como esperas

Si configuraste que al borrar un padre se borren sus hijos en cascada, pruébalo:

public function test_al_borrar_el_documento_se_borran_sus_lineas()
{
    $documento = Documento::factory()->hasLineas(2)->create();
    $idsLineas = $documento->lineas->pluck('id');

    $documento->delete();

    foreach ($idsLineas as $id) {
        $this->assertDatabaseMissing('lineas_de_detalle', ['id' => $id]);
    }
}

Aquí hay un detalle que conviene conocer: si la cascada está definida en la base de datos con onDelete('cascade'), el comportamiento depende del motor. Las pruebas de Laravel suelen correr sobre SQLite en memoria por velocidad, y SQLite no aplica claves foráneas a menos que se activen explícitamente. Una prueba que pasa en tu entorno podría no reflejar lo que ocurre en producción si los motores difieren.

Puedes verificar contra qué motor estás corriendo:

php artisan test --filter=test_al_borrar_el_documento -v

Y si quieres que las pruebas usen el mismo motor que producción, configúralo en phpunit.xml:

<env name="DB_CONNECTION" value="mysql"/>
<env name="DB_DATABASE" value="almcns_testing"/>

Es más lento, pero prueba lo que de verdad va a ocurrir.

4. Que los datos de captura histórica se conservan

Este es sutil y muy valioso. A veces guardas una copia de un dato en el momento de una transacción, por ejemplo el nombre y el precio de un producto tal como estaban ese día, en lugar de depender siempre del registro vivo. Una prueba puede confirmar que si el registro original cambia después, la copia guardada conserva su valor:

public function test_la_linea_conserva_el_precio_del_momento_de_captura()
{
    $producto = Producto::factory()->create(['precio' => 100.00]);

    $linea = LineaDeDetalle::factory()->create([
        'id_producto' => $producto->id,
        'precio'      => $producto->precio,
    ]);

    $producto->update(['precio' => 250.00]);

    $this->assertSame('100.00', $linea->fresh()->precio);
    $this->assertSame('250.00', $linea->producto->fresh()->precio);
}

Las dos aserciones juntas son las que dan el valor: confirman que la copia no se movió y que la relación hacia el registro vivo sigue funcionando. Es la diferencia entre un histórico confiable y uno que se reescribe solo.

El fresh() aquí no es decorativo. Sin él estarías consultando el objeto que ya tienes en memoria, no lo que quedó guardado, y la prueba pasaría incluso si la base de datos dijera otra cosa.

Cómo ejecutarlas

Las pruebas se ejecutan en la terminal, desde la raíz del proyecto. No hay nada que abrir en el navegador.

Toda la suite:

php artisan test

Solo tu archivo:

php artisan test tests/Feature/DocumentoRelacionesTest.php

Un solo caso, por nombre:

php artisan test --filter=test_la_linea_conserva_el_precio_del_momento_de_captura

Una salida exitosa se ve así:

   PASS  Tests\Feature\DocumentoRelacionesTest
  ✓ la linea llega a su documento                        0.34s
  ✓ el documento ve todas sus lineas                     0.08s
  ✓ la carga anticipada evita consultas por cada linea   0.11s
  ✓ al borrar el documento se borran sus lineas          0.09s
  ✓ la linea conserva el precio del momento de captura   0.10s

  Tests:    5 passed (12 assertions)
  Duration: 0.72s

Cuando algo falla, la salida te dice qué esperaba y qué obtuvo:

  ⨯ el documento ve todas sus lineas

  Failed asserting that actual size 0 matches expected size 3.

  at tests/Feature/DocumentoRelacionesTest.php:31

Ese “size 0” es exactamente el síntoma del que hablábamos al principio: la relación devuelve vacío sin lanzar ningún error. La diferencia es que ahora aparece en tu terminal en menos de un segundo, y no en un reporte de producción dentro de tres semanas.

Si prefieres no escribir el comando cada vez, puedes dejarlas corriendo en modo observador:

php artisan test --watch

Un consejo que ahorra dolores de cabeza

Si tu base de datos no usa la convención de nombres por defecto del ORM, declara la clave foránea de forma explícita en cada relación. No dependas de que el framework la adivine:

public function lineas()
{
    return $this->hasMany(LineaDeDetalle::class, 'id_documento', 'id');
}

Es un argumento más por relación y elimina de raíz toda una categoría de errores silenciosos.

Una red de seguridad para refactorizaciones

El mayor valor de estas pruebas aparece cuando tienes que modificar la estructura de datos. Agregar tablas, normalizar información que antes estaba mezclada, cambiar cómo se conectan las entidades: son cambios que tocan muchas piezas a la vez y donde es fácil romper una relación sin darte cuenta.

Con un conjunto de pruebas de relaciones en su lugar, cada cambio se valida solo. Si una modificación rompe la conexión entre dos modelos, lo sabes en segundos, no cuando un usuario reporta que un reporte sale vacío. Esa retroalimentación inmediata es lo que convierte una refactorización arriesgada en una rutina controlada.

En resumen

Las relaciones entre modelos son la fontanería de una aplicación: invisibles cuando funcionan, catastróficas cuando fallan. Dedicarles pruebas propias no lleva mucho tiempo, sobre todo apoyándote en factories que preparen los datos, y a cambio obtienes una red de seguridad que atrapa una clase de errores que de otro modo llegarían hasta el usuario final.

La próxima vez que definas una relación, considera escribir junto a ella una prueba breve que confirme que carga bien, en ambos sentidos. Tu yo del futuro, en medio de una refactorización, te lo agradecerá.

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.

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.

Para hacer esto lo podemos hacer con una consulta utilizando los comandos de COUNT, GROUP BY y HAVING,  vamos a ver como sería nuestra consulta:

SELECT name,COUNT(*) FROM clients
GROUP BY name
HAVING COUNT(*) > 1;

En esta consulta estamos solicitando de la tabla “clients” los registros donde el nombre se repita más de una vez.

Ahora vamos a explicar qué hace cada comando:

COUNT: Regresa el número de registros.

GROUP BY: Agrupa las filas que tiene el mismo valor y devuelve una única fila de cada agrupación realizada.

HAVING: Específica la condición que se aplica a los grupos, cuándo tenemos el comando GROUP BY no podemos usar la clausula WHERE, así que ahí es donde usamos HAVING.

Si quieres saber más sobre estos comandos puedes buscar en la documentación de MySQL:

https://dev.mysql.com/doc