Get Started with some typical integrations

Overview

This guide explains typical OMS integrations. Further details on Specifications can be found here.

Order New

Topic: magento.sales.order_management.create

Header: (need to add “to” in the headers with value*)

The Create Order Commands are sent by the Sales Channel to Magento OMS when a purchase is completed. The order information will include information about order lines, payments if available and shipping method. The addresses need to be referenced from the payment node and the orderlines nodes.

See the below example for more information.

JSON example


{
    "order": {
        "id": "000000063",
        "store": "CLIENT",
        "ip": "172.17.0.2",
        "language": "es_MX",
        "vat_country": "MX",
        "origin": "FRONTEND",
        "origin_date": "2016-08-17T09:25:48+00:00",
        "customer_service_agent": "",
        "customer": {
            "id": "1",
            "type": "REGISTERED",
            "segment": "B2C"
        },
        "addresses": [{
            "reference": "104",
            "address_type": "customer",
            "first_name": "Christophe",
            "last_name": "Trichet",
            "address1": "6 Championship Dr",
            "address2": "",
            "city": "Auburn Hills",
            "state": "Michigan",
            "zip": "48326",
            "country_code":  "US",
            "phone": "123456789",
            "email": "1469095459@example.com"
        }, {
            "reference": "103",
            "address_type": "customer",
            "first_name": "Christophe",
            "last_name": "Trichet",
            "address1": "6 Championship Dr",
            "address2": "",
            "city": "Auburn Hills",
            "state": "Michigan",
            "zip": "48326",
            "country_code": "US",
            "phone": "123456789",
            "email": "1469095459@example.com"
        }],
        "payments": [{
            "reference": "52",
            "currency": "USD",
            "transactions": [{
                "payment_method": "ZEROPAY",
                "payment_submethod": "ZEROPAY",
                "amount": 255,
                "gateway_information": {
                    "gateway_id": "OFFLINE",
                    "authorization_status": "AUTHORIZED"
                },
                "billing_address_reference": "104"
            }]
        }],
        "lines": [{
            "id": "56",
            "line_number": 1,
            "product_type": "PHYSICAL",
            "sku": "WB-WD7S",
            "product_name": "Wasburn WD7S",
            "shipping_address_reference": "103",
            "payment_reference": "52",
            "amount": {
                "net_amount": "121",
                "gross_amount": "100",
                "tax_amount": "21",
                "tax_rate": "21",
                "taxes": [{
                    "type": "VAT",
                    "amount": "21",
                    "rate": "21"
                }],
                "currency": "USD"
            },
            "promotions_info": {
                "original_price": 250,
                "promotions": [{
                    "code": "Q2AI26QUQPEH",
                    "discount": 12.1,
                    "name": "Push it to the limit",
                    "percentage": 10
                }]
            }
        }, {
            "id": "54-103",
            "line_number": 2,
            "product_type": "SHIPPING",
            "sku": "STANDARD",
            "product_name": "Shipping",
            "shipping_address_reference": "103",
            "payment_reference": "52",
            "amount": {
                "net_amount": 5,
                "gross_amount": 6.05,
                "tax_amount": 0,
                "tax_rate": 0,
                "taxes": [{
                    "type": "VAT",
                    "amount": 1.05,
                    "rate": 21
                }],
                "currency": "USD"
            }
        }]
    }
}


Order Status

Topic: magento.sales.order_management.updated

Header: (need to add “to” in the headers with value*)

The Order Status Message is generated by the OMS every time there is an order status update in an order or order line, to inform external systems of the update. Once the order is sourced, each line will indicate the source_id of the source that will fulfill the order.

Order Status and Description
  • NEW: As soon as the order is imported in the OMS the order status is set to NEW
  • RECEIVED: After some basic validation of the order the status is updated to RECEIVED
  • ERROR: In case there is any error, and the order cannot be processed further the status is ERROR
  • ONHOLD: This status is indicating the order is on remorse time
  • LOGISTICS: All steps such as sourcing, picking, packing, and shipping are represented with this order status
  • LOGISTICSCOMPLETE: Once all the lines of an order are either shipped or canceled. This status only lasts few seconds and is updated almost immediately to complete.
  • COMPLETE: Means that all the order lines of the orders are in a final status (canceled or shipped)
Order Line Status and Description
  • NEW: All new orders have lines in status NEW until the fulfillment process is initiated
  • SHIPPED: The line have been shipped
  • CANCELLED: The line have been canceled
  • RESOURCED: The line was assigned to a store for picking but is now again pending to be sourced because it was pick declined
  • ITEM_PENDING_PICKING: The pick list have been initiated, but this order line has not been picked yet
  • PICKDECLINED: This status will last only a few seconds as the pick declined are enqueued again in the sourcing engine and updated to the status RESOURCED
  • PICKCONFIRMED: The picking has been confirmed for the item and is now pending shipment

JSON example


