Reverse Invoke API

Last updated: Aug 2nd, 2018
Watch Star

Protocol

To build an implementation a reverse invoke connector to click2sync, there is a recommended protocol from Click2Sync of the order in which all the calls from your daemon to the Click2Sync platform need to take place. We recommend this approach for systems that are behind a firewall or when building a public layer is something your IT team does not like and your ERP or legacy database is in a server that has access to the internet.

Overview

This is the overall recommended daemon loop structure we propose for the reverse invoke protocol. The loop is divided in the process of asking the Click2Sync platform if it is asking for new information, or if it is waiting for the daemon to write information in its legacy application. Finally the loop ends and it is recommended to have a sleep lapse of time before starting again the loop.

(Some of the items are clickable and you can lookup deeper what is the substructure or procedure that is represented by that step.)

Product upload
Order upload
Product download
Order download

REST Calls

The following are all the Click2Sync Reverse Invoke API REST JSON Calls you can request for changing states in the process of reverse integrating with Click2Sync.

Ask if fetching

GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/ping

should return the connection status in a format similar to this:

{"connectionstatus":"fetchingremote"}

Push products page
  1. First you need to ask some things

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/upstreamstatus

    should return the connection upstream status in a format similar to this:

    {"connectionstatus":"waiting"}

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/strategy

    should return the connection upstream status in a format similar to this:

    {"strategy":"push"} or {"strategy":"pingsample"}

    this means that you can be called to just send a sample for healthy checks, or a full dataset

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/entity

    should return the connection entity that is currently being asked:

    {"entity":"products"} or {"entity":"orders"}

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/cursoroffset

    should return the connection upstream status in a format similar to this:

    {"cursoroffset":1517358864869}

    this number is the last update time in millis of the last discovered (by Click2Sync) record of the entity type currently selected

  2. Then you need to initialize the upstream process by calling

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/initialize

    should return http code 200

    Also when asking again for the upstream status it should respond with

    {"connectionstatus":"initialized"}

  3. Then if you check that the entity you are being asked for is "products", you are ready to start pushing your products to Click2Sync

    But you need to be careful, your task could be just to send a sample, or all the dataset (strategy)

    1. If you are being asked for a sample

      POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pingsample/products

    2. If you are being asked for a normal push

      POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/products

    3. The body you send should have a structure similar to this

      
      {
        "products": [
      	{
      	  "_id": "100004777",
      	  "sku": "100004777",
      	  "last_updated": 1517360038797,
      	  "title": "EON618S JBL SUBWOOFER 18\" AMPLIFICADO",
      	  "url": "",
      	  "brand": "",
      	  "mpn": "",
      	  "model": "",
      	  "description": "JBL Premium Transducers",
      	  "variations": [
      		{
      		  "availabilities": [
      			{
      			  "tag": "default",
      			  "quantity": "50"
      			}
      		  ],
      		  "prices": [
      			{
      			  "tag": "default",
      			  "currency": "USD",
      			  "number": "1060.51"
      			}
      		  ],
      		  "images": [
      			{
      			  "url": "https://www.example.com/13080-thickbox_default/eon618s-jbl-subwoofer-18-amplificado-.jpg"
      			}
      		  ],
      		  "videos": [
      			{
      			  "url": ""
      			}
      		  ],
      		  "barcode": "",
      		  "size": "",
      		  "color": ""
      		}
      	  ]
      	},
      	{
      	  "_id": "100004777",
      	  "sku": "100004777",
      	  "last_updated": 1517360038797,
      	  "title": "EON618S JBL SUBWOOFER 18\" AMPLIFICADO",
      	  "url": "",
      	  "brand": "",
      	  "mpn": "",
      	  "model": "",
      	  "description": "JBL Premium Transducers",
      	  "variations": [
      		{
      		  "availabilities": [
      			{
      			  "tag": "default",
      			  "quantity": "50"
      			}
      		  ],
      		  "prices": [
      			{
      			  "tag": "default",
      			  "currency": "USD",
      			  "number": "1060.51"
      			}
      		  ],
      		  "images": [
      			{
      			  "url": "https://www.example.com/13080-thickbox_default/eon618s-jbl-subwoofer-18-amplificado-.jpg"
      			}
      		  ],
      		  "videos": [
      			{
      			  "url": ""
      			}
      		  ],
      		  "barcode": "",
      		  "size": "",
      		  "color": ""
      		}
      	  ]
      	}
        ]
      }
      

Set finish product pushs

When you finish pushing your products "finalize" the process

  1. If you are being asked for a sample

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pingsample/products/finish

  2. If you are being asked for a normal push

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/products/finish

  3. The body is ignored so just send an empty body

    {}

