Organización, tienda y vendedor
Cómo Admin y Storefront determinan el alcance de cada petición.
Última actualización:
Los recursos comerciales pertenecen a una organización, una tienda y, cuando aplica, un vendedor. La forma de seleccionar ese contexto depende de la API.
Los tres niveles
Organización. Agrupa la cuenta, el plan, la facturación, los usuarios y una o varias tiendas.
Tienda. Aísla catálogo, pedidos, clientes y configuración. Recibe un dominio
*.ecomiq.app y puede conectar un dominio propio.
Vendedor. Identifica al dueño de la oferta dentro de una tienda. En una tienda simple suele ser único; en un marketplace puede haber varios.
Cómo se resuelve el contexto
| API | Tienda | Vendedor |
|---|---|---|
| Admin | Claim store_id del token o cabecera x-Store-Id. | Aplicación OAuth y claim seller_id del token. |
| Storefront | Header x-Store-Domain con el slug o un dominio configurado. | Lo determina la configuración de la tienda. |
| Auth | No usa el dominio comercial para seleccionar una tienda. | Depende de la aplicación o identidad que solicita el token. |
Un token de cliente en Storefront identifica al comprador cuando la operación lo requiere. No sustituye el dominio que selecciona la tienda.
Contexto de Admin
Una aplicación vinculada a una tienda recibe su contexto autorizado en el token. Envía ese token como bearer:
curl "https://api.ecomiq.pe/api/v1/catalog/products?limit=25" \
-H "Authorization: Bearer $ECOMIQ_TOKEN"Los claims store_id y seller_id, cuando aplican, identifican la tienda y el
vendedor autorizados.
Una aplicación de organización recibe un token sin store_id y con la lista de
tiendas permitidas. En cada solicitud a un recurso de tienda, indica cuál con la
cabecera x-Store-Id:
curl "https://api.ecomiq.pe/api/v1/catalog/products?limit=25" \
-H "Authorization: Bearer $ECOMIQ_TOKEN" \
-H "x-Store-Id: $ECOMIQ_STORE_ID"Si el token ya está vinculado a una tienda, la cabecera se ignora.
Contexto de Storefront
Para una integración directa, usa el gateway central y envía el slug, el
subdominio asignado o un dominio propio ya configurado en x-Store-Domain:
curl "https://storefront.ecomiq.pe/api/v1/products?page=1&pageSize=24" \
-H "x-Store-Domain: mi-tienda"El backend también puede resolver la tienda desde el host cuando la solicitud
llega con un subdominio *.ecomiq.app o dominio propio configurado. Esa forma
depende del ingress o proxy del despliegue; no reemplaza el gateway central en
una integración servidor a servidor. Las credenciales de Admin no seleccionan
una tienda pública.
Identificadores y aislamiento
Un identificador solo es útil dentro del contexto al que pertenece. Si un producto existe pero la petición usa otra tienda o vendedor, la operación no debe exponerlo.
Comprueba el contexto
Ante un 403 o 404, confirma el token, la aplicación OAuth o el dominio de
Storefront antes de asumir que el recurso fue eliminado.
No se mueve un recurso entre tiendas cambiando su identificador. Para replicar datos, crea o importa el recurso en la tienda destino.
Varias tiendas
No asumas que un mismo token puede operar en varias tiendas. Una aplicación OAuth suele estar vinculada a una tienda y a un vendedor.
Para otra tienda, crea una aplicación OAuth con acceso explícito en esa tienda y solicita un token con sus credenciales. Cambiar el dominio no modifica el contexto de Admin.
Marketplaces
En Admin, el vendedor autorizado forma parte del contexto de la aplicación y,
cuando corresponde, aparece en el claim seller_id. No existe un parámetro de
consulta que amplíe ese alcance.
En Storefront, la tienda y su configuración determinan qué ofertas se publican. La sesión del comprador no permite elegir un vendedor administrativo.