ElVendedorDocs

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.

Para implementadores5 min de lecturaActualizado el 16 de noviembre de 2026

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

  1. El producto existe en el catálogo de gestión con su almacén y su precio.
  2. 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.
  3. Se guarda en PouchDB y se encola como evento de sync de marketplace_product_publications.
  4. El backend la aplica por upsert sobre business_id + product_external_id (una por producto y negocio). Las imágenes viajan como URL http(s) o como imageUploads en base64 (máximo 5 MB) y se guardan en el disco public, bajo marketplace/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 reserved y 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 a in_fulfillment; con todas las ventas entregadas, a completed.

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 public enlazado (php artisan storage:link) para imágenes de publicaciones; el catálogo escribe en public/catalog/… y se limpia con php artisan catalog:prune-images.
  • CORS_ALLOWED_ORIGINS con el origen del marketplace-web en producción.
  • CATALOG_BASE_DOMAIN y CATALOG_SCHEME para 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) y NUXT_CATALOG_API_BASE con NUXT_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_total y fees_total siempre valen 0: 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

↑↓ para navegar · Enter para abrir · Esc para cerrar