Push orders page
  1. First you need to ask some things

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/upstreamstatus

    should return the connection upstream status in a format similar to this:

    {"connectionstatus":"waiting"}

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/strategy

    should return the connection upstream status in a format similar to this:

    {"strategy":"push"} or {"strategy":"pingsample"}

    this means that you can be called to just send a sample for healthy checks, or a full dataset

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/entity

    should return the connection entity that is currently being asked:

    {"entity":"products"} or {"entity":"orders"}

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/cursoroffset

    should return the connection upstream status in a format similar to this:

    {"cursoroffset":1517358864869}

    this number is the last update time in millis of the last discovered (by Click2Sync) record of the entity type currently selected

  2. Then you need to initialize the upstream process by calling

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/initialize

    should return http code 200

    Also when asking again for the upstream status it should respond with

    {"connectionstatus":"initialized"}

  3. Then if you check that the entity you are being asked for is "orders", you are ready to start pushing your orders to Click2Sync

    But you need to be careful, your task could be just to send a sample, or all the dataset (strategy)

    1. If you are being asked for a sample

      POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pingsample/orders

    2. If you are being asked for a normal push

      POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/orders

    3. The body you send should have a structure similar to this

      
      {
        "orders": [
      	{
      	  "_id": "75554554546",
      	  "orderid": "777777",
      	  "last_updated": 1517360038797,
      	  "status": "paid",
      	  "dateCreated": "",
      	  "dateClosed": "",
      	  "total": {
      		"amount": 350,
      		"currency": "USD"
      	  },
      	  "orderItems": [
      		{
      		  "id": "7778545",
      		  "variation_id": "0",
      		  "quantity": "1",
      		  "unitPrice": "350",
      		  "currencyId": "USD"
      		}
      	  ],
      	  "buyer": {
      		"id": "4578889",
      		"email": "testbuyer@example.com",
      		"phone": "88888888",
      		"firstName": "John",
      		"lastName": "Doe"
      	  }
      	}
        ]
      }
      

Set finish orders pushs

When you finish pushing your orders "finalize" the process

  1. If you are being asked for a sample

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pingsample/orders/finish

  2. If you are being asked for a normal push

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/products/finish

  3. The body is ignored so just send an empty body

    {}

Set finish all pushs

When you finish pushing your products and/or orders you "finalize" the process

  1. If you are being asked for a sample

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pingsample/finish

  2. If you are being asked for a normal push

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/push/finish

  3. The body is ignored so just send an empty body

    {}

  4. Check the upstream status again and should say:

    {"connectionstatus":"finishing"} or {"connectionstatus":"finished"}

    you should wait until the status is finished to proceed with other transactions

Ask if pulling

GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/ping

should return the connection status in a format similar to this:

{"connectionstatus":"pulling"}

Pull products page
  1. First you need to ask some things

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/upstreamstatus

    should return the connection upstream status in a format similar to this:

    {"connectionstatus":"waiting"}

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/entity

    should return the connection entity that is currently being asked:

    {"entity":"products"} or {"entity":"orders"}

  2. You need to initialize the donwload:

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/initialize

    Then request upstream again and wait for it to be initialized

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/upstreamstatus

    should return the connection entity that is currently being asked:

    {"connectionstatus":"initialized"}

Get next product to pull
  1. First you need to ask if there are updates to download, this is done like a cursor with the hasmore flag

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/hasmore

    should return the connection upstream status in a format similar to this:

    {"hasmore":"waiting"} or {"hasmore":"ready"}

    if it is waiting, the server is processing the last transaction, you should wait until ready to proceed asking for the next product

  2. Then you proceed to ask record per record

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/next

    should return the product to insert/update like this

    
    {
      "product": {
    	"_id": "100004777",
    	"sku": "100004777",
    	"last_updated": 1517360038797,
    	"title": "EON618S JBL SUBWOOFER 18\" AMPLIFICADO",
    	"url": "",
    	"brand": "",
    	"mpn": "",
    	"model": "",
    	"description": "JBL Premium Transducers",
    	"variations": [
    	  {
    		"availabilities": [
    		  {
    			"tag": "default",
    			"quantity": "50"
    		  }
    		],
    		"prices": [
    		  {
    			"tag": "default",
    			"currency": "USD",
    			"number": "1060.51"
    		  }
    		],
    		"images": [
    		  {
    			"url": "https://www.example.com/13080-thickbox_default/eon618s-jbl-subwoofer-18-amplificado-.jpg"
    		  }
    		],
    		"videos": [
    		  {
    			"url": ""
    		  }
    		],
    		"barcode": "",
    		"size": "",
    		"color": ""
    	  }
    	]
      }
    }
    

Notify product storage success

