VulCode

Shoper integration with wholesalers, ERP and Allegro

Wholesaler products reach your Shoper store by themselves, orders flow to Subiekt or another ERP, and stock matches Allegro. Through the Shoper REST API, within its limits.

E-commerce platforms
The Shoper store integration panel: one product from three wholesalers matched by EAN, the wholesaler choice rule and the selling price with margin and VAT

Two routes into the Shoper API

Shoper distinguishes integrating one store from an app for many stores. Authorisation depends on it.

WebAPI user

One store's integration. We exchange the login and password of a user with WebAPI access for a token.

An app in the Shoper App Store

An app for many stores. Authorisation through OAuth with an authorisation code and a refresh token.

  • WebAPI user: A login and password for a token

    A user with WebAPI access exchanges them for a token at /webapi/rest/auth. Without that access Shoper refuses authorisation.

    An app in the Shoper App Store: An authorisation code and a refresh token

    OAuth with grant_type authorization_code. A refresh token renews access, with no store login or password.

  • WebAPI user: You install it

    You create the user in your store panel, with access to the resources it needs only.

    An app in the Shoper App Store: Every store installs it

    Every store that adds the app connects to it on its own.

  • WebAPI user: Wholesalers, ERP and couriers

    It fits your store's integration with wholesalers, ERP and couriers.

    An app in the Shoper App Store: A tool for other stores

    We build one when the integration is meant for many stores.

For one store a WebAPI user with limited permissions usually suffices. We build an app when the integration is meant for many stores.

The token and request limit in practice

Shoper counts requests as a leaky bucket and says in headers how much is left. The import log shows how the queue uses that.

The log of an import into Shoper: the request bucket filling from the headers, a 429 refusal with Retry-After, the retry and the WebAPI user with its permissions

  1. A wholesaler change

    e.g. new stock or a price

  2. A token for the WebAPI user

    POST /webapi/rest/auth

    The integration's own account, with access to the resources it needs only, not an admin account.

  3. A counter from headers

    X-Shop-Api-Calls / X-Shop-Api-Limit

    Headers say how many calls were used and what the limit is. With a full bucket the queue slows down.

  4. A refusal and a retry

    Retry-After

    Over the quota Shoper says in Retry-After how long to wait. The queue waits exactly that long and retries, like the official library, up to 5 times by default.

  5. Written to the store

    under the store address, at /webapi/rest

A wholesaler product in a Shoper store

The most common Shoper integration. The mapping decides whether customers see a clean listing or chaos.

Building blocks, a 480-piece set

The same product is in three wholesalers. The rule picked Wholesaler 01, the cheapest with at least 5 pieces.

A row of the Wholesaler 01 file

Wholesaler code
H1-KL480
EAN
5901234300028
Net purchase price
PLN 82.40
Wholesaler stock
46 pcs
Category in the file
Toys > Blocks

A shared key

Store product
KLC-480, the same EAN
Rule

Product code and EAN with no duplicates. When one EAN has several wholesalers, the rule picks one.

Margin and VAT

After a 35% margin
PLN 111.24 net
With 23% VAT
PLN 136.83
With the price ending
PLN 136.99
Rule

The category margin, the VAT rate and the price ending by your rules.

Stock and category

Store stock
46 pcs, no buffer at this level
Store category
Toys > Building blocks
Rule

A stock buffer at low quantities, the category from a map agreed once.

The product on Shoper

Building blocks, a 480-piece set
  • PLN 136.99 with VAT
  • Available, 46 pcs
  • 4 images downloaded and added through the API, not hot-linked

What flows between Shoper and the back office

Each direction has its own resource in the Shoper REST API.

A product page of a Shoper store on a phone: the price with VAT, availability, product code, EAN, images and the add to cart button
ShoperERP, wholesalers, couriers
  • Orders and their linesOrderOrderProductA webhook or polling the Order and OrderProduct resources.
  • Products and imagesProductProductImageA new file or a wholesaler API change.
  • StockProductStockAn ERP document or an Allegro sale, with a buffer at low quantities.
  • ParcelsParcelA parcel dispatched with a courier, with the tracking number.
  • Order statusA change in the store or the ERP.

What we watch out for with Shoper

What decides whether the integration survives a big catalogue.

  • A separate WebAPI user

    The integration gets its own account with access to the resources it needs only, not an admin account.

    BasicAuth.php in Shoper's library

  • A request counter from headers

    A big import fills the bucket fast. The queue reads the headers and slows down before Shoper refuses.

    Http.php in Shoper's library

  • Hiding instead of deleting

    A deleted product leaves a dead URL. A hidden one keeps its URL and Google position.

    Website and store migration

  • Redirects on changes

    Shoper has a redirect resource in its API, so a product URL change can get a redirect straight away.

    Redirect.php in Shoper's library

Common questions about Shoper

Answers about ready apps, imports, migration and the quote.

Where does your Shoper store get its goods?

Tell us which wholesalers and ERP you use. We will reply within an hour with questions and a quote.