Skip to main content

Integration with Omnitron REST APIs

The steps to be followed in order to create a salable product are as follows:

The steps to be followed for the after-sales order are:

Create Product

To create a product, attribute, attribute value and attribute set must be created first.

Attribute

The detail information of the product is kept in "attributes". Attribute is used to enrich the product, to be able to filter and list the products. The most commonly used Attribute types are text, text_area and dropdown types.

  • dropdown: The selected type to create filterable or listable products. When this type is selected, the attribute value must be entered. Sample; color, size, season, brand, category, collar type, etc.)
  • text: Used for non-selectable attributes such as product description. For this type, the attribute value information comes with the product, it is not necessary to enter the attribute value.
  • text_area: This type should be selected if product descriptions are to be edited from the Omnitron interface. When text_area is selected, the enriched text editor is displayed on the Omnitron product detail page.

In order to create an attribute from Omnitron, the attribute addition page is reached with the flow Products and Catalogs -> Product Attribute -> Add New Attribute from the menu on the left. You can find the details of creating attributes with the API from this page

If Omnitron is set to support multiple languages, the entered attributes are generated for the main language. When it is desired to define attributes for other languages, the definition can be made by selecting the relevant language from the Locales field in the upper right of the Omnitron interface.

The name field for each attribute can be translated into different languages.

Attribute Value

Attribute value is where the definitions of selectable fields (of dropdown type) are made.

Create Attribute Value

To define the value for an attribute from Omnitron, go to Products and Catalogs -> Product Attribute from the left menu and select the related attribute with type dropdown from the attribute list.

The relevant values are entered by clicking the Add button from the table at the bottom of the page that opens.

After the attribute whose value will be defined with the API is queried from Omnitron, the attribute value is created together with the attribute ID. You can find the details from this page.

Get & Search Attribute's Value

To create or update the attribute value with the API, the attribute ID to which the value will be added must first be reached. You can find the details from this page.

Update Attribute Value

To update the attribute value information, go to Products and Catalogs -> Product Attribute page from the left menu and select the related attribute with type dropdown from the attribute list. Changes can be made by clicking on the value line to be updated.

In order to update the attribute value with the API, the attribute value ID to which the value will be added must be reached first. After the Attribute value ID is reached, an update request is sent to the attribute_value endpoint with the fields to be changed. You can find the details from this page.

Language Support

Omnitron's default language is the language defined when installing Omnitron. For example, the default language for the Omnitron to be created over Commerce Cloud will be English. If the website will be launced in a language other than the Omnitron default language, the translation for the language to be used on the website for the products must be entered. If translation is not entered for the products, the default language of the product will be reflected on the site. For example, when the default language of Omnitron is English, that is, if Omntiron is used in English, it is necessary to enter a German translation for all products that will be sold on the website when opening a German site. Otherwise, the products will appear in English while the website is in German.

value and attribute, meaning the attribute model together have the principle of uniqueness. Since the value value is unique in an attribute, multiple records with the same value cannot be created.

Create Attribute Set

Also, the attribute set is used to group attributes or products, set how products appear on the site, or how grouped attributes are filtered on the site.

The model in which we determine what attributes the product will have. Details for product creation can be found at this page.

After logging in to Omnitron, the screen is accessed with Products and Catalogs -> Product Attribute Sets -> Add New Attribute Set from the menu on the left.

Assign Attributes to Attribute Set

The way an attribute is used in the attribute set is determined during this process. For example, when you want to use the color attribute different in carpet, different in clothing, and different in jewelry, the attribute set is used. The usage of the feature to be assigned to the attribute set is made with the following definitions.

  • Required: In the Attribute set, this attribute must be filled in the product.
  • Searchable: In the Attribute set, this attribute is marked as searchable in products.
  • Filterable: In the attribute set, this attribute is marked as available for filters.
  • Variant: Within the attribute set, this attribute is defined as the variant of the product.
  • Variant Listing: This variant can be listed on the sales site by grouping it according to variant attribute values. For example, the color variant can be listed for the clothing attribute set, while the size variant can be listed for the carpet attribute set.
  • Visible: Used for attributes that will be used for backoffice operations in Omnitron but not on the website. Example, erp_color_code, erp_sku etc.
  • Form Required: It is used for texts such as name and note to be written on the product, such as jewelry, watches, wallets, flowers.
  • Form Field Required: If not required, the obligation to enter texts such as the name and note to be written on the product is eliminated and the product can be ordered anonymously.