In this step you already made whatever necessary to process the update/insert that was notified from Click2Sync. Then you need to tell Click2Sync if you achieved it or if there was any problem with the update tell Click2Sync the problem you had

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/{{_id}}/succeded

the body should be the product you inserted/updated


{
  "product": {
	"_id": "100004777",
	"sku": "100004777",
	"last_updated": 1517360038797,
	"title": "EON618S JBL SUBWOOFER 18\" AMPLIFICADO",
	"url": "",
	"brand": "",
	"mpn": "",
	"model": "",
	"description": "JBL Premium Transducers",
	"variations": [
	  {
		"availabilities": [
		  {
			"tag": "default",
			"quantity": "50"
		  }
		],
		"prices": [
		  {
			"tag": "default",
			"currency": "USD",
			"number": "1060.51"
		  }
		],
		"images": [
		  {
			"url": "https://www.example.com/13080-thickbox_default/eon618s-jbl-subwoofer-18-amplificado-.jpg"
		  }
		],
		"videos": [
		  {
			"url": ""
		  }
		],
		"barcode": "",
		"size": "",
		"color": ""
	  }
	]
  }
}

it should respond HTTP 200 OK, and then you need to wait until the product transaction is completed by Click2Sync, for this you should need to ask for the product pull readyfornext status to be ready:

GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/readyfornext

should respond with a format like this:

{"ready":false} or {"ready":true}

Notify product storage failure

In this step you already made whatever necessary to process the update/insert that was notified from Click2Sync. Then you need to tell Click2Sync if you achieved it or if there was any problem with the update tell Click2Sync the problem you had

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/{{_id}}/failed

the body should be the product you inserted/updated


{
  "error":"could not pull product",
  "reasons":[
	{
	  "message":"custom error string message",
	  "code":400
	}
  ]
}

it should respond HTTP 200 OK, and then you need to wait until the product transaction is completed by Click2Sync, for this you should need to ask for the product pull readyfornext status to be ready:

GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/readyfornext

should respond with a format like this:

{"ready":false} or {"ready":true}

Set finish product download

When no more products to download just commit to Click2Sync the message that you are finished processing updates from Click2Sync

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/products/finish

the body can be just an empty object {} and it should respond with an HTTP 200 OK

Pull orders page
  1. First you need to ask some things

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/upstreamstatus

    should return the connection upstream status in a format similar to this:

    {"connectionstatus":"waiting"}

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/entity

    should return the connection entity that is currently being asked:

    {"entity":"products"} or {"entity":"orders"}

  2. You need to initialize the donwload:

    POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/initialize

    Then request upstream again and wait for it to be initialized

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/upstreamstatus

    should return the connection entity that is currently being asked:

    {"connectionstatus":"initialized"}

Get next order to pull
  1. First you need to ask if there are updates to download, this is done like a cursor with the hasmore flag

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/hasmore

    should return the connection upstream status in a format similar to this:

    {"hasmore":"waiting"} or {"hasmore":"ready"}

    if it is waiting, the server is processing the last transaction, you should wait until ready to proceed asking for the next order

  2. Then you proceed to ask record per record

    GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/next

    should return the order to insert/update like this

    
    {
      "order": {
    	"_id": "75554554546",
    	"orderid": "777777",
    	"last_updated": 1517360038797,
    	"status": "paid",
    	"dateCreated": "",
    	"dateClosed": "",
    	"total": {
    	  "amount": 350,
    	  "currency": "USD"
    	},
    	"orderItems": [
    	  {
    		"id": "7778545",
    		"variation_id": "0",
    		"quantity": "1",
    		"unitPrice": "350",
    		"currencyId": "USD"
    	  }
    	],
    	"buyer": {
    	  "id": "4578889",
    	  "email": "testbuyer@example.com",
    	  "phone": "88888888",
    	  "firstName": "John",
    	  "lastName": "Doe"
    	}
      }
    }
    

Notify order storage success

In this step you already made whatever necessary to process the update/insert that was notified from Click2Sync. Then you need to tell Click2Sync if you achieved it or if there was any problem with the update tell Click2Sync the problem you had

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/{{_id}}/succeded

the body should be the order you inserted/updated


{
  "order": {
	"_id": "75554554546",
	"orderid": "777777",
	"last_updated": 1517360038797,
	"status": "paid",
	"dateCreated": "",
	"dateClosed": "",
	"total": {
	  "amount": 350,
	  "currency": "USD"
	},
	"orderItems": [
	  {
		"id": "7778545",
		"variation_id": "0",
		"quantity": "1",
		"unitPrice": "350",
		"currencyId": "USD"
	  }
	],
	"buyer": {
	  "id": "4578889",
	  "email": "testbuyer@example.com",
	  "phone": "88888888",
	  "firstName": "John",
	  "lastName": "Doe"
	}
  }
}

