Integration - Custom software

This documentation provides details for creating integration with Routee-Waymore
platform.
The intention of the integration is:
a) To move the existent data held in the database from your website to Routee
Platform.
b) Expose hook events, that are performed inside your website, to Routee Platform, so
that a website owner can use Routee Platform to configure his communication
automation workflows.

Business Process

a) The website (admin) owner will be requested to enter his Routee username and
password.
*If the website owner does not have a Routee username and password, a link needs to
be displayed for him to create a new account in Routee Platform.
b) In the website, the owner enters his Routee username and password in a form to
register his website to Routee-Waymore.

Once registration is successful, the endpoint will reply back a UUID string that will be
used as required authenticate field for all the API endpoints described below.
(Note: The UUID must be stored for future use. The UUID does not expire)
c) The website needs to transfer all the historical data (data from the database) of the
site, to Routee Platform using Mass-data API.

d) The website needs to transfer all the real-time events (i.e. when a new user is
registered) to Routee Platform using Event data API.

e) The website owners, logs in to Routee-Waymore platform (using the username and
password he used when registering the site) where he can see all the data retrieved
from his website and configures his own communication workflows from within
Routee-Waymore Platform.
i.e. send an SMS to all customers that added the product X in their basket 3 days ago,
but did not complete the checkout.
i.e. send a welcome all to a user when he creates an account
etc.

Development Integration Requirements

In order to integrate with the Routee-WayMore platform, you have to consume
our API. To consume our API you have to be authenticated (register your site).

Authentication

To be authenticated you have to make an HTTP request the the Authorization
API. The API on success will return a UUID string which will be used to consume the
WayMore API.
The authentication should be done only once and not be accessible after that.
The UUID should stored so the plugin can access it everytime. The UUID should be
deleted when plugin is uninstalled.

Check API Reference: https://docs.routee.net/v1.0/reference#wm-software-authenticate

Mass data

The mass data api will send the historic data from the database. The mass data will be
sent in the following order:

  1. Customers
  2. Subscribers*
  3. Products
  4. Wishlist
  5. Orders
    The mass must be sent automatically after a successful authentication.
    The mass data must be sent in multiple parts in order to prevent sending too much data.
    The mass data must be sent in the background so the user doesn’t have to wait untill all the
    data is sent

Check API Reference: https://docs.routee.net/v1.0/reference#mass-api

Mass Data JSON examples

There are three ways you can send mass data as can be seen in the following
examples. You can choose whichever way is more suitable to you.

{
	"uuid": "8e109ec3-a69b-40fb-a648-dab158616314",
	"data": [
		{
			"name": "customers",
			"description": "shop customers",
			"object": [
        {
          "customer": {
            "id": "1",
            "lastname": "Doe",
            "firstname": "john",
            "birthday": "01/01/2000",
            "email": "john.doe@mail.com",
            "phone": "0123456789"
          },
          "addresses": [
            {
              "country": "United States of America",
              "city": "New York",
              "address1": "",
              "postcode": "534231",
              "company": ""
            }
          ],
          "cart": {}
        }
			]
		}
	]
}
{
  "uuid": "8e109ec3-a69b-40fb-a648-dab158616314",
  "data": [
  	{
        "name": "products",
        "description": "shop products",
        "object": [
          {
          "name": "products",
          "description": "products from CS Cart",
          "data": [
            {
              "product_id": "778",
              "name": "t-shirt",
              "description": "printed t-shirt",
              "short_description": "printed t-shirt",
              "categories": [
              "Clothes",
              "Men"
            ],
            "stock_quantity": 499,
            "image_link": "http://example.com/t-shirt.jpg",
            "product_link": "http://example.com/t-shirt.html",
            "product_options": [
              {
              "option_id": "1",
              "size": "S",
              "stock_quantity": 250,
              "price": 29.4,
              "discount": {},
              "color": "White"
              },
              {
              "option_id": "2",
              "size": "S",
              "stock_quantity": 249,
              "price": 29.4,
              "discount": {},
              "color": "Red"
              }
        ]
       }
      ]
      },
      {
        "product_id": "779",
        "name": "TestProduct2",
        "description": "This is a test product",
        "short_description": "short desc",
        "categories": [
          "TestCategory",
          "TestCategory2"
      ],
      "stock_quantity": 120,
      "price": 450,
      "discount": {
        "price": 400,
        "date_start": "",
        "date_end": "",
        "quantity": null
     	 },
        "product_options": [],
        "image_link": "https://www.example.com/e-com/testproduct2.jpg",
        "product_link": "https://www.example.com/e-com/testproduct2"
      },
      {
        "AnotherProduct": "data"
      }
    ]
   }
 ]
}

