Catálogo en línea y marketplace
Cómo funcionan los dos canales de publicación de ElVendedor, qué repos intervienen, cómo se publican productos y se atienden pedidos, y qué límites tiene el backend.
El ecosistema publica productos en dos canales que el negocio administra desde la app de gestión: el marketplace multi-vendedor y el catálogo en línea de cada negocio. Aquí ves cómo se publican, cómo llegan los pedidos y qué debe estar bien configurado.
Dos canales que no se mezclan
| Canal | Qué es | Precio | Pedido |
|---|---|---|---|
| Marketplace | Escaparate con productos de varios negocios | public_price de la publicación |
Cotización, reserva y orden en el backend |
| Catálogo en línea | Página pública de un negocio en {subdominio}.miraloaki.com |
Precio propio, sin conversión | Mensaje de WhatsApp; no pasa por el backend |
Repos implicados
| Repo | Rol |
|---|---|
el-vendedor-back |
Autoridad: publicaciones, disponibilidad, reservas, cotizaciones y órdenes |
el-vendedor (móvil) |
Único cliente que crea publicaciones y atiende pedidos |
miraloaki |
Frontends: marketplace-web y catalog-web |
el-vendedor-desktop |
Fuera del canal: no sincroniza estas entidades |
Flujo de publicación de productos
- El producto existe en el catálogo de gestión con su almacén y su precio.
- En la app móvil se crea la publicación: título y descripción públicos, precio público, moneda, almacén de origen e imágenes.
- Se guarda en
PouchDBy se encola como evento de sync demarketplace_product_publications. - El backend la aplica por
upsertsobrebusiness_id+product_external_id(una por producto y negocio). Las imágenes viajan como URLhttp(s)o comoimageUploadsen base64 (máximo 5 MB) y se guardan en el discopublic, bajomarketplace/business-{id}/products/….
| Estado | Efecto |
|---|---|
draft |
Borrador; no se ve en la API pública |
published |
Visible en GET /api/marketplace/v1/catalog/products |
paused |
Se oculta sin borrar la publicación |
archived |
Retirada; deja de listarse |
Borrar un producto de gestión no borra la publicación: revísalo al retirar
mercancía. El catálogo en línea sigue el mismo camino con catalog_storefront
(singleton current_catalog) y catalog_products; el slug se fija al crear el
producto y no cambia al renombrarlo.
Flujo de pedidos del vendedor
catálogo público → POST /quotes (15 min) → POST /quotes/{q}/reserve
→ POST /quotes/{q}/confirm → MasterOrder + una SellerOrder por negocio- La cotización congela precios y no puede mezclar monedas: dos publicaciones
en divisas distintas devuelven
422. - La reserva descuenta disponibilidad por negocio.
- La confirmación exige la cotización
reservedy vigente, y crea la orden maestra con una orden por vendedor (SO-…). - El vendedor ve sus órdenes en
GET /api/v1/marketplace/seller-orders, acotadas a su negocio, y puede aceptar, rechazar o avanzar la preparación (preparing → ready → dispatched → delivered, solo hacia adelante). - Al aceptar se crea una venta con
payment_method='marketplace', se descuenta stock por líneas y se confirma la reserva. La orden maestra pasa ain_fulfillment; con todas las ventas entregadas, acompleted.
Endpoints
| Método y ruta | Uso |
|---|---|
GET /api/marketplace/v1/catalog/products |
Listado público: q, business_id, in_stock, currency, per_page (50) |
POST /api/marketplace/v1/quotes |
Cotización (lines[] con publication_id y quantity) |
POST …/quotes/{id}/reserve · /confirm |
Reserva y orden maestra |
GET /api/marketplace/v1/orders · /{orderNumber} |
Consulta por consumer_id o order_numbers[] |
POST /api/marketplace/v1/auth/register · /login |
Cuenta de consumidor (Sanctum, ability consumer) |
GET /api/v1/marketplace/seller-orders |
Bandeja del vendedor: status, per_page (50) |
POST …/seller-orders/{id}/accept · /reject · PATCH …/status |
Aceptar, rechazar o avanzar |
GET /api/catalog/v1/storefronts/{subdominio}/products |
Catálogo público: q, category, only_available, featured, sort, per_page (60) |
GET / PUT /api/v1/catalog/storefront · POST …/products/import |
Administración del catálogo e importación de publicaciones |
Las rutas de vendedor y de administración exigen auth:sanctum y negocio
actual; sin negocio responden 409, y la orden de otro negocio responde 404.
Relación con el POS y la sincronización
La disponibilidad del marketplace es una proyección: stock por almacén menos
reservas activas. Una venta aceptada genera una venta normal en el backend y
descuenta stock. La reserva caduca a los 15 minutos y el cron
inventory:expire-reservations la expira cada cinco; si no corre, el stock
aparece bloqueado sin pedidos que lo justifiquen.
Requisitos de despliegue y entorno
- PHP 8.2 o superior (probado con 8.4.5), Laravel 12, migraciones de marketplace, catálogo y reservas aplicadas, y seeders de categorías y monedas.
- Disco
publicenlazado (php artisan storage:link) para imágenes de publicaciones; el catálogo escribe enpublic/catalog/…y se limpia conphp artisan catalog:prune-images. CORS_ALLOWED_ORIGINScon el origen del marketplace-web en producción.CATALOG_BASE_DOMAINyCATALOG_SCHEMEpara resolver{subdominio}, con DNS y certificado wildcard.- Tareas programadas activas: expiración de reservas y poda de eventos de sync.
- Frontends:
NUXT_PUBLIC_API_BASE(marketplace) yNUXT_CATALOG_API_BASEconNUXT_PUBLIC_CATALOG_SOURCE=rest.
Contrato y código
El digest miraloaki/docs/backend/api-contract.md es anterior a la auth de
consumidor y a las monedas gestionadas; cuando difiera, manda routes/api.php.
Límites conocidos
delivery_totalyfees_totalsiempre valen0: no hay cálculo de envío.- No hay pasarela de pago: la confirmación guarda un snapshot, no cobra.
- No existe CRUD REST de publicaciones: se administran por sync desde el móvil.
- Del vendedor solo se expone
business.{id,name,slug,photo}; el precio del catálogo no se hereda del marketplace.
Diagnóstico
| Síntoma | Causa probable | Comprobación |
|---|---|---|
| Producto ausente del catálogo público | Publicación en draft, paused o archived |
GET /catalog/products/{id} da 404 |
| Aparece sin stock | Sin proyección, todo reservado o cron detenido | php artisan marketplace:health |
409 al llamar al marketplace |
Token sin negocio actual | PUT /api/v1/auth/current-business |
422 al cotizar |
Cotización vencida, monedas mezcladas o sin stock | Revisa expires_at y la moneda |
| Imágenes rotas | storage:link sin ejecutar o APP_URL incorrecto |
Abre la URL de la publicación |
Catálogo con 404 |
Subdominio no publicado o dominio mal configurado | Consulta la tienda y el DNS |
Siguiente paso
- Sincronización para el protocolo y los conflictos.
- Diagnóstico para incidentes en producción.
¿Falta algo o encontraste un error?
Ayúdanos a mejorar esta documentación con tu experiencia real.
Escribir a soporte