it should respond HTTP 200 OK, and then you need to wait until the order transaction is completed by Click2Sync, for this you should need to ask for the order pull readyfornext status to be ready:

GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/readyfornext

should respond with a format like this:

{"ready":false} or {"ready":true}

Notify order storage failure

In this step you already made whatever necessary to process the update/insert that was notified from Click2Sync. Then you need to tell Click2Sync if you achieved it or if there was any problem with the update tell Click2Sync the problem you had

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/{{_id}}/failed

the body should be the order you inserted/updated


{
  "error":"could not pull order",
  "reasons":[
	{
	  "message":"custom error string message",
	  "code":400
	}
  ]
}

it should respond HTTP 200 OK, and then you need to wait until the order transaction is completed by Click2Sync, for this you should need to ask for the order pull readyfornext status to be ready:

GET https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/readyfornext

should respond with a format like this:

{"ready":false} or {"ready":true}

Set finish order download

When no more orders to download just commit to Click2Sync the message that you are finished processing updates from Click2Sync

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/orders/finish

the body can be just an empty object {} and it should respond with an HTTP 200 OK

Transact finish pull

When no more updates globally to download just commit to Click2Sync the message that you are finished processing "ALL" updates from Click2Sync this time

POST https://api.click2sync.com/api/adapters/custom/reverse/connection/{{your key}}/pull/finish

the body can be just an empty object {} and it should respond with an HTTP 200 OK

Implementation

Implementing the following parts of the flow is a core part of the reverse connector development. Think of it as the methods of an abstract class that you are implementing.

Query implementation products

The query part of the products that are on your legacy ERP, database, etc. is a pagination process of first extracting or quering your products from your source application, transforming it in an array of products with the Click2Sync structure, and send them to Click2Sync. You define the page size that fits better to your performance needs.

You need to also know if your result set contains more products to know when to stop pushing products to Click2Sync. (has more)

Is it mandatory to synchronize both products and orders?
No, you can choose to implement just the products or the orders synchronization. You just need to make sure all the steps of transactioning between connection states are done in the right order.

Query implementation orders

The query part of the orders that are on your legacy ERP, database, etc. is a pagination process of first extracting or quering your orders from your source application, transforming it in an array of orders with the Click2Sync structure, and send them to Click2Sync. You define the page size that fits better to your performance needs.

You need to also know if your result set contains more orders to know when to stop pushing orders to Click2Sync. (has more)

Is it mandatory to synchronize both products and orders?
No, you can choose to implement just the products or the orders synchronization. You just need to make sure all the steps of transactioning between connection states are done in the right order.

Store implementation products

The store part of the products on your legacy ERP, database, etc. is the part where you receive an updated product from Click2Sync and you now need to tranform it and insert it (or update it) on your application. You can be inserting/updating a table or database directly (JDBC, ODBC, etc), or maybe through an API (SOAP, REST), or via COM, filesystem, etc.

What you need to make sure is to know if the data you are supposed to insert or update was correctly stored or updated and tell that to Click2Sync. This way Click2Sync can know that the transaction has been done correctly and your synchronization is taking place correctly.

If you send an error to Click2Sync, it will try later to send the same update/insert again in the next synchronization until you tell Click2Sync that the store was done.

If you don't send the error, Click2Sync will believe the storage process succeeded and it will not try again later. And in the next synchronization will think that the fields changed again (for the previous values) and will try to propagate that synchronization to other connections you could have on Click2Sync.

Store implementation orders

The store part of the orders on your legacy ERP, database, etc. is the part where you receive an updated order from Click2Sync and you now need to tranform it and insert it (or update it) on your application. You can be inserting/updating a table or database directly (JDBC, ODBC, etc), or maybe through an API (SOAP, REST), or via COM, filesystem, etc.

What you need to make sure is to know if the data you are supposed to insert or update was correctly stored or updated and tell that to Click2Sync. This way Click2Sync can know that the transaction has been done correctly and your synchronization is taking place correctly.

If you send an error to Click2Sync, it will try later to send the same update/insert again in the next synchronization until you tell Click2Sync that the store was done.

If you don't send the error, Click2Sync will believe the storage process succeeded and it will not try again later. And in the next synchronization will think that the fields changed again (for the previous values) and will try to propagate that synchronization to other connections you could have on Click2Sync.

Sleep & timeouts

We will review the number of calls to our API by account and communicate with you in case we think you should change the way you implemented the API.

The sleep time we recommend is 2 to 4 seconds.

When pushing or pulling products on your implementation. Click2Sync will timeout after 30 seconds subject to change by our UX team of the platform. So make sure the time between calls of the process does not exceed this time or the process will be finished.

Your browser is out of date!

Update your browser to view this website correctly. Update my browser now

×