{
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616314",
 "data": [
   {
     "name": "products",
     "description": "shop products",
     "object": [
       {
         "product_id": "778",
         "name": "TestProduct",
         "description": "This is a test product",
         "short_description": "short desc",
         "categories": [
           "TestCategory",
           "TestCategory2"
         ],
         "stock_quantity": 100,
         "price": 45,
         "discount": {
           "price": 40,
           "date_start": "06/12/2018",
           "date_end": "10/12/2018",
           "quantity": 5
         },
         "product_options":[],
         "image_link": "https://www.example.com/e-com/testproduct.jpg",
         "product_link": "https://www.example.com/e-com/testproduct"
       },
       {
         "AnotherProduct": "data"
       }
     ]
   },
   {
     "name": "customers",
     "description": "shop customers",
     "object": [
 {
         "customer": {
           "id": "1",
           "lastname": "Doe",
           "firstname": "john",
           "birthday": "01/01/2000",
           "email": "john.doe@mail.com",
           "phone": "0123456789"
         },
         "addresses": [
           {
             "country": "United States of America",
             "city": "New York",
             "address1": "",
             "postcode": "534231",
             "company": ""
           }
         ],
         "cart": {}
       },
       {
         "customer": {
           "id": "2",
           "lastname": "Doe",
           "firstname": "john",
           "birthday": "01/01/2000",
           "email": "john.doe@mail.com",
           "phone": "0123456789"
         },
         "addresses": [
           {
             "country": "United States of America",
             "city": "New York",
             "address1": "",
             "postcode": "534231",
             "company": ""
           }
         ],
         "cart": {
           "cart_products": [
             {
               "product_id": "778",         "quantity": "1"
             }
           ]
         }
       },
       {
         "AnotherCustomer": "data"
       }
     ]
   },
   {
     "name": "orders",
     "description": "shop orders",
     "object": [
       {
         "order_details": {
           "customer_id": "33",
           "order_id": "123",
           "order_status": "pending validation",
           "shipping_method": "carrier",
           "payment_method": "credit card",
           "total_price": "150"
         },
         "order_products": [
           {
             "product_id": "1",
             "quantity": "1"
           }
         ]
       },
       {
         "AnotherOrder": "data"
       }
     ]
   },
   {
     "Other Data": "data"
   }
 ]
}

Events data

If the data can not be sent as in the JSON example because of architecture or limitations
of the plugin then send them as you see fit (e.g. putting the phone in the address and not in the
customer). If there are extra data for an event that are not in the JSON examples then add
those as well. For any changes to the JSON please update us about it so can parse the
correctly.
List of event hooks:
● CustomerAdd (User register)
● CustomerUpdate (User account/address update)
● CartUpdate (Add to cart, remove from cart)
● ProductAdd (New product created)
● ProductUpdate (Product updated)
● ProductStockUpdate (Product stock quantity changed e.g. After an order)
● ProductoutOfStock (Product is out of stock)
● OrderAdd (New order placed)
● OrderStatusUpdate (Order status changed)
● OrderPaymentConfirmed
(Order payment is confirmed)
● WishlistAdd (A product is added to the wishlist)
● WishlistDelete (A product is removed from the wishlist)
● Newsletter (A customer/guest subscribes to the newsletter)
● Search (Someone makes a search in the shop)
● Uninstall (The plugin is uninstalled)
ProductoutOfStock: If this event can not be implemented it’s ok as long as the
“ProductStockUpdate” is implemented.
*Search: This is not a critical event, it’s ok if it can’t be implemented.

Check API Reference https://docs.routee.net/v1.0/reference#events-data-api

Events data JSON examples

