Seller portal¶
The seller-facing side of the marketplace: a Vue 3 SPA talking to a REST surface
under /flyok-portal/*, served by the Base plugin on the Shopware host in
every deployment mode (Base owns these routes; Remote doesn't move them).
The SPA¶
The portal is distributed as a separate Vue 3 build. It is configured via its
.env:
VITE_FLYOKAI_URL=https://shop.example # Shopware host serving /flyok-portal/*
VITE_PLATFORM_URL=https://shop.example
VITE_OAUTH_CLIENT_ID=<marketplace:oauth:client:create>
VITE_OAUTH_CLIENT_SECRET=<marketplace:oauth:client:create>
At runtime the SPA bootstraps from GET /flyok-portal/config, which returns the
public OAuth client id, the allowed origin and the portal URL — so the build is
environment-agnostic.
The Shopware host must allow the SPA's browser origin for CORS. Set it under
Settings → Plugins → FlyokaiMarketplace → Seller portal → Seller portal CORS
origin (sellerPortalOrigin, default http://localhost:5173).
Authentication¶
The portal uses an OAuth password grant to exchange a seller's username +
password for a portal JWT, then sends that JWT as a bearer token on every
/flyok-portal/* call.
SPA ──POST /flyok-app/oauth/access_token (grant_type=password, client creds)──► Shopware
SPA ◄────────────── JWT (RS256, ~1h TTL) ────────────────────────────────── Shopware
SPA ──GET /flyok-portal/sellers/me Authorization: Bearer <jwt> ───────────► Shopware
- The JWT is RS256, signed with the RSA keypair at
var/marketplace/oauth.id_rsa(rotate viamarketplace:oauth:keypair:generate). /flyok-portal/*routes run under the customFlyokPortalRouteScope; a JWT validator verifies the signature and resolves the calling seller before the controller runs. The seller can only ever see their own data — every…/me/…endpoint is scoped to the JWT's subject.- The OAuth client itself is created with
marketplace:oauth:client:create; its secret is hashed (argon2id) server-side, with the plaintext handed to the SPA via config once.
Two keypairs, don't confuse them
var/marketplace/oauth.id_rsa{,.pub} signs portal JWTs (Base ↔ portal).
The separate flyokaiOAuthPublicKeyPath config points at Flyokai's OAuth
public key, used when verifying tokens that originate from the Flyokai stack.
Rotating one does not affect the other.
REST surface¶
All paths below are relative to the Shopware host. Unless noted, they require a valid portal JWT and act on the calling seller only.
Session & metadata¶
| Method | Path | Purpose |
|---|---|---|
POST |
/flyok-app/oauth/access_token |
Password grant → portal JWT. |
GET |
/flyok-portal/config |
Public portal config (OAuth client id, origin, URL). |
GET |
/flyok-portal/field-metadata |
Field schemas that drive the portal forms. |
GET |
/flyok-portal/locations/countries |
Country / subdivision lookup. |
GET |
/seller-portal |
SPA HTML entry point. |
Seller profile¶
| Method | Path | Purpose |
|---|---|---|
GET PATCH |
/flyok-portal/sellers/me |
Read / update the seller profile. |
GET POST PATCH DELETE |
/flyok-portal/sellers/me/addresses |
Billing / shipping addresses. |
GET PATCH |
/flyok-portal/sellers/me/branding |
Store name, logo, banner. |
POST |
/flyok-portal/branding/media |
Upload logo / banner media. |
GET POST PATCH DELETE |
/flyok-portal/sellers/me/stock-sources |
Warehouses / stock sources. |
GET POST PATCH DELETE |
/flyok-portal/sellers/me/shipping-profiles |
Shipping profiles, services, carriers. |
Catalogue & offers¶
| Method | Path | Purpose |
|---|---|---|
GET |
/flyok-portal/products |
Products the seller owns or may offer against. |
GET POST PATCH DELETE |
/flyok-portal/sellers/me/offers |
List / create / edit / transition the seller's offers. |
Orders & fulfilment¶
| Method | Path | Purpose |
|---|---|---|
GET |
/flyok-portal/sellers/me/purchase-orders |
The seller's POs (read-only), grouped by order. |
GET PATCH |
/flyok-portal/order-deliveries |
Shipment tracking — transition a delivery to shipped. |
Finance¶
| Method | Path | Purpose |
|---|---|---|
GET |
/flyok-portal/sellers/me/statements |
The seller's statements. |
GET |
/flyok-portal/sellers/me/payouts |
The seller's payouts (status, amount, date). |
Messaging¶
| Method | Path | Purpose |
|---|---|---|
GET POST PATCH |
/flyok-portal/mail/me/inbox |
Inbox, compose, reply, archive. See Messaging. |
Bulk import/export¶
Added by the optional Bulk plugin under
/flyok-portal/bulk/* — same JWT auth, same per-seller scoping.
Where requests go¶
In Base, a /flyok-portal/* controller builds a ServiceRequest and calls
LocalMarketplaceBackend (in-process). With Remote installed, the
same controllers call RemoteMarketplaceBackend and the work runs on the
cluster — the portal and its auth are unchanged either way.