# DealsBOT API

[ToC]

# Info
🌎 **BASE URL:** `https://botsapi.dealsbot.io/bots/{endpoint}`

All replies are in `JSON`.

# Auth

Remember to add the Auth-Header to each request:

x-dealsbot-secret: <your-api-token>

**Note:** the API Token is case-sensitive!

# Error Management

## HTTP Codes
| Code | Type | Description |
| -------- | -------- | -------- |
| 200 | OK | No error occurred |
| Others | Error | Try to parse the response as JSON and check for the "code" field |

## Error Object
If any error occurs you may get an **Error Object** as response (if the request reached the server):

| Field | Type | Description |
| -------- | -------- | -------- |
| error | boolean | `true` if an error occurred |
| code | integer | the code of the error |
| message | string | a description of the error |

## Error codes
Here's a full list of possible error codes.
For each endpoint it will be specified which error codes it can return.

| Code | Name | Description |
| -------- | -------- | -------- |
| 0 | INVALID_ENDPOINT | Invalid endpoint |
| 1 | MISSING_PARAM | A mandatory parameter was missing |
| 2 | INVALID_CHANNEL | Invalid / wrong channel ID specified |
| 3 | INVALID_PRODUCT | Invalid product link specified |
| 4 | INVALID_TELEGRAMID | The specified Post Telegram ID does not exist |
| 5 | NO_AUTOPOSTS | The specified channel has no Auto Posts active (and it's required for the endpoint / parameters) |
| 6 | QUEUE_LOADING | The queue is still loading for the specified channel. Try again in 1 minute. |
| 7 | CATEGORY_NOTSELECTED | The specified category is not selected on BOT
| 11 | INVALID_REF | Error while applying the referral to the specified link
| 12 | ERROR_GETTING_INFO | An error occurred while getting the product info
| 13 | INVALID_DATE | The date specified while scheduling the product is invalid
| 14 | FULL_SCHEDULE_SLOTS | All the schedule slots are full
| 15 | DUPLICATES_IGNORED | All the products from a request have already been published today on the channel
| 16 | FILTERS_IGNORED | All the products from a request have been ignored due to the filters specified channel

# Endpoints

## channels

### ➡️ `GET`

### 🧩 Params: `No Params`

### ❌ Errors: `No Errors`

### 🔎 Response:
A `JSON Array` made of `JSON Objects`, each one contains a user that you can access from the API using your token with the Channels that the user have connected to the BOT.

{
  "error": false,
  "result": [
      {
          "id": 12345, #main admin id
          "channels": [ #associated channels id
              1111,
              2222,
              ...,
              9999,
          ]
      },
      {
          ...
      },
      ...
      {
          ...
      }
  ]
}

## posts

### ➡️ `GET`

### 🧩 Params:

| Param | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| channel | long | Yes | The Telegram ID of the channel (starts with `-100`) |
| offset | integer | No | Start index (Default: `0`) |
| number | integer | No | Max. number of more recent posts to be returned (Default: `10`) |
| startTimestamp | integer | No | Retrieve only updates occurred after the specified Timestamp |
| type | string | No | `scheduled` to access Scheduled Posts, `published` to access Posts that were published on the Channel (Default: `published`) |

### ❌ Errors:

`MISSING_PARAM`, `INVALID_CHANNEL`

### 🔎 Response:
A `JSON Object` containing a `JSON Array` into the `result` Field. Each element of the `JSON Array` is a `Post Object`. If there are no posts for the query / filters set, an empty list will be returned.

{
  "error": false,
  "channel_name": "Channel Username or Full name (if private)",
  "result": [
      {
          "offer_id": "UUID", #unique single offer identifier. This identifies a product inside a post (different products on a Multiple Post will have a different offer_id)
          "post_id": "UUID", #unique post identifier, identifies the Telegram Post during all the cycles (draft, scheduled, published). Different products on the same Multiple Post will have an equal post_id
          "timestamp_created": 12345, #when the post was created by the admin (only for scheduled type, otherwise -1)
          "timestamp": 12346, #when the post was scheduled to be published or published,
          "code": "ABCD", #the ASIN of the product / unique code
          "link": "https://amazon.it/...", #full link of the product (with REF)
          "short_link", #short link of the product (if available)
          "domain": "amazon.it", #the domain of the link
          "channel_id": -100123456789,
          "title": "My Product",
          "edited_title": "Title Edited", #if the title was manually edited
          "price": "12,99",
          "price_numeric": 12.99,
          "old_price": "19,99", #can be -1 if not present
          "oldprice_numeric": 19.99,
          "currency": "€",
          "disc": "7,00", #discount (formatted)
          "discount_amount": 7.0, #discount (number)
          "perc": 35, #discount percentage (number)
          "category": "CategoryName", #CamelCase
          "category_original": "Category Name", #Full name
          "sub_categories": "#FirstSub #SecondSub #ThirdSub",
          "store": "amazon", #marketplace ("amazon", "ebay", "gearbest"...),
          "store_name": "Amazon", #marketplace display name ("Amazon", "eBay", "Gearbest"...)
          "telegram_id": 123, #telegram message id of the published post (only for published type)
          "image": "https://media.amazon.it/...", #full image link for the post
          "original_image": "", #may be blank. If not it contains the original product image (not modified by the BOT)
          "is_used": false, #true if the product is used (not new)
          "is_lowest_price": false, #true if the current price is the lowest price for the offer
          "lowest_price": 1299, #lowest price for the offer (needs to be divided by 100), -1 if unavailable 
          "average_price": 1439, #average price for the offer (needs to be divided by 100), -1 if unavailable 
          "average90_price": 1429, #average price for the offer in the last 90 days (needs to be divided by 100), -1 if unavailable 
          "maximum_price": 2299, #highest price for the offer (needs to be divided by 100), -1 if unavailable
          "is_lightning_deal": true, #true if the offer is a lightning deal on Amazon
          "lightning_deal_end": 12345678, #unix timestamp when the lightning deal will end, -1 if unavailable
          "lightning_deal_requested_percentage": 34, #contains the percentage of the requested lightning deal updated when the post was published / scheduled, -1 if unavailable
          "graph_link": "", #Keepa graph link (if available)
          "coupon": "ABCD", #coupon (may be blank)
          "description": "ABCD", #product description (may be blank)
          "is_expired": false, #true if the offer is flagged as "expired"
          "is_vpc": true, #true if the offer contains a VPC coupon (may also contain a classic coupon)
          "vpc_discount": 5.39, #the discount amount from the VPC coupon, -1 if not present
          "vpc_text": "Tick the checkbox on Amazon to get 20% extra discount!", #Box Coupon Text (may be blank)
          "checkout_discount": "8,99", #formatted amount for the Amazon cart discount
          "custom1": "Custom Text 1", # TAG {custom}
          "custom2": "Custom Text 2", # TAG {custom2}
          "custom3": "Custom Text 3", # TAG {custom3}
          "custom4": "Custom Text 4", # TAG {custom4}
          "custom5": "Custom Text 5", # TAG {custom5}
          "custom6": "Custom Text 6", # TAG {custom6}
          "post_type": "single", # "single", "multiple" or "custom"
          "sold_by": "Seller Name",
          "shipped_by": "Amazon or Seller Name",
          "reviews_total": 105, # total number of reviews
          "reviews_stars": 4.7, # review stars
          "feedback_seller_perc": 95%, # positive feedback percentage for eBay sellers
          "feedback_seller_count": 105, # total feedbacks for eBay sellers
          "formatted_date": "10/05/2025", #scheduled / published date
          "formatted_time": "15:54", #scheduled / published time
          "features": [ #product bullet points (may be empty, 0 elements)
              "feature1",
              "feature2",
              ...
              "featuren"
          ]
          "message": "...", #the message as printed on Telegram
          "message_no_link": "...", #the message as printed on Telegram but without the link line
          "tags": { #all the tags inside the Telegram message with the respective value
              "{minhist}": "Historical Minimum!",
              "...": "...", #other tags inside the post
              "{ship}": "Shipped and Sold By Amazon"
          }
      },
      {
          ...
      },
      ...
      {
          ...
      }
  ]
}

## expired

### ➡️ `GET`

### 🧩 Params:

| Param | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| channel | long | Yes | The Telegram ID of the channel (starts with `-100`) |
| offset | integer | No | Start index (Default: `0`) |
| number | integer | No | Max. number of more recent posts to be returned (Default: `10`) |
| startTimestamp | integer | No | Retrieve only updates occurred after the specified Timestamp |

### ❌ Errors:

`MISSING_PARAM`, `INVALID_CHANNEL`

### 🔎 Response:
The same `JSON Object` as `posts`, containing a `JSON Array` into the `result` Field. Each element of the `JSON Array` is a `Post Object` that is expired. If there are no expired posts for the query / filters set, an empty list will be returned.

## publish

### ➡️ `POST`

### 🧩 Params:

| Param | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| channel | long | Yes | The Telegram ID of the channel (starts with `-100`) |

### 🧱 Body (JSON):
| Field | Type | Required | Description |
| -------- | -------- | -------- | -------- |
| urls | string | Yes | The URL of the product to be published (_single post_) or a comma separated list of URLs (_multiple post_)<br><br>_The REF will be applied automatically on the link if it's configured on BOT_ |
| mode | string | Yes | Can be one of:<br>`now`: publish the post immediately<br>`first`: add the post as first in the queue*<br>`last`: add the post as last in the queue*<br>`lastmanual`: add the post right after the last manual in the queue*<br>`schedule`: schedule the post for the date / time specified in the `date` parameter<br>`scheduleslots`: schedule the post in the next available slot configured in the BOT<br><br>*_these requires auto posts license on channel, otherwise a `NO_AUTOPOSTS` error will be returned_ |
| date | string | Maybe | required for the `schedule` mode, in the format `yyyy-MM-dd HH:mm`. If invalid the error `INVALID_DATE` is returned. |
| coupon | string | No | if specified it's added as "Coupon Code" in the post |
| price | double | No | if specified it's added as price in the post |
| ref | boolean | No | if `false` the link specified in the `url` will be used without it being modified (_the specified link should already contain the REF_). (default: `true`) |
| custom1 | string | No | set's the {custom} TAG value* |
| custom2 | string | No | set's the {custom2} TAG value* |
| custom3 | string | No | set's the {custom3} TAG value* |
| custom4 | string | No | set's the {custom4} TAG value* |
| custom5 | string | No | set's the {custom5} TAG value* |
| custom6 | string | No | set's the {custom6} TAG value* |
| returnproducts | boolean | No | if `true` each Post Object is returned in the `products` field (default: `false`)) |
| ignore_duplicates | boolean | No | if `true` each product is checked to ensure it has not already been published by the BOT during the day. For multiple posts, duplicate products are removed, and the post is published with the remaining products. (default: `false`) |
| filter_minpercentage | integer | No | if set between 1 and 100, it checks if the specified products have a percentage discount above or equal to the amount set. If not the `FILTERS_IGNORED` error is returned. For multiple posts, duplicate products are removed, and the post is published with the remaining products. (default: `0`) |
| facebook | boolean | No | if `true` the Post will be published on Facebook if it's configured on BOT (default: `false`)) |
| whatsapp | boolean | No | if `true` the Post will be published on WhatsApp if it's configured on BOT (default: `false`)) |
| discord | boolean | No | if `true` the Post will be published on Discord if it's configured on BOT (default: `false`)) |