{
  "order": {
    "id": "000000063",
    "status": "COMPLETE",
    "store": "CLIENT",
    "ip": "172.17.0.2",
    "language": "es_MX",
    "vat_country": "MX",
    "origin": "FRONTEND",
    "origin_date": "2016-08-17T09:25:48+00:00",
    "customer_service_agent": "",
    "customer": {
      "id": "1",
      "type": "REGISTERED",
      "segment": "B2C"
    },
    "addresses": [{
      "reference": "104",
      "address_type": "customer",
      "first_name": "Christophe",
      "last_name": "Trichet",
      "address1": "6 Championship Dr",
      "address2": "",
      "city": "Auburn Hills",
      "state": "Michigan",
      "zip": "48326",
      "country_code": "US",
      "phone": "123456789",
      "email": "1469095459@example.com"
    }, {
      "reference": "103",
      "address_type": "customer",
      "first_name": "Christophe",
      "last_name": "Trichet",
      "address1": "6 Championship Dr",
      "address2": "",
      "city": "Auburn Hills",
      "state": "Michigan",
      "zip": "48326",
      "country_code": "US",
      "phone": "123456789",
      "email": "1469095459@example.com"
    }],
    "payments": [{
      "reference": "52",
      "currency": "USD",
      "transactions": [{
        "payment_method": "ZEROPAY",
        "payment_submethod": "ZEROPAY",
        "amount": 255,
        "gateway_information": {
          "gateway_id": "OFFLINE",
          "authorization_status": "AUTHORIZED"
          },
        "billing_address_reference": "104"
      }]
    }],
    "lines": [{
      "id": "56",
      "line_number": 1,
      "status": "SHIPPED",
      "product_type": "PHYSICAL",
      "sku": "WB-WD7S",
      "product_name": "Wasburn WD7S",
      "shipping_address_reference": "103",
      "payment_reference": "52",
      "source_id": "L001",
      "amount": {
        "net_amount": "121",
        "gross_amount": "100",
        "tax_amount": "21",
        "tax_rate": "21",
        "taxes": [{
          "type": "VAT",
          "amount": "21",
          "rate": "21"
        }],
        "currency": "USD"
      },
      "promotions_info": {
        "original_price": 250,
        "promotions": [{
          "code": "Q2AI26QUQPEH",
          "discount": 12.1,
          "name": "Push it to the limit",
          "percentage": 10
        }]
      }
    }, {
      "id": "54-103",
      "line_number": 2,
      "status": "SHIPPED",
      "product_type": "SHIPPING",
      "sku": "STANDARD",
      "product_name": "Shipping",
      "shipping_address_reference": "103",
      "payment_reference": "52",
      "source_id": " L001",
      "amount": {
        "net_amount": 5,
        "gross_amount": 6.05,
        "tax_amount": 0,
        "tax_rate": 0,
        "taxes": [{
          "type": "VAT",
          "amount": 1.05,
          "rate": 21
        }],
        "currency": "USD"
      }
    }]
  }
}

Order Cancelation API

URL structure: /orders/{orderId}/cancel - POST

Parameters:

  • Order externalid
  • Userid that performed the cancelation

Response messages:

  • 200: cancellation successful
  • 400: Exception occurred during order cancellation
  • 406: Order cancellation verification failed

Example URL:

http://devlyn-stg.bcn.magento.com/api/orders/000000140/cancel

Example response messages:

{
  "response": {
    "orderId": "000000141"
  }
}


{
  "exception": "Order 000000140 is not in a cancellable status: LOGISTICS - READYTOSHIP",
  "code": null
}

Inventory check API

The API expects to receive a request for a list of SKUs in a specific stock aggregate, and the response will provide the quantity available in the stock aggregate. This quantity will be the aggregated count of the stock across the entire network including the safety stocks buffer. http://devlyn-stg.bcn.magento.com/api/#!/Inventory/get_store_storeExternalId_stock

URL structure: /store/{storeExternalId}/stock - GET

Parameters:

  • Storeexternalid
  • SKUs separated by comma

Example URL:

http://devlyn-stg.bcn.magento.com/api/store/STORE/stock?skus=1111111111%2C%202222222222%2C24-MB01

Example response messages:

[
  {
    "sku": "2222222222",
    "quantity": "98"
  },
  {
    "sku": "24-MB01",
    "quantity": "97"
  },
  {
    "sku": "1111111111",
    "quantity": "99"
  }
]

Oauth validation

Oauth2 is used as authorization framework to enable applications to obtain access to user accounts on an HTTP service.

As a first step the application needs to request a token to be generated by the OAuth server:

https://auth-stg.bcn.magento.com/oauth/token [POST]

Payload (form-data):

{
 "access_token": "uivXjfL3n7XlEOeUItUCS7gjuOQDJfakYRpSO48S",
 "token_type": "Bearer",
 "expires_in": 3600
}

The access_token will then be used in the requests made to the APIs. It will have to be provided in the header as follows: http://devlyn-stg.bcn.magento.com/api/ -> Authorization: Bearer

Item Master

Topic: magento.catalog.product_management.update

Header: (need to add “to” in the headers with value*)

The Item Master feed/message informs the OMS about the basic set of SKUs that will be sold via MC and from the in-store interfaces (POS). The feed/message can include information such as SKU, name, price, status, dimensions, etc.

Price and dimensions