Attribute sets are listed on the screen that opens with the Products and Catalogs -> Product Attribute Sets flow. The attribute set whose details are desired to be displayed can be accessed by clicking on the table. All features are listed on the left side of the screen that opens. The features to be added to the attribute set are moved to the right area (Selected Features) by clicking the + button.

Create Product

After the attribute, attribute value, attribute set definitions are made, the product will be ready to be created.

To do this from Omnitron, Products and Catalogs -> Product Pool -> Add New Product menu flow is followed to reach the relevant screen.

The newly created product will be created with Omnitron's default language.

You can find the details from this page to create a product with the API.

Update Product

When making changes on the selectable fields (attribute type = dropdown) related to the product, it is useful to check whether the attribute value is defined in the selectable field. Assuming that the "color" attribute is a dropdown, it is mandatory to have an attribute value in our attribute value table with a "value" value of "RED". There is no such requirement for text-type properties.

You can find the details from this page to update the product with the API.


Create or Update Price

This function is used to create or update the price of the product.

To define or update a price for a product, a price list must first be defined.

Create Price List

To do this from Omnitron, Products and Catalogs -> Price Lists -> Add New Price List menu flow is followed to reach the screen.

NOTE: is_auto_sync' determines whether the price list is managed from the integration or Omnitron panel.

  • True: It is possible to create and update with integration.
  • False: Price creation and update processes are managed with excel via Omnitron back-office.

You can find the details from this page to create a price list with API.

Create Product Price

The price of a product can take different values in different lists. For example, when the product is sold for X amount in the A price list defined for marketplace A; It can be sold for Y amount in B price list defined for marketplace B. For this reason, when creating or updating the price of the product, it should be specified in which price list it is.

With the steps mentioned in the Create product title, the product was created, and with the steps mentioned in the create price list title, the price list in which the product price would be defined was created.

In this way, it is now possible to define a price for the product. You can find the details from this page to define a price with API.

Note If a price is tried to be defined for the product without creating a price list or product, an error will be received.


Create or Update Stock

This function is used to create or update the stock of the product.

In order to define or update a stock for a product, a stock list must first be created.

Create Stock List

To do this from Omnitron, Products and Catalogs -> Stock Lists -> Add New Stock List menu flow is followed to reach the screen.

NOTE: is_auto_sync' determines whether the stock list is managed from the integration or the Omnitron panel.

  • True: It is possible to create and update with integration.
  • False: Stock creation and update processes are managed through the Omnitron panel. (with Excel)

You can access the details from this page to create a stock list with API.

Create Product Stock

The stock of a product can have different values in different lists. For example, when the product is X units in A stock list defined for marketplace A; It can be offered for sale from Y units in B stock list defined for marketplace B. Therefore, when creating or updating the stock of the product, it should be specified in which stock list it is.

With the steps mentioned in the Create product title, the product has been created, and with the steps mentioned in the create stock list title, the stock list in which the product stock will be defined has been created.

In this way, it is now possible to define stock for the product. You can find the details on this page to define stock with API.

Note If you try to define the number of stock for the product without creating the stock list and product first, an error will be received.


Create Image

When uploading product images to Omnitron with the API, links to the image are used, not the media file of the image. After the images of the product are saved as a link to Omnitron via API, Omnitron takes the image from the links given for the image with asynchronous tasks and formats it (size, resolution, etc.) and uploads it to the CDN. For this reason, the product images displayed on the website are not fed by the links sent via the API, but by the links that are created after they are uploaded to the CDN.

Create Downloadable Image

In order for images to be uploaded to CDN, image links sent via API must be accessible by Omnitron.

You can find the details on this page.

Create Product Image

To upload images from Omnitron;

  • Products and Catalogs -> Product Pool menu flow is followed.
  • From the product pool list, click on the product to which the image is to be added.
  • Images are uploaded from the area under the product images title.
  • When multiple images are loaded, their order can be adjusted by drag-and-drop.


Order

1. The company can pull orders from Omnitron that are not written to its own system with the is_send=false parameter. How many orders to be entered into the system at the same time can be adjusted with the limit parameter.

Retrieve a list of orders

With the request /api/i1/orders/?is_send=false&status=400&status=450&status=500&status=550&limit=5, a list of orders that have been paid but not sent to the integration system can be retrieved.

The mandatory fields that the company should keep in its own system are as follows;

  • Order number (number)
  • The ID information of the order lines must be kept. (orderitem_set-->id)

