Referencia de la API

URL base y formato de respuesta

Todas las rutas se sirven con el prefijo /api. En local, la URL base es http://localhost:8000/api. En un servidor es la dirección de tu API seguida de /api, el mismo valor que ambos frontends leen de NEXT_PUBLIC_API_BASE_URL (Variables de entorno).

La API sirve a dos públicos que nunca comparten un token: los clientes, que usan las rutas de la tienda, y el personal, que usa las del panel de administración. Los cuerpos de las solicitudes son JSON, salvo las subidas de archivos. Cada respuesta llega en el mismo envoltorio:

{
  "success": true,
  "data": { },
  "message": ""
}

data contiene el resultado. message es una frase corta que rellenan algunas escrituras, traducida al idioma de la solicitud, y vacía en los demás casos.

La comprobación de estado es la única ruta fuera del envoltorio. No necesita token:

curl http://localhost:8000/api/health

{"status":"ok"}

Responde 503 con {"status":"unavailable"} mientras no se puede acceder a la base de datos o esta no tiene tablas, así que un balanceador de carga puede usarla como sonda de disponibilidad.

Errores

Una solicitud fallida responde con el estado HTTP correspondiente y el mismo envoltorio, con success: false, data: null y, en la validación, los problemas por campo:

{
  "success": false,
  "data": null,
  "message": "<the first field's problem>",
  "errors": {
    "email": ["<the problem with email>"]
  }
}

Las escrituras correctas responden 201 para POST y 200 para los demás métodos.

Paginación y ordenación

Las listas reciben page, desde 1, y page_count, el tamaño de página. Una página contiene como máximo 100 filas: un tamaño mayor se lee como 100, uno menor como 1, y uno ausente o ilegible recurre al valor por defecto de la lista. Una lista responde siempre con la misma forma:

{
  "success": true,
  "data": { "data": [ ], "page": 1, "limit": 15, "total": 35, "totalPages": 3 },
  "message": ""
}

• order=asc u order=desc fija el sentido en productos, categorías, clientes y pedidos. Las categorías van por defecto en orden ascendente, y las demás de más reciente a más antiguo.
• Los productos también se ordenan con sort: created_at, updated_at, price, rating o best_selling. Un valor desconocido recurre al orden por defecto, de actualización más reciente a más antigua, con los empates resueltos por id. order_by_featured=true pone primero los productos destacados y los más vendidos.
• La lista de productos filtra por search (nombre en cualquiera de los dos idiomas, o SKU), category_id, is_active, is_featured, is_best_seller, min_price, max_price, tag y on_sale.

Idioma

Envía el idioma del lector en la cabecera Accept-Language: en o ar tal como se entrega. ar-SA cuenta como árabe, y cualquier idioma que la API no tenga se responde en inglés. No hay ningún parámetro de consulta para el idioma.

• Los mensajes de error y el message de una escritura correcta se traducen.
• El texto guardado en ambos idiomas, como los nombres de productos y categorías, vuelve como { "en": "...", "ar": "..." } y el cliente elige uno.

Autenticación

Los clientes y el personal inician sesión en endpoints distintos, contra tablas distintas, y reciben tokens que solo aceptan sus propias rutas.

• Ambos son JWT firmados con JWT_SECRET. Envíalos como Authorization: Bearer <token>.
• Un token dura JWT_EXPIRATION, 7d por defecto (Variables de entorno). El inicio de sesión del personal indica el mismo valor como expires_in.
• No hay endpoint de renovación. Cuando un token caduca, la siguiente solicitud responde 401 y el cliente vuelve a iniciar sesión.
• Un token de cliente se rechaza en las rutas de administración y un token de personal en las rutas de clientes, aunque ambos usan el mismo secreto.
• Un inicio de sesión fallido responde 401 con un único mensaje, tanto si el correo no tiene cuenta como si la contraseña es incorrecta.
• Las rutas de inicio de sesión, registro, contraseña y seguimiento de pedidos aceptan 10 intentos por minuto desde una misma dirección, contados por ruta. Pasado ese límite responden 429 con una cabecera Retry-After. El recuento se guarda en la memoria de la API, así que vuelve a empezar con un reinicio y cada instancia lo cuenta por separado. Detrás de un proxy, consulta TRUST_PROXY (Solución de problemas).

1. 01

   Inicia sesión como el Super Admin de los datos iniciales

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"admin@example.com","password":"Admin@123"}'

   RespuestaCopiar

   {
     "success": true,
     "data": {
       "access_token": "eyJhbGciOiJIUzI1NiIs...",
       "token_type": "Bearer",
       "expires_in": "7d",
       "admin": {
         "id": 1,
         "email": "admin@example.com",
         "roles": [{ "id": 1, "name": "Super Admin", "guard_name": "web" }],
         "permissions": ["admins.view", "admins.create", "..."]
       }
     },
     "message": "..."
   }
2. 02

   Llama a una ruta protegida con el token

   TerminalCopiar

   curl "http://localhost:8000/api/orders?page=1&page_count=5" \
     -H "Authorization: Bearer <access_token>"

   Resultado esperado: Los cinco pedidos más recientes, con la forma de lista.
3. 03

   Inicia sesión como un cliente de los datos iniciales

   La tienda de demostración también incluye clientes, como john.doe@example.com con la contraseña password123:

   TerminalCopiar

   curl -X POST http://localhost:8000/api/auth/customer/login \
     -H "Content-Type: application/json" \
     -d '{"email":"john.doe@example.com","password":"password123"}'

   Después pasa data.token de la misma forma, por ejemplo a GET /api/orders/my.

Permisos

Cada ruta de administración comprueba primero el token y luego el permiso que indica. Un administrador tiene todos los permisos de todos sus roles; cuando una ruta indica varios, basta con uno de ellos. En las tablas de administración de abajo, un nombre de permiso en la columna Quién puede llamarla significa un administrador cuyos roles lo conceden.

Las secciones de la página de inicio y el estudio de IA usan los permisos de productos. Las reseñas no tienen permiso propio: el panel las lee a través de los productos.

Volver a ejecutar la carga de datos crea lo que falta y deja los permisos de los roles existentes tal como los configuraste.

Catálogo público

No se necesita token. Los compradores solo ven productos activos: sin un token de administrador, un producto inactivo o eliminado no existe.

Registro y cuentas de clientes

Los clientes con sesión iniciada también tienen disponible un carrito en el servidor. La tienda incluida guarda su carrito en el navegador y no lo llama.

Pedidos, pago y seguimiento

Con payment_method: "stripe" y Stripe configurado, la respuesta incluye un client_secret que la tienda confirma con Stripe. El envío es gratis a partir de un subtotal de 75 y cuesta 9.99 por debajo; el impuesto es 0. Un promo_code se guarda en el pedido, pero no se aplica.

• Pagos

Inicio de sesión y cuentas del personal

Roles

Clientes

A los clientes se les identifica por su nombre de usuario. La lista filtra por search, email, phone, country_id, username, first_name, last_name, verified, from_date y to_date.

Productos y categorías

Las claves de las secciones son style-pillars, editorial-split, new-drops, best-sellers, spotlight, lux-difference y editorial-slider.

Pedidos

La API acepta cualquier cambio de estado; el panel solo ofrece el paso siguiente o una cancelación.

Ajustes

No hay ninguna ruta para crear un ajuste: los crea la carga de datos. Nada en el código incluido lee sus valores.

Subida de archivos multimedia

• Formulario multipart: el archivo en file, la carpeta en path (uploads por defecto) y, de forma opcional, un tamaño predefinido en for.
• Hasta 150 MB. Los videos (MP4, WebM, MOV, M4V) se guardan tal cual y responden { "original": url }.
• Las imágenes se vuelven a codificar en JPEG, con 1920 píxeles de ancho como máximo, más el tamaño predefinido, y responden con cada URL, como { "original": url, "250x250": url }.
• Sin las cinco variables R2_* responde 503: "File uploads are not set up yet."

Notificaciones

• Las notificaciones en directo usan Socket.IO en el espacio de nombres /notifications, en la dirección de la API sin /api. Envía el token del personal en auth.token del handshake; los tokens de clientes se desconectan.
• Cada una nueva llega como notification:created. Los tipos son order_created, para todos los administradores que pueden ver pedidos, y studio_generation_completed y studio_generation_failed, para el administrador que inició la generación.
• Un segundo espacio de nombres, /auth, envía permissions-updated cuando cambian los roles o los permisos de un administrador.
• El socket solo acepta conexiones desde FRONTEND_URL.

Asistente de IA

Estudio de IA

Probador

Rutas del modo demostración