The provided price can be used for export declarations and statistics but will not be visible to the end customer as it is different from the store price. The catalogue is sent as either a full feed or a delta feed which only includes changes since the last feed.

Product types

Magento OMS supports three types of SKUs:

  • PHYSICAL: normal physical products with stock
  • SERVICE: services such as gift wrap, engraving, hemming, etc.
  • SHIPPING: shipping type
Configurable Products VS Simple Products

Magento OMS supports a catalog structure for items holding one or more options. The JSON example below is in currently being refined to define how the final relationship between an item (configurable product) and option (simple product) will be (children_skus array).

Examples

JSON example

{
    "product": {
        "created_at": "2016-04-28T11:18:54+00:00",
        "status": "active/inactive/eol",
        "modified_at": "2016-06-28T13:24:42+00:00",
        "type": "PHYSYCAL",
        "name": [
            {
                "channel": null,
                "locale": null,
                "value": "Washburn WD7S"
            },
            {
                "channel": "frontend",
                "locale": "es_ES",
                "value": "Guitarra Washburn WD7S"
            },
            {
                "channel": "frontend",
                "locale": "en_US",
                "value": "Washburn WD7S Guitar"
            }
        ],
        "sku": "WB-WD7S",
        "price": {
            "currency": "EUR"
            "quantity": "20.00"
        },
        "children_skus": [
            "sku1",
            "sku2",
            "sku3"
        ]
    }
}

XML example

<?xml version="1.0" encoding="UTF-8"?>
<itemMaster version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="../../schema/item-master.xsd">
    <client>DEVLYN</client>
    <items>
        <item>
            <details>
                <clientCode>6BHTV024</clientCode>
                <styleCode>6BHTV024</styleCode>
                <name>Long Sleeves T-Shirt-HT122</name>
                <type>PHYSICAL</type>
                <category>Shirt</category>
                <originCountry>ESP</originCountry>
                <price>
                    <currency>EUR</currency>
                    <amount>49</amount>
                </price>
                <serialNumbers>false</serialNumbers>
            </details>
            <warehouseData>
                <warehouseMeasurements>
                    <param>
                        <key>height</key>
                        <unit>cm</unit>
                        <value>55</value>
                    </param>
                </warehouseMeasurements>
                <warehouseInfo>
                    <param>
                        <key>season</key>
                        <value>0906</value>
                    </param>
                </warehouseInfo>
            </warehouseData>
            <variants>
                <variant>
                    <sku>8718343609973</sku>
                    <clientSku>8718343609973</clientSku>
                    <optionName>Long Sleeves T-Shirt</optionName>
                    <status>ACTIVE/INACTIVE/EOL</status>
                    <price>
                        <currency>EUR</currency>
                        <amount>49.95</amount>
                    </price>
                    <attributes>
                        <param>
                            <key>COLOR</key>
                            <value>514</value>
                        </param>
                        <param>
                            <key>COLORNAME</key>
                            <value>Medium Pur</value>
                        </param>
                        <param>
                            <key>SIZE</key>
                            <value>32</value>
                        </param>
                    </attributes>
                    <warehouseData>
                        <warehouseMeasurements>
                            <param>
                                <key>height</key>
                                <unit>cm</unit>
                                <value>55</value>
                            </param>
                        </warehouseMeasurements>
                        <warehouseInfo>
                            <param>
                                <key>season</key>
                                <value>0906</value>
                            </param>
                        </warehouseInfo>
                    </warehouseData>
                </variant>
            </variants>
        </item>
    </items>
</itemMaster>

Inventory snapshot

Topic: magento.inventory.source_stock_management.update

Header: (need to add “to” in the headers with value*)

The Stock Snapshot is a feed that is used for stock audit and reconciliation purposes, front-ends or the internal client’s system (ERP). The Magento OMS expects a stock-snapshot feed for each one of the stock sources (either warehouses or physical stores). Where necessary, multiple sources feeds will be aggregated and rules applied before the generation of frontend feeds which can be provided for a single web store or a group of web stores.

XML example Name of the file: DEVLYN_stock-snapshot_sourceid_YYYYMMDDHH.xml The snapshots are sent as either a full, delta or non-zero (which is the same as the full feed but SKUs not included should be assumed to have a stock of zero).


<?xml version="1.0" encoding="UTF-8"?>
<stockSnapshot
        version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="../../schema/stock-snapshot.xsd">
    <client>DEVLYN</client>
    <source>WAREHOUSE1</source>
    <mode>FULL/DELTA</mode>
    <snapshotTime>2016-06-17T17:22:01Z</snapshotTime>
    <items>
        <item>
            <clientSku>8718343609973</clientSku>
            <stockType>GOOD</stockType>
            <qty>7</qty>
        </item>
        <item>
            <clientSku>8718343609974</clientSku>
            <stockType>GOOD</stockType>
            <qty>43</qty>
        </item>
        <item>
            <clientSku>8718343609975</clientSku>
            <stockType>DAMAGED</stockType>
            <qty>19</qty>
        </item>
        <item>
            <clientSku>8718343609873</clientSku>
            <stockType>GOOD</stockType>
            <qty>6786</qty>
        </item>
    </items>
</stockSnapshot>