Hepsiburada Marketplace Connector for OpenCart

Overview

Hepsiburada Marketplace Connector sells your OpenCart catalogue on Hepsiburada. You map your categories and attributes once, set your price rules and stock buffer, and the extension sends your products to Hepsiburada, keeps stock and price in sync, imports every Hepsiburada order as a real OpenCart order, and reports packing, the invoice link and the tracking number back to Hepsiburada.

What it does

• Connection. API user, API password, merchant ID and integrator name of your own Hepsiburada merchant account. Test and live credentials side by side, stored encrypted, shown only as a hint afterwards. Requests use HTTP Basic authentication and send your integrator name as the User-Agent, as the Hepsiburada documentation asks.
• Category and attribute mapping. Search the Hepsiburada category tree, map it to your store categories, and map every required Hepsiburada attribute (colour, size, material, warranty ...) to a product attribute, the manufacturer, the model, the SKU or a fixed value.
• Product import. Products are uploaded to the Hepsiburada catalogue import; the extension reads the import result later and shows per product whether it is not listed, waiting for Hepsiburada or live, with the exact message Hepsiburada returned when it rejects one.
• Price rules and stock buffer. Markup in percent and a fixed amount, price endings (x.99, x.90, whole numbers), exchange rate from your OpenCart currencies or your own, units kept back, zero limit and maximum. Stock and price are sent as inventory uploads; nothing is re-sent when nothing changed.
• Orders. Every Hepsiburada order becomes an OpenCart order with buyer, invoice and delivery address, lines at the price Hepsiburada sold them, totals, the status you choose and the stock taken like a normal order. Later Hepsiburada statuses (shipped, delivered, cancelled) move the order along. Orders whose product is not mapped are listed as failed imports with the reason and retried.
• Packing, invoice and tracking. Set an order to Shipped and write the tracking number in the order history ("Tracking: ABC123456"): the extension packs the lines at Hepsiburada, sends a signed link to a simple HTML invoice of the order and, for your own carrier, reports the tracking number and link.
• Cannot supply and returns. Cancel a line at Hepsiburada from the Orders page; return (claim) requests are imported, noted on the order and can be approved from the admin.
• Job queue and log. Retries with growing waits, a Jobs page with a "Run now" button, a filtered log with CSV export. Secrets never reach the log.
• Events and cron only, no OCMOD, no core edits. OpenCart 4, tested on 4.1.0.4.

Limits to know

• You need your own Hepsiburada merchant account with API access. Hepsiburada may only answer requests from server IP addresses you registered with them.
• Hepsiburada is polled by cron: there is no webhook, so new orders arrive at the next sync (every few minutes with a host cron, hourly with the OpenCart cron alone).
• One Hepsiburada merchant SKU per OpenCart product. Option-based variants are not listed as separate Hepsiburada variants in version 1.0.
• Order prices are the final prices Hepsiburada sold at; no OpenCart tax is added and no OpenCart shipping method is used.
• Imported orders are written directly and do not fire the order e-mails or the events of other extensions.
• Tested against a stand-in of the Hepsiburada API built from the public documentation, not against a live merchant account. Not affiliated with Hepsiburada.

Installation

Requires OpenCart 4.1 (tested on 4.1.0.4), PHP 7.4 or newer with the cURL and OpenSSL extensions.

1. In the admin go to Extensions > Installer, upload kv_hepsiburada.ocmod.zip and click Install.
2. Extensions > Extensions, choose "Modules", find "Hepsiburada Marketplace Connector" and click Install (the green button).
3. Click Edit. Switch the connector on and, if you have one, enter your Kavio Labs license key. Without a key the extension works for 14 days.
4. The Hepsiburada pages are under Sales > Hepsiburada: Listings, Connection, Categories, Attributes, Rules, Orders, Returns, Log, Jobs.
5. Cron. The install registers an hourly entry in the OpenCart cron, which needs the standard OpenCart cron line on your server (shown on the settings page). For a faster sync call the secret web address from the settings page every few minutes with your host cron.

Uninstall removes the mappings, rules, queue, log and the stored credentials. The OpenCart orders that were imported stay.

What you need from Hepsiburada

• A merchant account with API access: the API user name and password, and your merchant ID (a GUID).
• An integrator name for the User-Agent header. Use the name Hepsiburada gave you when you registered the integration; letters and digits, up to 30 characters.
• If Hepsiburada requires it, the outgoing IP address of your server allow-listed (test and live separately). Start in test mode and switch to live only after a successful test.