{
 "event": "CustomerAdd",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer": {
     "id": "1061",
     "lastname": "Doe",
     "firstname": "john",
     "birthday": "01/01/2000",
     "email": "john.doe@mail.com",
     "phone": "0123456789"
   },
   "addresses": [
     {
       "country": "United States of America",
       "city": "New York",
       "address1": "",
       "postcode": "534231",
       "company": ""
     }
   ]
 }
}
{
 "event": "CustomerUpdate",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer": {
     "id": "1061",
     "lastname": "Doe",
     "firstname": "john",
     "birthday": "01/01/2000",
     "email": "john.doe@mail.com",
     "phone": "0123456789"
   },
   "addresses": [
     {
       "country": "United States of America",
       "city": "New York",
       "address1": "",
       "postcode": "534231",
       "company": ""
     }
   ]
 }
}
{
"uuid": "string",
"event": "OrderAdd",
"data": {
  "customer_id": 13,
  "order_details": {
    "order_id": "12",
    "order_status": "Awaiting bank wire payment",
    "shipping_method": "My carrier",
    "payment_method": "Bank transfer",
    "total_price": 103.47,
    "lastname": "Doe",
    "firstname": "Jeans",
    "birthday": "1970-05-31",
    "email": "b@mai.net",
    "company": null,
    "newsletter": true,
    "website": null,
    "address1": "my address",
    "address2": "my Address Complement",
    "postcode": "12345",
    "phone": "1234567890",
    "phone_mobile": "",
    "city": "myCity",
    "country": "Greece"
  },
  "order_products": [
    {
      "product_id": "6",
      "quantity": "1",
      "option_id": null
    },
    {
      "product_id": "3",
      "quantity": "2",
      "option_id": "13"
    }
  ]
}
}

NOTE

If customer is guest and has no customer_id then the customer_id should be 0

{
 "event": "OrderStatusUpdate",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer_id": "1061",
   "order_id": "123",
   "order_status": "pending validation"
 }
}
{
 "event": "OrderPaymentConfirmed",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer_id": "1061",
   "order_id": "123"
 }
}
{
 "event": "CartUpdate",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer_id": "1061",
   "cart_products": [
     {
       "product_id": "778",
       "option_id": "1",
       "quantity": "1"
     }
   ],
   "cart_url": "https://www.site.gr/shop/cart"
 }
}

NOTE

If last product is removed from cart the event should be triggered and cart_products should be an empty array.

{
 "event": "ProductAdd",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
    "product_id": "778",
    "name": "t-shirt",
    "description": "printed t-shirt",
    "short_description": "printed t-shirt",
    "categories": [
      "Clothes",
      "Men"
    ],
    "stock_quantity": 499,
   
    "image_link": "http://example.com/t-shirt.jpg",
    "product_link": "http://example.com/t-shirt.html",
    "product_options": [
      {
        "option_id": "1",
        "size": "S",
        "stock_quantity": 250,
        "price": 29.4,
        "color": "White"
      },
      {
        "option_id": "2",
        "size": "S",
        "stock_quantity": 249,
        "price": 29.4,
        "discount": {
          "price": 23.52,
          "date_start": "2018-06-06",
          "date_end": "2018-08-06",
          "quantity": ""
        },
        "color": "Red"
      }
    ]
  }
}
{
 "event": "ProductUpdate",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "product_id": "779",
   "name": "TestProduct",
   "categories": [
     "TestCategory",
     "TestCategory2"
   ],
   "description": "This is a test product",
   "short_description": "Test product",
   "stock_quantity": 100,
   "price": 45,
   "discount": {},
   "image_link": "https://www.example.com/e-com/testproduct.jpg",
   "product_link": "https://www.example.com/e-com/testproduct",
   "product_options": []
 }
}
{
 "event": "ProductOutOfStock",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "product_id": "778"
 }
}
{
 "event": "ProductStockUpdate",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "product_id": "778",
   "option_id": "1",
   "stock_quantity": 99
 }
}

If product options don’t have stock quantity

{
 "event": "ProductStockUpdate",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "product_id": "778",
   "option_id": "1"
 }
}
{
 "event": "WishlistAdd",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "product_id": "778",
   "customer_id": "1061"
 }
}j
{
 "event": "WishlistDelete",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "product_id": "778",
   "customer_id": "1061"
 }
}
{
 "event": "Newsletter",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer_id": "1061",
   "email": "john.doe@mail.com",
   "subscription": true
 }
}
{
 "event": "Search",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {
   "customer_id": "",
   "search_string": "blue car"
 }
}
{
 "event": "Uninstall",
 "uuid": "8e109ec3-a69b-40fb-a648-dab158616318",
 "data": {}
}

Integration - Custom software


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.