Make your own connector

Freely integrate with your own API’s

For more advanced use cases, the set of order flow connectors that Twikit provides may be insufficient. Therefore, Twikit Live provides a way to extend the capabilities and create your own connectors. Typical use cases are:

Receive updates when an order is created or on order status changes.
Download order files in a third party system and use them for manufacturing, back-up cloud storage or post-processing.

Before getting started, make sure you understand the concept of order flows by reading the getting started guide.

To create your own adapter that can be used in a Twikit order flow, set up your own REST API endpoint (POST subscription endpoint) according to the connector API format. Twikit Live requires this endpoint to use https. (Different API security protocols are currently not yet supported.)

Once your endpoint is up and running, it can be used in an order flow consume-rest-api task as illustrated in the example below:

{
	"key": "task-execute-your-endpoint",
	"handlerKey": "consume-rest-api",
	"payload": {
		"uri": "https://<your_endpoint>",
		"sendsFeedback": true
	},
	"timeoutDuration": 1000,
	"next": []
}

CODE

Connector API format

To implement your own connector, a public REST endpoint should be provided that supports the following API format. The endpoint will be called by a server as part of the order flow e.g. when an order is created or when it failed to process.

Requirements:

There are no restrictions on the name of the endpoint. It can be chosen freely.
The API method should be of type POST.
The API endpoint should be secured with https. (Different security protocols are currently not supported.)

The connector API format

POST https://<your_endpoint>

CODE

Headers

Content-Type	application/json

CODE

Body

{
  "order": {
    "spaceKey": "string",
    "flowKey": "string",
    "thirdPartyOrderId": "string",
    "updateUrl": "string",
    "addresses": [
      {
        "addressType": "string",
        "purpose": "string",
        "data": {}
      }
    ],
    "data": {},
    "orderLines": [
      {
        "orderId": "string",
        "title": "string",
        "data": {},
        "items": [
          {
            "id": "string",
            "data": {},
            "tags": [
              "string"
            ],
            "items": [
              null
            ],
            "assets": [
              {
                "id": "string",
                "url": "string",
                "isPublic": true,
                "versions": [
                  "url": "string",
                  "date": "2020-09-23T14:23:17.580Z"
                ]
              }
            ],
            "isAsset": true
          }
        ],
        "deadline": "2020-09-23T14:23:17.580Z",
        "amountOfUnits": 0,
        "valuePerUnit": 0
      }
    ]
  }
}

CODE

Error codes

The API caller supports the following error codes:

201	Connector method was correctly called.
400	Failed to call, invalid input.
500	Failed to call, internal error.

Online documentation

Link to the latest online documentation: https://orders.twikit.com/api/docs/#/order/OrderController_createOrder

Using a connector

When your connector is created, it can be added to an order flow. Use the “consume-rest-api” task type and fill in the name of your endpoint.

Example order flow

This order flow has one stage and one task definition that will make the system call your connector’s endpoint as part of the order flow.

Note that the body in this example order flow will not contain any manufacturing files. This requires to define an export call before defining the task that calls your connector.

{
	"stages": [
		{
			"key": "stage-1",
			"taskDefinitions": [
				{
					"key": "task-1",
					"handlerKey": "consume-rest-api",
					"payload": {
						"uri": "https://<your_endpoint_url>",
						"sendsFeedback": false
					},
					"timeoutDuration": 1000,
					"next": []
				}
			],
			"initialTaskDefinitionKeys": [
				"task-1"
			]
		}
	]
}

CODE