Configuration

Settings (Extensions > Modules > Hepsiburada Marketplace Connector > Edit)

• Enable the connector. When off, no new work starts. Jobs that are already under way are still processed.
• Status of imported orders. The order status given to a new Hepsiburada order (Processing by default, which takes the stock). The status mapping on the Rules page can override it.
• Sync interval. How often stock and price are pushed, orders imported and shipments reported.
• Log retention and Debug log (stores each HTTP call with masked secrets; switch off when done).

Connection

Choose test or live, enter the API user, the API password, the merchant ID and the integrator name. The password is stored encrypted and never shown again; leave the field empty to keep the stored value. "Save and test" calls Hepsiburada and shows the result.

Categories and attributes

On Categories search the Hepsiburada tree by name and map a leaf category to a store category. The deepest mapped category of a product decides where it is listed. Markup and fixed amount can be set per mapping. On Attributes pick the mapped category and map each Hepsiburada attribute to a product attribute, the manufacturer, the model, the SKU or a fixed value; values are matched with the allowed Hepsiburada values by name. Required attributes are marked; a product with a missing one is not sent and shows which one is missing.

Rules

Prices (markup, fixed amount, endings, list price, exchange rate), stock (buffer, zero limit, maximum), new listings (automatic creation, default brand, brand source, VAT rate, default weight) and orders (guest or attach to the customer with the same e-mail, status mapping). Shipping: report the packing step, send the invoice link (with a prefix for the invoice number) and, for your own carrier, the tracking number and a tracking link template such as https://track.example/{tracking}.

Usage

1. Connect and run "Save and test". The result names your merchant.
2. Map a category, then its required attributes. The brand is the manufacturer of the product unless you choose a product attribute on Rules.
3. List products. On Listings add a product by ID with its merchant SKU (the barcode defaults to the EAN code, then the SKU, then the model) or add all products of a category. The sync uploads the products; they are "Waiting for Hepsiburada" until Hepsiburada has processed the import, then "Live". A rejected product shows the reason in the Last error column; fix the product and click Retry.
4. Stock and price follow your catalogue. A change to a mapped product, or an order that takes its stock, is pushed at the next sync.
5. Orders. New Hepsiburada orders appear under Sales > Orders with the note "Hepsiburada order ...". An order whose merchant SKU is not mapped is shown on the Orders page under "Failed imports only" with the reason and retried.
6. Ship. Set the order to Shipped and add a history comment with the tracking number, for example Tracking: 7330012345678. The order page shows the tracking number found. The next sync packs the lines at Hepsiburada, sends the invoice link and, with "own carrier" on, the tracking number.
7. Cannot supply. On Orders, "Cannot supply" cancels a line at Hepsiburada (enter the reason ID if Hepsiburada gave you one).
8. Returns are listed on the Returns page; Approve sends your answer to Hepsiburada.

Run the queue by hand on the Jobs page with "Run the queue now".

FAQ

Does it need OCMOD or core edits?

No. Events and the OpenCart cron only.

Which OpenCart versions?

OpenCart 4.1 (tested on 4.1.0.4). There is no OpenCart 3 edition.

Do I need a Hepsiburada account?

Yes, a merchant account with API access. Hepsiburada decides which products and sellers it accepts.

Why no webhook?

The connector polls Hepsiburada on every sync run. New orders therefore arrive within one sync interval.

The connection test fails with "Unauthorized". Check the API user, the password and the merchant ID, and that test and live credentials are not mixed up. If Hepsiburada answers with 403, ask them to allow-list the outgoing IP address of your server.

"Required attribute ... has no value". Open Attributes for the mapped category and give that attribute a product attribute or a fixed value, then Retry the product.

A product stays "Waiting for Hepsiburada". Hepsiburada processes imports in batches; the sync reads the result on the next run.

An order was not imported. Open Orders > Failed imports only. The usual reason is a merchant SKU that is not mapped to a product. Fix it; the import retries.

What does the invoice link do?

It is a signed address of a plain HTML invoice of the order that Hepsiburada downloads. It works only for orders imported by this extension, and your shop must be reachable from the internet over https.

Prices look wrong. Check the exchange rate: the extension uses the Turkish lira rate of your OpenCart currencies, or the rate you enter on Rules. Without either, prices are sent unchanged.

Are customers e-mailed about imported orders?

No. The order is a record in your shop; Hepsiburada is the seller of record to the buyer.

Does the licence stop the admin?

No. Without a valid licence the sync and the import of new orders stop; the admin pages stay open.