Each sold product is kept as one. For example, if 4 pieces of the same product are purchased, 4 different order lines (order_item) will be created.

2. If the order has been successfully imported into the integration, the order's dispatch status on Omnitron is updated as is_send.

Request PATCH

Path: /api/i1/orders/{order_no}/

{
"is_send": true
}

You can find the details of this API endpoint from this page.

2.1. When the order is placed, Omnitron starts to hold reservations on stock. This reservation is used to synchronize the stock between the ERP system and Omnitron. If the order has been successfully registered, a request must be sent to Omnitron to release the reservation information, with the information that the order has been successfully registered.

To perform this operation;

2.1.a. Mapping should be done for the order lines.

Request POST

Path: /api/v1/order_items/{orderitem_id}/create_mapping/

{
"update_stock": true,
"code": "<erp_orderitem_code>"
}

update_stock: Releases the reservation stock. code: Unique identifier of the order line on the ERP side.

You can find API details from this page.


3. Order Status Update

3.1. The fields used in the status update for the order lines are as follows.

  • status : Status of the order line
  • shipping_company : Information with which shipping company the order line is shipped with (must be from the enum in omnitron)
  • e_archive_url : URL to access invoice pdf in the Omnitron panel and sales channels
  • invoice_number : Invoice number for the order line
  • invoice_date : Order line billing date
  • tracking_number : shipping tracking number for the order line (it will be sent filled when the cargo tracking integration is done by the company.)

You can access the order update via API details from this page.

After the order's invoice information (invoice_number) is updated, the order status should be changed to 'in preparation' (450). By looking at this information, Omnitron will decide whether the order will be canceled or refunded in the future.

You can access the order update details via API from this page.

After the order's invoice information (invoice_number) is updated, the order status should be changed to 'in preparation' (450). By looking at this information, Omnitron decides whether the order will be canceled or refunded in the future.

If the shipping processes are controlled from outside of Omnitron (ERP), the status of the order line must be updated when the shipping information is received. Order statuses from the courier company must be updated by finding their corresponding order status in Omnitron.

You can find order statuses from this page.

Order Cancellation-Return Process

The action initiated for uninvoiced orders is cancellation, and the action initiated for invoiced orders is return.

If the brand wants to initiate cancellation/return transactions via API,

Request POST

Path: /api/i1/orders/[order_id]/cancel/

Example of data to be sent to cancel the entire order:

{
"order": 1,
"is_all": true,
"cancel_items": [],
"forced_refund_amount": null,
"reasons": {
"1": 1
}
}

Example of data to be sent for partial order cancellation:

NOT The values in the cancel_items list are the orderitem -> id information to be canceled/refunded.

{
"order": 2,
"cancel_items": [
4,
3
],
"forced_refund_amount": null,
"reasons": {
"3": 4,
"4": 1
}
}

reasons object is filled out with orderitem -> id : reason->id data. reason->ids must be filled with id values in the list of cancellation/refund reasons defined in Omnitron.

For cancellations, 'cancel' type and 'refund' type cancellation/refund reasons should be selected for refunds.

  • check reason for cancellation: /cancellation_reasons/?cancellation_type=cancel

  • check reason for return: /cancellation_reasons/?cancellation_type=refund

1. Retrieving transactions pending cancellation by cheking from Omnitron

/api/v1/cancellation_plans/?status=waiting&cancellation_type=cancel&limit=5

  • cancellation_type: Specifies the cancellation or refund type. Enum is the field. ("cancel" for cancellation, "refund" for refund)
  • status: Indicates the status of the cancellation/refund process.
  • limit: Determines how many cancellations can be made at the same time.

2. Confirmation of the transaction pending cancellation

After successfully receiving the cancellation into the integration system, it must be confirmed on the Omnitron. Once approved, the refund process begins.

Request POST

Path: /api/v1/orders/{order_id}/cancellation_approved_order/

Confirmed cancellations/refunds do not need to be interfered with by Omnitron during the refund process. Cancellation/return statuses were checked and automated with asynchronous tasks.

3. Rejection of transaction pending cancellation

If the cancellation/refund transaction is not accepted by the system for any reason, the transaction must be rejected and closed. The closed cancellation/refund process can be restarted upon request.

Request POST

Path: /api/v1/orders/{order_id}/cancellation_reject_order/

Order Detail

If the information returned from the order service is not sufficient for the order writing process, the following pages can be used to reach more detailed order information;