Help › Marketplace

Marketplace Integration — A Guide from Scratch

A company selling on Trendyol, Hepsiburada, Tokopedia or Shopee usually copies orders from the seller panel by hand, corrects stock platform by platform every evening and never quite knows why the money the platform pays out at month end is short. The Marketplace window ties this work to HNR: platform orders arrive in HNR as sales orders, packing and shipping details are reported back to the platform, free stock and prices in HNR are sent to the platform, returns and platform deductions are tracked, and the expected settlement for the period is calculated.

1. Overview: platforms and maturity

There are four real platforms and one test driver. For Türkiye Trendyol and Hepsiburada, for Indonesia Tokopedia and Shopee; Simulation lets you rehearse the same flow with sample orders without connecting to a real marketplace. A company can open several connections (even two stores on the same platform).

Credentials are encrypted with the same key (HNR_BANKA_KIMLIK_ANAHTARI) as the live bank connection. If the key is not defined, a red warning appears in the window and no platform can be connected; the system administrator provides the key to the Node launcher.

2. The flow at a glance

1. Connection — the system administrator picks the platform in Settings, enters the credentials, sets the platform account and intervals, and tests the connection.
2. Product mapping — each platform product is linked to a stock card (by hand, by CSV/XLSX or from barcode suggestions).
3. Order download — new orders are fetched; an order whose products are all mapped is written to HNR as a sales order in the PZ series and reserves stock.
4. Pack → Ship → Delivered — every step is reported to the platform; the tracking number comes from the shipment, from the platform or by hand.
5. Stock and price — free stock in HNR is sent to the platform after the platform share and buffer are applied; prices are sent including VAT. Only changes are sent.
6. Returns and settlement — platform returns come in and show the work to do in the error queue; the Settlement tab deducts commission, shipping deduction, service fee and returns from the period's gross sales.

3. Setting up a connection and credentials

Connections are in Settings › Company Information › Marketplace connections and are seen and managed only by the system administrator (even users with the marketplace permission cannot open the connection and credentials screen). For a new connection press New connection; the form has three steps.

1. Marketplace — choose the platform. The box shows the platform's document title, the maturity note and the To obtain from the platform list; collect the details from the seller panel beforehand.
2. Credentials and settings — connection name, platform account, warehouse, the platform's fields, intervals; then Save.
3. Test — Test connection: HNR tries to connect to the platform with the credentials. If it works you see "Connection test successful" and the status becomes Running; otherwise the error class is shown.

Fields requested per platform (starred ones are required; 🔒 = secret credential field). Field names appear on screen with the driver's own label:

• Trendyol: Satıcı ID* (seller ID), Ortam (environment: canli = live / test), Kendi kargo anlaşması (own carrier contract: hayir = no / evet = yes — if yes, the tracking number is sent from HNR to Trendyol), API Key* 🔒, API Secret* 🔒.
• Hepsiburada: Merchant ID*, Entegratör adı (User-Agent) (integrator name), Ortam (environment), Kendi kargo anlaşması (own carrier contract), API kullanıcı adı* 🔒 (API user name), Servis anahtarı* 🔒 (service key).
• Tokopedia: fs_id (App ID)*, Shop ID*, Tahmini komisyon oranı (%) (estimated commission rate — Tokopedia's order list carries no commission, so the settlement estimate uses this rate), Client ID* 🔒, Client Secret* 🔒.
• Shopee: Partner ID*, Shop ID*, Ortam (environment), Kargoya teslim (handover to carrier — dropoff: you drop the parcel at a branch · pickup: the courier collects it), Partner Key* 🔒, Access token* 🔒, Refresh token 🔒.
• Simulation: Tohum (seed — the same seed produces the same orders), Ürünler* (products, one per line: platform product code|price|name), Günlük sipariş sayısı (orders per day), Komisyon oranı (%) (commission rate), Kargodan teslime (dk) (minutes from shipping to delivery), İade edilecek sipariş numaraları (order numbers to return), Platformda iptal edilecek sipariş numaraları (order numbers to cancel on the platform), Para birimi (currency), Kullanıcı adı* 🔒 (demo), Parola* 🔒 (password).

Common fields are the same on every platform:

Connection card status: Awaiting test (saved, not tested yet or settings changed), Running (last test or sync successful), Error. A connection that has orders cannot be deleted and its marketplace cannot be changed — deactivate it (turn off automatic sync) or open a new connection. Deleting a connection without orders also deletes its saved credentials and product mappings.

4. Product mapping

The platform knows a product by its own code; HNR by the stock card. The Product mapping tab links the two. The mapping key is platform product code + variant; if the order line has a barcode, it is also found by barcode. If even one line of an order is unmapped, the order comes in but is not written to HNR (ESLEME_YOK); after adding the mapping, press Rewrite to HNR on the order.

• By hand — on the top row enter Stock card, Platform product code / barcode, Variant, Stock share %, Buffer, Fixed price and press Map. If the platform product is already mapped, the mapping is updated.
• Unmapped platform products seen in orders — products without a mapping in incoming orders are listed in a yellow box with their counts; click one to carry its code into the form, then just pick the stock card.
• Suggest from barcode — lists your unmapped stock cards that have a barcode as suggestions (GTIN-style 8/12/13/14-digit barcodes first; expense, service and labour cards excluded). Trendyol and Simulation identify products by barcode, so the suggestion can be used directly. Hepsiburada, Tokopedia and Shopee identify products by their own ID: barcode suggestions are certain only for products already seen in orders; for the others you enter the platform product code.
• Import CSV / XLSX — a file whose first row is a header: stok, urun (or barkod), varyant, sku, fiyat, pay, tampon. A preview comes first: "Import preview: … new, … to update, … invalid rows" with the invalid rows by number; Apply writes, Cancel drops it. At most 5,000 rows per file; the same platform product cannot appear twice; a row whose stock card is not found is skipped.

Stock share % is the percentage of free stock offered on this platform (default 100). Buffer is a safety quantity subtracted after the share (default 0) — so the last few items are not sold on two platforms at once. If Fixed price is filled, that price is sent to the platform as is. Instead of deleting a mapping you can Deactivate it: its stock and price are no longer sent, but past orders stay intact.

5. Orders: download and the HNR order

At the top of the Orders tab there are four boxes: Waiting to be packed, To ship, Shipped, Error queue; clicking a box filters the list to that status. The platform and status filters, the "Search order no., customer or HNR no." box and the columns (Date, Platform, Order no., Customer, Products, Amount, Status, HNR order) are here. Click a row to open the order card.

Download never duplicates. An order is identified by its platform number and package number; if the same order arrives again no new record is opened, only its status, tracking number and deductions are updated. A marketplace order is never deleted from HNR; cancellation is a status too and history is kept.

The HNR order. A new order whose products are all mapped and whose connection has a platform account is written to HNR as a sales order: account = platform account, document series PZ (e.g. PZ2026000001, channel "pazaryeri"; a number is issued once and never reused), description "Trendyol siparişi 123456 / package … [PZ#…]", delivery date = the platform's ship-by date, the end customer's name in the Attention field. The line price is the platform's selling price; since it includes VAT it is written to HNR as price = gross ÷ (1 + VAT/100). If writing is interrupted, the order is found again by the marker in the description; the same order is never written twice. Platform confirmation: on Tokopedia the order is confirmed on the platform after it is written to HNR; on the other platforms the packing step is the confirmation.

End-customer details. The buyer's name, e-mail, phone, Turkish ID / tax number (TCKN/VKN), tax office, invoice and delivery address are kept in the marketplace record (the account of the HNR order is the platform account; end-customer details are for the e-Archive invoice). In the list and on the card the ID number is masked (e.g. *******1234), e-mail a***@…, phone only the last four digits; addresses are hidden. Only users with the marketplace management permission see the full values, and every view is written to the audit trail.

Status machine. An order only moves forward: New → Approved → Packed → Shipped → Delivered. Cancel happens before delivery; Return after shipping or delivery. A step backwards coming from the platform (a delayed or old page) is ignored; cancellations and returns are always applied. If a transition that is not allowed is tried from HNR, the warning "The order cannot move from … to …." appears.

The HNR order column shows the state of the counterpart: Not written to HNR, Writing to HNR, HNR order open, Invoiced (automatically, once the order is invoiced in HNR), HNR order deleted. Two warnings are not errors but worth a look: "Free stock is short, the order became a backorder: …" (the order is still written) and "The order was shipped before the integration. The HNR order was not written (it can be written with retry)." (old orders shipped before the connection was set up are not written automatically).

6. Pack, ship, deliver

The buttons on the order card do the next step and report it to the platform first, then write the status; if the platform refuses, the status does not change and the error is shown. In the list, the Pack / Ship button on the row does the same.

• Pack — "being prepared/packed" is reported to the platform (Trendyol Picking/Invoiced; on Hepsiburada a package is created and its number is written to the order). Status Packed.
• Ship — the Tracking number and Carrier boxes are optional. If left empty, the tracking number is first read from Shipping (if the HNR order or its invoice is in a shipment, that shipment's tracking number and carrier), and otherwise comes from the platform's contracted carrier. On Trendyol and Hepsiburada, if Kendi kargo anlaşması = evet (own carrier contract = yes), the tracking number is sent from HNR to the platform; on Shopee the dropoff/pickup setting is used. Status Shipped.
• Delivered — usually reported by the platform. If you shipped with your own carrier, the order becomes Delivered automatically once proof of delivery (POD) is taken in Shipping; if needed, mark it by hand with the Delivered button on the card.
• Cancel — cancels the order on the platform; it cannot be undone and asks for confirmation. If the HNR order is open, "Cancelled on platform, HNR order open" goes into the error queue: close it with Delete HNR order on the card (this uses your own HNR order delete permission).

At the bottom of the order card there are Returns and Change history sections: every status change is recorded with who made it (or "system") and its source (manual, platform, shipment POD).

7. Sending stock and prices

The stock sent is calculated as follows (the same rule as ATP):
free = on hand − unusable (quarantine / subcontract / inactive warehouse) − remaining open sales orders (reserved)
sent = at least 0, round down(free × stock share / 100) − buffer
Example: on hand 120, 10 in quarantine, 30 in open orders → free 80; share 50% → 40; buffer 5 → 35 is sent to the platform.

The moment a marketplace order is written to HNR it becomes an open sales order and is deducted as reserved; it has already been deducted on the platform too — it is not counted twice. Several platforms each take their share from the same free stock; the shares may add up to more than 100 (a deliberate choice by the manager: every platform sees the same goods and whoever sells first gets them).

The price is found in this order: the Fixed price in the mapping (sent as is) → a price list attached to the mapping → the price engine (account = platform account, channel Marketplace (e-commerce), without campaigns — platform campaigns are managed on the platform) → price 1 of the stock card. Engine and card prices exclude VAT; if Platform prices include VAT is on, net × (1 + VAT/100) is sent. The Price source column in the table shows which one was used.

The Stock and price tab shows, for each mapping, the On hand, Reserved, Free, Share / buffer, HNR stock, Platform stock, HNR price, Platform price and Price source columns; rows that differ are highlighted. The platform value is normally the last sent one; if Query the current value on the platform is ticked, it is read from the platform (today Trendyol and Simulation support this; for the others the last sent value is shown). Send changes sends only what differs from the last sent value; Resend all forces everything. The result is summarised as "… products sent, … skipped as unchanged, … failed."; the reason for a failed row appears on the mapping and in the error queue.

8. Returns

Platform returns are downloaded together with orders (looking back at least 14 days); the same return number is processed once. When a return arrives, the order becomes Return, the returned quantity appears on the lines and the returned amount on the order, and the platform return number, reason and amount are written to the Returns section of the card.

In HNR a sales return invoice is not written automatically. If the order was invoiced, "Return invoice pending" appears in the error queue — issue the return invoice from document entry as usual. If it was not invoiced, "Returned on platform, HNR order open" appears — close the open order with Delete HNR order on the card. The returned amount is deducted from the settlement.

9. Settlement

The Settlement tab shows one row per connection for the selected period (this month by default); cancelled orders are excluded:
expected settlement = gross sales − commission − shipping deduction − service fee − returns
Gross sales is the VAT-inclusive amount the customer paid. Commission comes from the line commission rate on Trendyol, the platform's payment (escrow) details on Shopee, the connection's Tahmini komisyon oranı (estimated commission rate) on Tokopedia and the configured rate in Simulation; it is shown per line and per order on the order card.

Only users with the marketplace management permission see the Settlement tab; others see "Settlements require the marketplace management permission."

10. Log and errors

At the top of the Log and errors tab is the error queue: orders carrying an error code, mappings whose upload failed and connections in error ("… consecutive errors"). Below it, per connection, the Last order download, Last stock upload and whether automatic sync is on or off; at the bottom the log table (Time, Connection, Transaction, Status, Received, New, Updated, Sent, Duplicate, Message). If the queue is empty it says "The error queue is empty."

Rewrite to HNR appears only on orders without an HNR counterpart and also writes an order that was shipped before the integration; a cancelled order is not written to HNR. Connection-level errors are shown by class: Credentials rejected, Service or permission not enabled for this account, Connection settings incomplete (for these three automatic retries stop and the system administrator must fix the cause), Network error or timeout, The marketplace service is temporarily not responding, The marketplace returned unexpected data (for these the automatic retry interval doubles after each error, up to 6 hours).

11. Automatic sync

Automatic sync is off by default (HNR does not contact a platform on its own). To turn it on, the system administrator writes PAZARYERI_GOREV=1 into the server's .env file and restarts the Node service. While it is off, the window says "Automatic sync off (server setting PAZARYERI_GOREV). Sync is done manually." and everything runs through Sync now.

• The task checks every minute; each connection downloads orders and returns at its own Order download interval and sends stock and prices at its Stock upload interval. Only connections with Automatic sync ticked and saved credentials take part.
• The server's main company (HNR_FIRMA) is scanned by the scheduler; for this, a service user with write permission (HNR_B2B_KULLANICI) must be defined in .env. Other companies are synced in the background with that user's own session when a user with write permission opens the Marketplace window or Nabız. The participating companies can be limited with PAZARYERI_FIRMALAR (or else HNR_FIRMALAR).
• When the task receives new orders, the administrator who set up the connection gets the message "…: … new marketplace orders received."; if the connection fails three times in a row, the warning "The … marketplace connection is reporting an error: …" is sent once.

Sync now (at the top of the window, with the connection selector) runs order, return and stock/price sync immediately on the selected connections whether or not the task is on, and says "Sync finished: … new orders, stock and price sent for … products." The same connection is never synced twice at the same time ("This connection is syncing right now. Try again in a moment.").

12. On the phone (Garden + Step)

On screens smaller than 7 inches the Marketplace window is simplified for warehouse staff: at the top the To pack, To ship and Failed tabs with their counts, the "Search order no. or customer" box and the Fetch new orders button; below, order cards with large touch areas (customer, city/district, amount, ship-by).

1. Order — lines, end customer and delivery details.
2. Pack — the packed report with a single tap.
3. Ship — type the tracking number or leave it empty (it is taken from the shipment or the platform) and ship.

The system administrator can also set up a connection from the phone: the form in Settings has three steps on the phone (Marketplace · Credentials and settings · Test). See the Mobile guide for details.

13. Permissions

In Settings › Users the Marketplace group has two permissions: Marketplace orders: sync, pack, ship, cancel, send stock and prices (pazaryeri for short) and Product mapping, settlements and the full end-customer identity (pazaryeri_yonet; it includes the first). The rule is enforced on the server.

A read-only user cannot change marketplace records; if HNR's write gate is closed, no write operation is performed. Connections, mappings, identity views and every manual action are written to the server's audit trail (who, when, what).

14. Nabız and the Owner Dashboard

On the Nabız home screen on the phone, one of two lines appears in the Up next list: "… new marketplace orders are waiting to be packed." or "There are … records in the marketplace error queue."; tapping the line opens the Marketplace window on the relevant tab. The revenue box of the Owner Dashboard shows the footnote "Marketplace: … revenue (incl. VAT) from … orders, platform commission and deductions …."; clicking it opens the Settlement tab.

15. Not in this version

Creating new products on the platform (listing, images, descriptions — today only the stock and price of existing products are sent), issuing the sales return invoice automatically from a return, passing the end-customer identity into the e-Archive invoice automatically (the data is ready and the hook is in place), choosing a price list on the mapping screen, managing platform campaigns and coupons and importing the platform's invoice automatically are planned as separate work.

Related guides: Shipping and Logistics · Prices and Campaigns · Live bank connection · Settings · Mobile · All modules.