Nod Emag

     EMAG MARKETPLACE

WordPress plugin for woocommerce

Contents hide

Revisions

  1. 2020-05-05
  2. 2020-05-08
  3. 2020-05-14
  4. 2020-05-18
  5. 2020-05-29
  6. 2020-06-01
  7. 2020-07-27
  8. 2020-08-06
  9. 2020-08-28
  10. 2020-09-09
  11. 2020-11-02
  12. 2020-11-10
  13. 2020-12-30
  14. 2021-02-03
  15. 30.03.2021
  16. 09.11.2021
  17. 22.02.2022
  18. 11.03.2022
  19. 15.06.2022

Use case

This module allows NOD partners to sync their ecommerce websites with emag marketplace in terms of products and orders. It is based on the Emag Woocommerce module developed by Zitec.

Integration Pre-requisites

  1. Make sure that your hosting provider allows your machine to receive traffic from emags’ IP 91.206.36.241
  2. Also, you need to add your host machine’s ip address inside emag marketplaces’ whitelist IP list (https://marketplace.emag.ro/my_account#technical-details)
  1. Add callback urls to your machine in the technical details page for the awbs, new orders products.

AWB => https://yoursite.tld/index.php?type=emkp_new_awb&awb=

NEW ORDER =>  https://yoursite.tld/index.php?type=emkp_new_order&order_id=

CANCELLED ORDER => https://yoursite.tld/index.php?type=emkp_new_order&order_cancelled=

Plugin Dependencies

Required plugins

  • WooCommerce (min v5.0.0) – required for your online shop

Optional plugins

  • Smartbill (min v.1.8.0) – used for generating invoices and NIRs. The eMag marketplace option should also be enabled in your smartbill cloud provider. 

Note that 2 factor authentication is not supported with the plugin, so you need to disable that from you cloud account if you have it enabled !

  • Nod wordpress module (min 1.2.0) for sending orders to NOD and importing NOD products.
    Important note: The customer should have the DropShipping option enabled in order to be able to send orders to NOD. Please send an email to ecommerce@nod.ro requesting eMag API access so you can place orders with eMag AWB.


Core functionalities

Product import

Imports products from emag marketplace and stores them internally for processing

Product match

Matches products imported from emag described in previous steps and tries to match them with products from your woocommerce shop. The match is done by comparing woocommerce SKU with the Emag Part Number (PN). If a relationship can not be linked, you can also manually match products imported from emag via bulk csv upload via the plugins Sync Products page or from individually ,from the products page.

Product Unmatch

The unmatched product reverses the process of matching an emag product with a woocomerce product so that I can try the match on another product again, so that if you initially make a mistake in the match, you may correct it.

You can manually unmatch products  individually from the products page.

Note * When you want to un-mached a product, after pressing the “un-mach” button there is no need to update it, leave the product page, because if you click the “Update” button, the product returns to it’s original settings.

Product sync

The process in which matched woocommerce products (see above) are kept in sync with emag automatically (for price and stock). This depends on the settings you configure the plugin with.

It has two modes:

Order import

Register new orders from emag in your woocommerce website. It only works for emag orders that contain products that you also have in your woocommerce shop.

Important: Use this URL to force the order import process:

[SHOP URL]/index.php?type=emkp_new_order&order_id=[EMAG_ORDER_ID]

If you want to manually import commands from Emag before the cron. Go to the “EMag Marketplace ->” Orders Queue module and click the “Importa comenzile di EMag” button

Orders sync

For imported orders (see above) we also keep them in status sync (update status according to emag status) and also register awbs.

AWBs for emag orders can also be created from the order details page, using the sender details from the Shipping Settings page (see the Plugin Config > Shipping section.)

Order invoice and NIR generation

We automatically generate invoices and in some cases NIRs.

We generate invoices for all orders in your shop, and NIRs for all orders that have a nod order id.

Automatic generation depends on how you configured the plugin. Manual nir / invoice generation can also be done individually from orders page.

Invoices for emag orders can also be sent automatically in emag.

Plugin config

General settings page

API

You will need to use your  eMAG login credentials to use the plugin.

  1. API URL: Select which version of the emag api you want to use (api-3 recommended !)
  1. Username: your emag marketplace username
  1. Password: your emag marketplace password
  1. Locale: the locale you use for your marketplace (currently only one is supported)
  1. Currency: The currency you sell in.

Smartbill

Make sure you know how to use the smartbill and the smartbill plugin beforehand. Read the official documentation here.

For this Tab to be enabled you need to have the smartbill plugin installed, activated and authenticated. (see the dedicated Smartbill Section on how to do that)

Please note that every module activation in Smartbill requires you to re-login in order to benefit from the new modules. To perform a new login, simply remove your password, hit save, then enter your password and save again.



For more informations on the settings, please acces this link: Setari Smartbill-Nod Emag

Products


All the options regarding products management in relation to emag will be handled in this tab:

  1. Handling Time:  0 is the default value, change only if you have another deal with emag. => This validation is ignored.
  1. VAT rate: the VAT rate specific to the rules and regulations of your country
  1. Min sale price (percentage): the minimum sale price percentage of products that you want to sync with emag marketplace
  1. Max sale price (percentage): the maximum sale price percentage of products that you want to keep in sync with emag marketplace
  2. General Emag Product Commission (percentage): This percentage will be added to the price of the product (price * (1 + percentage)) when sending price to emag (if the price sync is enabled).

MISC: Note that if you set your woocommerce store to include price tax for products, the final price sent to emag will deduct the VAT rate you set at point 3 from the overall product price, because VAT will be added in emag as well.

  1. Delete Product Action Action to be taken with emag products removed from woocommerce.
    This is only available for products that have been matched and are in stock sync with emag. Options:
  1. Import and Match Cron If this is enabled, it will periodically try to match (and sync, if the auto-sync option is set to yes) your products from eMag marketplace with products existing in your woocommerce shop.

disable – this will make no changes to the emag products.

enable – this could make changes to the emag products, depending on the following settings.

  1. Auto sync If this is set to yes, it will put all matched products automatically in sync with eMag
  1. Price sync default  If this is enabled, it will set the price sync on for newly matched products automatically. This only works if the auto sync is also enabled. options:
  1. Stock sync default  If this is enabled, it will set stock sync for newly matched products automatically. This only works if the auto sync is also enabled.
  1. eMag sync preferences for products that run out of stock Will update emag products according to the selected options, for matched products that run out of stock and have the stock sync option enabled and visibility to marketplace active.
  1. eMag products become unavailable Using this option you can handle what happens with matched woocommerce products that become unavailable in emag. Options:

Orders

  1. Initial order status the status of the order when it arrives in ecommerce website
  1. Finalized order status the status of the orders in ecommerce after they are completed in emag marketplace
  1. Cancelled order status the status of the cancelled orders in ecommerce after they are being cancelled in emag marketplace
  1. Generate invoices automatically If enabled, invoices will be automatically generated for orders with completed status. This uses the smartbill plugin. For emag invoices it will try to use the series you defined in the Smartbill section of this plugin, if not it will default to the one used in the Smartbill Plugin. This option is only available if you have smartbill installed and enabled.
  1. Auto send invoice to eMag If enabled, invoices for emag orders will also be sent automatically to eMag. Be careful with this option if you’re also using smartbill, because smartbill also sends invoices to emag automatically. It’s better to disable auto sending from smartbill and use this plugin instead to auto send.

Payments

This section allows you to map the payment options coming from emag to payment options in woocommerce.

It has Three options:

  1. Cash On Delivery the final user will pay with cash on delivery
  2. Bank Transfer the user will use an bank transfer for the payment
  3. Online Card Payment the user will use an online payment method

Note that woocommerce comes by default only with the cash on delivery option. You will need to install and enable other plugins for the bank transfer and online card payments to be available.

Sending orders to NOD depending on the payment method

If an Order from emag is with Cash on delivery, then we send the order to NOD with cash on delivery option (plata ramburs) so that it will appear on the AWB.

If an Order from emag is with Online payment or Bank transfer then no cash on delivery parameter will be sent to NOD and it won’t appear on AWB

Shipping

The information stored in the shipping page is used when generating AWBs for emag orders saved in woocommerce, from the order details page.

Crons:

In this panel you can set on disabled/enabled the emag related crons, just like in the Nod connector panel:

Alerts and Logging

The alerts and logging system provides a way to inspect the health of the plugin by monitoring information regarding Api integration and overall plug-in functionality. 

  1. API Error Email: Will send alerts only in regards to communication with the emag API
  1. Generic Alerts: Will send all other alerts (regarding the crons, invoice generation, orders import,products sync etc.)
  1. Debug level: Will enable debugging in site (available in the Logs section)
  2. “Ciclicitate trimitere alerte” How often will emails be sent with errors from Emag
  3. Keep logs for: For how long logs will be saved on disk, (0 for forever).

Sync products page

On the sync products page you can perform multiple tasks:

  1. Import and match emag products
  2. Import and match & sync emag products
  3. Export a list of unmatch emag products
  4. Bulk match emag products

Also, this page shows info of last products import, last match and last sync.

Import and Match emag products

Running this option will import all of the emag products from your marketplace account then try to match them with your existing woocommerce products using the relationship between emag part number and woocommerce sku.

After the process finishes, you will receive a message stating how many products have been processed and how many were matched.

You can also go to the products page and use the emag status filter with “ready for sync” option, to see how many emag products have been matched and can be put in sync.

Import and Match & Sync products

This option will do the same thing as the previous process, but will also enable the product for syncing with emag, meaning that every time stock or price changes in woo, it will be sent in emag. 

This also depends on how you configured the Price and Stock Sync default options in the settings tab, because it will use the values you set there. Meaning if you have price and stock sync options on disabled, stock and price won’t be sent to emag ! 

In other words, if the price and stock defaults are enabled, the matched emag products will be kept in sync with the ones in woocommerce for price and/or stock.

After the process finishes, you will get a feedback message.

Download unmatched products list

Before confirming if there are any un-matched products, you need to run one of the above processes first.

After the process completes, some of the emag products might not be matched with products from your shop. This can happen:

– When you don’t have all of the emag products listed in your woo shop

– When you have both the emag and the woo product, but your woo products have a different SKU than what the emag Part Numbers.

In that case, you will receive a message that contains the details about the total number of products from emag marketplace and the total number of products from your shop that have been processed, as well as another text field explaining how many products couldn’t be matched.

2. Clicking the button labelled “Exporta lista de produse necorelate” will download a csv file containing details about all the products from Emag Marketplace that have couldn’t be automatically matched with woocommerce products, because the SKUs and emag part numbers don’t match.

Bulk Matching products

Based on the same file you just downloaded on the previous step, you can also perform the bulk manual match process. You just have to insert the woocommerce product SKUs that match and save the file.

With the new file, add it in the bulk manual match section then hit the upload button.

After the process finishes, you will get a message with feedback regarding how the match went.

Products

Products Listing

On the products listing page there is a new filter option that will filter products depending on emag status.

There are 3 options for filtering products by their status in regards to the relationship with emag:

In the case of not matched products, please see the Product Manual Match page option described below.

Product Page – Emag marketplace tab

Inside each product page, you will find a new tab called Emag Marketplace

  1. Sync with Marketplace: Enable sync with eMag for this product. This enables price and/or stock sending. You will be able to check this only if the product has been previously matched.

Important: If the product is not matched, the sync options will be disabled and you will be presented with a manual match button (explained later).

  1. Sync price in emag: Check this box if you want to send the product price to eMag automatically. Only available if the sync with the marketplace is also checked.
  1. Sync stock in emag: Check this box if you want to send the product stock to eMag automatically. Only available if the sync with the marketplace is also checked.
  1. Emag Part Number Key, Brand, Warranty, EAN: imported automatically from emag when the match is made, or you can fill them manually.
  1. Emag Product Commission %: if the price sync is enabled, then the value that will be automatically sent to emag will be woocommerce regular price + this commission. 
  1. Custom price in emag: Check this checkbox if you want to send a custom price for this product.
  2. Emag custom price: This will overwrite the products’ regular price and allow the user to send a fixed value for that product. The price field has a min-max validation rule, and must fall between the Min sale and Max sale price range. Also, the value you set here will not take into account the product commision rule, but only the VAT rule (if enabled from woocommerce, it will deduct the VAT you set from the sum entered).
  3.  Price calculation formula in emag is: Pemag=Pnod*(1+Cnod)/(1-Cemag), where:

This percentage is use only if a specific product commision is not set (defined later down on the product page)

Product Page – The manual match process

If a product could not be matched by manually running the match from the sync page, or automatically by running the cron, you also have the option to individually manually match products (if you know for sure that this product exists in emag).

When clicking the manual match button, you are presented with a popup with an input that requires you to enter the emag product id (only numeric values are valid here).

You can get the product emag ID from your emag marketplace account. Enter the dashboard, go to My Products, and get the ID for the product from the “ID produs” column (as highlighted in the screenshot below).

After entering the product id and clicking the match button, if a match is found you will be presented with some information of the found product.

Hitting the confirm button will match the product and reload the page.

Orders

Order canceled

A canceled order that already has a NOD ID in the store will have the status “Canceled”.
!important:  Canceled orders in Woocommerce won’t cancel NOD orders.

In order to truly cancel the order you must contact the NOD team.

New orders from emag will automatically be created in your store, if all of the products from the emag order are available in your store (even if they are not matched).

Processes:

Orders page 

On the orders listing page, will see a new filter called “Emag Orders”.

Selecting that filter and clicking the Filter button will display only the orders your shop received from eMag automatically.

If you have the smartbill plugin installed and activated, you will also see two new columns, one for invoices and one for NIRs. 

Order Page

On the main order page you can see two new information fields, one for the emag order id and the other for the emag order status.

The emag order status info field shows the current emag status.

The status mapping between emag and woocommerce is based on the options you selected from the general settings > orders tab.

Invoice Generation

Inside the order page, you have on the right side a box labelled Invoice.

The “generate invoice” button only appears if you have the smartbill plugin installed and active.

Clicking on the generate invoice button, a smartbill invoice will be manually generated for you.

If this is an emag invoice and you also have the additional smartbill options configured, it will try and look for the corresponding emag order inside smartbill and generate an invoice there. 

If not, it will generate a regular invoice.

Invoices are downloaded locally and you can view them by clicking the link in the invoice box.

Or from the orders list page in the invoice column.

Auto Generation

If you use the auto-generation invoice feature (from the plugin order settings page) for orders with status completed invoices will be generated automatically via the invoice generation cron.

eMAG locker invoices


Because of the new implementation, from 03 may 2022, of eMAG marketplace – they take care of the transport fee in the case of locker orders, we made an implementation for the invoices made with Smartbill API and we have eliminated the transport fee from the invoices, only for the locker delivery method.

In this case, the invoice will contain only the products and their prices, like in the following example:

NIR Generation

Underneath the Invoice box, there is another one called NIR (Nota intrare receptie).

You can only generate NIRs for orders that have been sent to nod successfully, and that have been invoiced in NOD and only if you have the smartbill plugin enabled.

Clicking the Generate NIR button a new NIR type document will be generated inside smartbill, as well as the products for the respective order will be correctly handled in the administration (gestiune).

Once a NIR is generated, the link to it will be placed in the box.

And also in the nir column on the orders listing page.

Auto Generation

If you use the auto generation feature (enabled from the orders setting page), NIRs will be automatically generated for NOD orders with status completed and that have awb in emag.

Coupons

Starting with nod-emag 1.8.2 we added the logic of handling emag orders with vouchers. We use the woocommerce coupons functionality for showing emag vouchers in woocommerce and to send them to nod.

Please check some examples here based on these smartbill settings.

Smartbill setup

Generating invoices

Invoice series

Before being able to generate any type of invoice with smartbill, you need to create your first invoice series.

Go to you smartbill account -> configuration -> series (https://cloud.smartbill.ro/core/configurare/serii/).

From here, select “Factura” in the dropdown, add a name for your series, let the first number as 0001, and optionally add a description. After that click on “Adauga serie”. 

Your new invoice series should now appear in the list below, as pictured above.

eMag orders

In order to generate invoice for emag orders you first need to buy and enable the smartbill service supporting emag. 

Go to your smartbill account -> my account -> integrations (https://cloud.smartbill.ro/core/integrari/) and the first tab will be emag.

After you make a request for the plugin, once smartbill approves it it should be available for configuration from the same page.

You will need to configure it by first adding your email and password for your emag marketplace account.

Once your credentials are validated, you are asked to add some basic config.

You can use the same invoice series you generated at the previous step or generate a new one just for your emag invoices.

You can also choose to impact your products stock, if you have the stock module enabled in smartbill. This will decrease the stock of products / services whenever you generate a new invoice.

Once you have the module enabled and ready, you can import emag order from this page https://cloud.smartbill.ro/raport/comenzi_emag/ starting with the date selected above (Preia comenzile incepand cu)


If you configured the smartbill section of the emag plugin, the plugin will try to fetch the orders automatically for you, and based on them will try to generate invoices if you also have them in your shop.

Manully upload of the invoice

Manual upload of the invoice on eMAG orders:
Customers who want to upload the invoice manually on an eMAG order, can do so from the order page, eMAG Invoice section where they can manually upload the invoice and download it later.

Enabling SKU on products

It is important that you enable the product codes option to be available on products.

You can do that from here https://cloud.smartbill.ro/documente/preferinte-generale/

WordPress plugin configuration

Once you configure your smartbill account, head over to your wordpress installation, where you will need to configure the smartbill WP plugin as well (https://yoursite.com/wp-admin/admin.php?page=smartbill-woocommerce)

Add your email address, your API token and your CIF number in order to authenticate to smartbill.

Once validated, you’ll get access to another config screen (https//yoursite.com/wp-admin/admin.php?page=smartbill-woocommerce-settings)

Your smartbill integration plugin will behave the way you configure it in that page, so pay attention to each option.

An optimal config example might look like this:

Depending on your setup, you might want to use other option values than the ones presented above.

You also have to configure the smartbill section in the emag marketplace plugin. See the General settings page | Smartbill section for reference

Non emag orders

For orders without an emag order id will be generated invoices will be generated as regular invoices, and you will find them here https://cloud.smartbill.ro/raport/facturi/

Generating NIRs

In order to generate NIRs you must first have to:

  1. Define a NIR series, from here https://cloud.smartbill.ro/core/configurare/serii/
  1. Define NOD warehouse https://cloud.smartbill.ro/nomenclator/gestiuni/
  2. Define NOD supplier https://cloud.smartbill.ro/nomenclator/furnizori/

You also need to configure the smartbill section of the emag marketplace plugin with the desired options. See the General settings page | Smartbill section for reference.

Once you’ve finished setup, you can then proceed to create NIRs. You will then find the NIRs here https://cloud.smartbill.ro/gestiune/raport/note-intrare-receptie/

Crons

Product related crons

emkp_import_products

Cron that runs twice a day, but only if the auto match sync option is enabled.

This cron imports all the available (status active and documentation approved) emag marketplace you have listed in your account, and inserts them inside a dedicated db table (_emkp_sync_products_queue) for match and sync purposes.

If the products already exist in the table, the script will only update relevant columns for the products: part_number and product_data (name, price, brand, stock, part_number, warranty, status and ean) values.

emkp_sync_products

Cron that runs hourly, also only if the auto match sync option is enabled.

This cron tries to match all of the products in your woocommerce shop with the products imported from emag and saved in the emkp_sync_products_queue table. It does so by matching the SKU from woocommerce with the PN from emag.

 If it does not find a match, it will try to match the products in the following order, as a fallback:

emkp_process_products

Cron that runs every 10 minutes and which sends data to emag (stock, price, status) for products in woocommerce that have been updated and that now need to be synced in emag. These products can be found in the emkp_products_queue table with status pending (or failed, in which case only 5 attempts are made for that particular update requirement. Retries are reset every time a new woo update occurs for that product, or when the product is sent successfully).

This cron uses a cron locking system, more details here: Cron locking system

emkp_products_cleanup

Cron that runs daily and cleans up the emkp_sync_products_queue table (table which keeps the imported products from emag) of products that are not in your emag marketplace anymore or have become unavailable (status 0 or documentation invalid).

Also, depending on the value set for the “eMag products become unavailable” option, for woo products matched with the emag products that are no longer available, the cron will also either delete the emag meta data (unmatch), or just put the product out of sync.

emkp_products_stock_sync_check

Cron that runs hourly and looks for differences in stock and price between woo and emag products (that have been matched) found in the emkp_sync_products_queue table. For every product found that has a difference in stock and / or price, it will add / update the emkp_products_queue table with that product, so that when the emkp_process_products (see above) cron runs it will sync the products with differences in emag.

Order related crons

emkp_import_new_orders

Cron that runs every 5 minutes, checks for new orders frequently, and tries to create woo orders based on new eMAG orders, on your site quickly, reducing the risk of losing stock on the order products. 

The cron iterates over all the orders that has eMAG status 1 (new). When an order cannot be created in your shop, a warning email containing the respective error will be sent to you, so that you deal with it with priority.

The number of attempts to send the order is limited to 25. If the reason why the order was not imported changes, press the “Reseteaza” (“Reset”) button in order to retry to import the order.

New emag orders are automatically saved in the emkp_orders_queue table by a direct call to your website triggered by emag every time a new order is registered on your marketplace account. 

Important: the url for the callback is:

[SHOP URL]/index.php?type=emkp_new_order&order_id=[EMAG_ORDER_ID]
Use this to FORCE the order import process.

This cron uses a cron locking system, more details here: Cron locking system

emkp_sync_orders

Cron that runs hourly and updates emag status of woocommerce orders created from emag (see above cron).

emkp_sync_awbs

Cron that runs every 10 minutes and tries to match and assign emag AWBs registered in the emkp_awbs_queue table with orders from your woocommerce shop. Emag AWBs are added to the queue table in a similar fashion like emag Orders, via a callback triggered by emag every time a new awb is generated (the callback url is index.php?type=emkp_new_awb&awb=).

Based on the info of the awb id we can ask emag which order it belongs to, and the based on the order id we can find the corresponding woocommerce id, in which case we just attach the awb to that order.

emkp_send_orders_emag

Cron that runs every 10 minutes only if the Auto Send Invoice option is enabled. For every emag order that has an invoice in woocommerce, it will send the invoices to emag marketplace for those specific orders.

emkp_nod_update_orders*

Cron that runs every 10 minutes only if the nod connector plugin is enabled. It updates the status and AWBs of NON-EMAG orders only, based on their nod-webshop counterpart.

emkp_delete_duplicate_orders

Cron that runs every 10 minutes and deletes all duplicate orders with the same emag id, leaving only one. In case one of the duplicate emag orders has a nod id, it will leave that one instead. Registering more orders with the same emag id, even though it is possible it is highly unlikely to happen. In case it does happen however, this cron will handle it.

Smartbill related crons

emkp_fetch_emag_orders

Cron that runs every 10 minutes, only if the smartbill plugin is active. It’s job is to refresh the emag orders list in the corresponding smartbill marketplace module, so that the emkp_generate_invoice (described below) can create emag invoices. It only works if you have the emag marketplace module enabled and configured inside your cloud smartbill account.

emkp_generate_nir

Cron that runs every 10 minutes,  only if the smartbill plugin is active and the emag smartbill extension is configured. This cron will iterate over all your completed woocommerce orders that have been successfully sent to nod (have a nod id) and also  have an eMag awb ii, and will try to generate an NIR invoice type in smartbill.

emkp_generate_invoice

Cron that runs every 10 minutes, only if the smartbill plugin is active and the Auto Generate Invoices option is enabled. This cron will iterate over all your completed woocommerce orders that have an emag order and as well as an emag awb. For each of these orders it will try to generate invoices.

If you don’t have the marketplace module enabled in smartbill, or if you have not configured the smartbil extension in the emag plugin, or if we are simply unable to create invoices directly for the emag orders due to various issues, the cron will fallback to generating regular type invoices.

Locking system

This cron uses a cron locking system, more details here: Cron lockyng system

Misc

emkp_delete_invoices

Cron which runs once a day and deletes invoices uploaded on emag orders from the emkp_orders_invoices table (but not from disk !) only for those invoices older than 1 month.

emkp_cron_checker

Cron which runs every 10 minutes and unlocks all emag crons that have run but timed out or stopped working before finishing thus failing to get unlocked.

emkp_delete_logs

Runs once a day to delete log files older than 15 days or whatever setting you have added in the Alert & Logging settings page for logs retention.

Diagrams

Schematics of various user flows can be found on whimsical accessing this link.

Schematics of table diagrams and cron use cases also in whimsical here

Logs

The plugin has a logging system integrated in all crons and within the rest of the system. To access the logs you first have to enable logging.

Put the debug level option to a different value than Off.

After that, you will begin to see logs appear in the logs tab of the plugin.

Select a file from the list on the left side to inspect logs.

Change history:

We have implemented a log that records the changes made recently in the settings of the Emag Marketplace module here:

The logs can be found in Emag Marketplace->Logs->settings->change_history: