An in-house app always authenticate itself. Use the token throughout this tutorial.

1. Create queue

Queue is simple as it sound, it is a first in first out queue that we will put your notification events in one side, and you can periodically pull the events out the other side.

Once the queues are created with this token, the queues becomes app’s resource. After that use that token to create queue:

POST https://api.tiki.vn/integration/v1/queues
Authorization: Bearer <IN-HOUSE-TOKEN>

Request body

{
    "name": "queue 1"
}

Response body

{
    "code": "5a84289f-ed78-4285-9670-9a34508fb4a7",
    "name": "queue 1",
    "status": "ACTIVE"
}

You have many options:

• distinct queues for different event types
• or a queue for all event types

Remember you can always separate to more queues in the future if the workload needed.

Go here for details about the endpoint to create queue.

2. Subscribe to events

After create queues you can free to choose subscriptions which event type to which queue. Currently here is the list of supported event type. We can add more in the near future so keep your eyes on this.

Subscribe all ORDER_CREATED_SUCCESSFULLY to queue 5a84289f-ed78-4285-9670-9a34508fb4a7:

POST https://api.tiki.vn/integration/v1/queues/5a84289f-ed78-4285-9670-9a34508fb4a7/subscriptions
Authorization: Bearer <IN-HOUSE-TOKEN>

Request body

{
    "event_type": "ORDER_CREATED_SUCCESSFULLY"
}

Response body

{
    "code": "38f9923b-a345-4437-a48a-d5938a4d6182",
    "active": true,
    "event_type": "ORDER_CREATED_SUCCESSFULLY",
    "sid": "969BEA7515A1A27FF4F456C782653F854E6B5D2D"
}

After your subscription it will take around 5s for your events if have start routing to your queue. Go here for details about the endpoint to subscribe to events.

3. Pull events

After subscriptions succeed, events will route to your queue if it happened.

3.0. Service Level Agreement

The event queue system guarantee that it will delivery at least one and in order events

• At least one: mean if you have an event this will sure the event will route to your queues. It might delivery duplicate events to you queue but each event generated with a UUID, so you only need to implement a simple idempotent checking to ensure you process each event only one time if you need to.
• In order: if multiple events of an object like update price of a product happened it will delivery to your queue as the order those events occurred, so you only need to update with the price of last event and don’t need worry about the order we handle it for you

It’s main api you use in event queue system. After setup queue and subscriptions. You can use this endpoint to periodically pulling and handling events from a queue.

Each time you call this endpoint we will return a list of events (if have) and an ack_id. This ack_id is there for a special purpose. It will help to prevent lost events. In the next pull request you should send the ack_id of previous ack_id so we know you are for sure received events so we will remove them and return you the next events. If you don’t send previous ack_id, you will received old events too. You can also can ack without doing a pull request

The lost events case can happen with many reasons along the network round-trip between our server with your server or your system can crash when handle the events. So even we return events with HTTP 200 to you it will not guarantee you handle them in your system successfully. One case you might lost the event if your pulling service stops for 7 days AND your event list is too big, we might drop event list and stop subscriptions

Notes: If you receive an empty event list from a pull call, you better to implement a slowdown mechanism like sleep for 1 minute for the next pull call. It will save unnecessary resources in both your system and our system.

3.1. Pull

POST https://api.tiki.vn/integration/v1/queues/{queueCode}/events/pull
Authorization: Bearer <PUBLIC-APP-SELF-TOKEN>

In your first request

Request body

{
    "ack_id": null
}

Response body

{
    "events": [
      {
          "id": "e4ecb7e5-f12f-4807-ade9-bf4aa1512b71",
          "sid": "063B7B71DF51BDB8B46C00F84F1CA928C30742A7",
          "created_at": 1604388548418,
          "payload": {
                "order_code": "203791555",
                "status": "picking"
          },
          "type": "ORDER_STATUS_UPDATED",
          "version": "v1"
      },
      {
        "id": "a96d8c5b-769e-426a-b051-eaf2a671a596",
        "sid": "063B7B71DF51BDB8B46C00F84F1CA928C30742A7",
        "created_at": 1604388764934,
         "payload": {
                "order_code": "203791555",
                "status": "picking"
          },
        "type": "ORDER_STATUS_UPDATED",
        "version": "v1"
      }
    ],
    "ack_id": "e586abc8-e6f5-43e0-2222-dc24a25c50fv"
}

In your next request

You should use this ack_id to call, then you will get the new events.

Request body

{
  "ack_id": "e586abc8-e6f5-43e0-2222-dc24a25c50fv"
}

Response body

{
  "events": [
      {
        "id": "a96d8c5b-769e-426a-b051-eaf2a671a777",
        "sid": "063B7B71DF51BDB8B46C00F84F1CA928C30742A7",
        "created_at": 1604388764934,
        "payload": {
                "order_code": "203791555",
                "status": "canceled"
          },
        "type": "ORDER_STATUS_UPDATED",
        "version": "v1"
      }
  ],
  "ack_id": "e586abc8-e6f5-43e0-2222-654654223"
}

Go here for details about the endpoint to pull events.

3.2. Acknowledgement

Tell us you have got all events until this point of time. And from the next pull, we only returns events from this point of acknowledgement onward.

POST https://api.tiki.vn/integration/v1/queues/{queueCode}/events/ack
Authorization: Bearer <PUBLIC-APP-SELF-TOKEN>

Request body

{
    "ack_id": "e586abc8-e6f5-43e0-2222-654654223"
}

Go here for details about the endpoint to ack events.