Realtime Data

Sometimes you rely on fresher data or real-time data and can't use the data from our cached database. For this purpose we created the sellytis DATA API Execution Engine . You can use the engines APIs to create Jobs & Tasks in our system that will execute as fast as possible and send you a callback webhook when your job is done.

Requirements#

A sellytics DATA API Bearer access_token to make authenticated API requests [see documentation]

Jobs & Tasks#

TypeDescription
TaskA Task is the smallest entity in the execution context. It describes a concrete task what the engine should do. There are many different task-types you can choose from that define different workloads and also have different input-properties. Multiple tasks can be packaged as a Job to have bulk processing. Each tasks can be identified by its id.
JobA Job is a wrapper or some kind of bulk request to summarize a collection of tasks. Each job can be uniquely identified by its id and can hold a list of different tasks. So mixing of task-types is possible. The maximal size of tasks a job can hold is currently 1000 tasks.
TaskResultA TaskResult is the result of a successful executed task and has a TTL of 48 hours. After a job or a task is done you have to fetch the task result within 48 hours otherwise it won't be possible to obtain it anymore since we delete the result after this time.

Creation of a job with some tasks#

As we already know a job can hold a list of tasks. To create a job you have to make use of the jobs API endpoint.

Example request to create a job with different tasks#

curl -X POST 'https://api.sellytics.com/jobs/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-access-token>'
--data-raw '{
"callbackUrl": "https://your-service.url/job-is-ready/{{jobID}}",`
"tasks": [
{
"type": "AMAZON_PRODUCT_DETAIL_TASK",
"asin": "B01KB7IUX0",
"marketplace": "DE"
},
{
"type": "IDEALO_PRODUCT_DETAIL_TASK",
"productId": "200248318",
"marketplace": "DE"
},
{
"type": "AMAZON_OFFER_LISTING_TASK",
"asin": "B01KB7IUX0",
"marketplace": "ES"
},
{
"type": "AMAZON_KEYWORD_LOOKUP_TASK",
"keyword": "macbook pro 13 case",
"marketplace": "DE"
}
]
}'

Example response after creation of a job#

After you've created a job you will get a response like the following. You should persist the job-id from this response to keep track of your jobs. It's also important to know the job-ids to know which job to get or mark as done in your system if you get a callback request from our DATA API execution engine with the job-id as GET parameter. You don't have to use callbacks but it's strongly recommend. To get information about how callbacks work and what they are click here.

{
"id": "470f1ff322734528828e32de91f535a4",
"dateCreated": "2021-03-05T16:21:54.825256Z",
"callbackUrl": "https://your-service.url/job-is-ready/470f1ff322734528828e32de91f535a4",
"status": {
"statusCode": "CREATED",
"message": "Job was created and queued.",
"date": "2021-03-05T16:21:54.825554Z"
},
"summary": {
"tasks": 4,
"costs": 40,
"taskTypes": {
"AMAZON_PRODUCT_DETAIL_TASK": 1,
"IDEALO_PRODUCT_DETAIL_TASK": 1,
"AMAZON_OFFER_LISTING_TASK": 1,
"AMAZON_KEYWORD_LOOKUP_TASK": 1
}
},
"tasks": [
{
"type": "AMAZON_PRODUCT_DETAIL_TASK",
"id": "6054db9ed2e98f5fb6561412",
"status": {
"statusCode": "QUEUED",
"message": "Task was queued.",
"date": "2021-03-19T17:13:02.662133Z"
},
"refunded": false,
"marketplace": "DE",
"asin": "B00PUKOIBW",
"withStock": null
},
{
"type": "IDEALO_PRODUCT_DETAIL_TASK",
"id": "6054db9ed2e98f5fb6561543",
"status": {
"statusCode": "QUEUED",
"message": "Task was queued.",
"date": "2021-03-19T17:13:02.662133Z"
},
"refunded": false,
"marketplace": "DE",
"productId": "B00PUKOIBW"
},
{
"type": "AMAZON_OFFER_LISTING_TASK",
"id": "6054db9ed2e98f5fb6561337",
"status": {
"statusCode": "QUEUED",
"message": "Task was queued.",
"date": "2021-03-19T17:13:02.662133Z"
},
"refunded": false,
"marketplace": "DE",
"asin": "B00PUKOIBW",
"maxPages": 1
},
{
"type": "AMAZON_KEYWORD_LOOKUP_TASK",
"id": "6054db9ed2e98f5fb6561456",
"status": {
"statusCode": "QUEUED",
"message": "Task was queued.",
"date": "2021-03-19T17:13:02.662133Z"
},
"refunded": false,
"marketplace": "DE",
"asin": "B00PUKOIBW",
"maxPages": 1
}
]
}

Callbacks#

Since the sellytics DATA API execution engine is highly asynchronous to provide best performance we provide a callback / webhook feature. With this feature you don't have to poll our APIs because our system will inform you when your job is ready. Just optionally provide the field callbackUrl in your job-creation request if you want to get a callback when your job is ready. This url can contain the placeholder variable {{jobId}} which will be replaced by our system before requesting the callbackUrl. The callback is a http GET request.

"callbackUrl": "https://your-service.url/job-is-ready/{{jobID}}",

Polling of job status#

To get the status or information about a job you can use the following api endpoint to obtain the job information. We recommend to only use polling with this endpoint in case you can't use the better approach with callbacks.

curl -X GET "https://api.sellytics.com/jobs/<your-job-id>/v1" \
--header "accept: application/json" \
--header 'Authorization: Bearer <your-access-token>'

You will then get the job information response.

{
"id": "<the-requested-job-id>",
"dateCreated": "2021-03-03T19:38:38.8Z",
"callbackUrl": "https://your-service.url/jobs/<the-replaced-job-id>",
"status": {
"statusCode": "DONE",
"message": "Job is done.",
"date": "2021-03-03T19:38:38.8Z"
},
"summary": {
"tasks": 8,
"costs": 80,
"taskTypes": {
"AMAZON_KEYWORD_LOOKUP_TASK": 2,
"AMAZON_PRODUCT_DETAIL_TASK": 6
}
}
}

Getting the result of a successful task#

To get your personal result for your previously created task you can use the task-result endpoint to obtain the result-data. Use the task-id you've gotten from the job creation to get the result of a specific task.

Example getting task-result for task-id#

curl -X GET "https://api.sellytics.com/tasks/<your-task-id>/task-result/v1" \
--header "accept: application/json" \
--header 'Authorization: Bearer <your-access-token>'

The response of this depends on the original task-type.

Example task-result of an AMAZON_OFFER_LISTING_TASK#

{
“id”: “6057bb442e3e2a6b9ab24f98",
“jobId”: “05361fa9edda49d898c37d6cadd232cb”,
“taskId”: “6057bb442e3e2a6b9ab24f98",
“dateCreated”: “2021-03-21T21:31:49.392Z”,
“content”: {
“type”: “AMAZON_OFFER_LISTING_TASK_RESULT”,
“marketplace”: “DE”,
“asin”: “B00PUKOIBW”,
“offers”: [
{
“seller”: {
“asid”: “A1JPUUIHWVC5C2”,
“title”: “Incutex Deutschland”
},
“shippedBy”: {
“asid”: “amazon”,
“title”: “Amazon”
},
“price”: {
“gross”: 10.95,
“currency”: “EUR”
},
“shippingCosts”: {
“gross”: 0.0,
“currency”: “EUR”
},
“used”: false
},
{
“seller”: {
“asid”: “A1JPUUIHWVC5C2",
“title”: “Incutex Deutschland”
},
“shippedBy”: {
“asid”: “A1JPUUIHWVC5C2”,
“title”: “Incutex Deutschland”
},
“price”: {
“gross”: 10.95,
“currency”: “EUR”
},
“shippingCosts”: {
“gross”: 0.0,
“currency”: “EUR”
},
“used”: false
}
],
“date”: “2021-03-21T21:31:49.382Z”
}
}

You can find more endpoints and APIs in our reference.