_\* custom TAGs specified on Multiple Posts will be only applied to the first post_

### ❌ Errors:
`MISSING_PARAM`, `INVALID_CHANNEL`, `NO_AUTOPOSTS`, `INVALID_REF`, `QUEUE_LOADING`, `INVALID_DATE`, `DUPLICATES_IGNORED`, `FILTERS_IGNORED`

### 🔎 Response:
A `JSON Object` containing a `JSON Array` into the `result` Field. Each element of the `JSON Array` is a `Post Object`. If there are no posts for the query / filters set, an empty list will be returned.

{
    "error": false,
    "is_multiple": true, # true if the post is a Multiple Post
    "post_id": "66221af2-58fd-40aa-bf77-7f0342266fc7",
    "scheduled_timestamp": 1721574360000, # if scheduled, the unix timestamp in milliseconds
    "products": [ # array of Post objects (one element for single posts, each product on multiple posts)
        {
            ...
        },
        {
            ...
        }
    ]
}

## amazoncategories

### ➡️ `GET`

### 🧩 Params: NO PARAMS

### ❌ Errors: `No Errors`

### 🔎 Response:
A `JSON Object` containing two `JSON Arrays`: one for Amazon categories and one for Amazon sub-categories.

{
  "error": false,
  "categories": [
      {
        "412603031": {"domainId":8,
                      "catId":412603031,
                      "name":"Videogiochi",
                      "contextFreeName":"Videogiochi",
                      "children":[412604031,
                                  427506031,
                                  494935031],
                      "parent":0,
                      "highestRank":4002579,
                      "lowestRank":1,
                      "productCount":308466
                      },
          ...
      },
      {
          ...
      },
      ...
      {
          ...
      }
  ],
  "subcategories": [
      {
          ...
      },
      {
          ...
      },
      ...
      {
          ...
      }
      
  ]
}