API
Для работы с апи вам потребуется сгенерировать токен. Перейдите в настройки вашего бота, выберите вкладку "Интеграция", пролистайте вниз до раздела HTTP и нажмите на кнопку Generate.
Вы получите токен, по которому вы сможете сделать запрос на логин.
Вы можете настроить автоматическую отправку информации о новых заказах на ваш сервер. Для этого включите переключатель HTTP webhook enabled и укажите в поле New order webhook url куда отсылать такую информацию.
Поле New order webhook query string предназначено для передачи ваших аргументов в запросе как query params.
Запрос который придет на ваш сервер имеет следующую структуру:

POST https://your-domain.com/handle-order
Request JSON payload: {contact : {...}, order: {...}}

contact и order это структуры с данными о заказе и сделавшем его пользователе соответственно, пример которых приведен ниже.
REST API entry point
https://bot.bot4shop.com/manager/api/v1/
Login method
POST https://bot.bot4shop.com/manager/api/v1/auth/login?type=api_token
//Request json payload
{
  "botId": "yours-bot-id",
  "apiToken": "api-token"
}

//Response
{
  "botId": "yours-bot-id",
  "token": "token-to-use-in-requests"
}
Auth
Every request should consist api_token=token-to-use-in-requests as query param
REST API
API path: https://bot.bot4shop.com/manager/api/v1/bot/:botId/:entity/:id?

General HTTP methods usage

  • GET - query for entities
  • POST - insert entity
  • PUT - change entity
  • DELETE - delete entity

General query params

  • start - count of entries in db to skip
  • rows - max count of entries to return
  • sort - array of arrays of sorting param. [["name", 1], ["price", -1]] etc.

Entities

  • config
  • products
  • orders
  • tags
  • contacts

Total count of entities is in Content-Total-Count header in response to any request.
Change entities
You can pass custom field path to change it in object. For example, base object:
{
  _id: "myid"
  name: "amacoolobj",
  details: {
    age: 30
  }
}
You can change age field by sending PUT request with next payload:
{ "details.age": 40 }
Google Sheets
You can trigger import and export of data from google sheets by api.
You can read how to connect sheets for your bot in general in this article https://www.bot4shop.com/help/gsheets.

It's highly recommended not to run several import/export at once because of google sheets read/write quota limit.

Import

POST /gsheets/:entity-name/import

entity-name can be one of next values:
  • promocodes
  • products
  • tags
  • texts

Query params

  • removeOldData - pass true to delete all entity data
  • updateExisting - pass true to update entities with equal ids
  • updateTagsByProducts - can be used with entity-name=products. If true - creates new tags by product.tags field.
Export

POST /gsheets/:entity-name/export

entity-name can be one of next values:
  • promocodes
  • products
  • tags
  • texts
  • orders
  • contacts
Entities examples
Config
{
    "_id" : "nice-case",
    "apiKey" : "api-key",
    "defaultImageUrl" : "https://storage.googleapis.com/eb-general/paint.jpg",
    "currency" : "UAH",
    "country" : "UZ",
    "lang" : "ru",
    "useCurrencyCode" : false,
    "defaultPlan" : "0-9-9-29",
    "products" : {
        "sort" : [ 
            [ 
                "price", 
                1
            ], 
            [ 
                "name", 
                -1
            ], 
            [ 
                "createDate", 
                -1
            ]
        ]
    },
    "integration" : {
        "http" : {
            "enabled" : true,
            "newOrderUrl" : "",
            "query" : "&token=secret"
        }
    },
    "contacts" : {
        "error" : [ 
            "-358541008"
        ],
        "support" : [ 
            "-358541008"
        ]
    },
    "orderStatuses" : [ 
        {
            "id" : 1585145089501.0,
            "label" : "Открыт"
        }, 
        {
            "id" : 1585146406557.0,
            "label" : "Новый статус"
        }, 
        {
            "id" : 1585158567171.0,
            "label" : "Ожидает упаковки"
        }, 
        {
            "id" : 1585158567730.0,
            "label" : "Отправлен"
        }, 
        {
            "id" : 1585158740301.0,
            "label" : "Закрыт"
        }
    ],
    "menuConfig" : {
        "type" : "buttons",
        "hideEmptySubMenu" : true,
        "paginationSize" : 2,
        "compactPaginationSize" : 10,
        "alwaysShowAllProductOptions" : false,
        "buttonsPerRow" : 2,
        "showAllProductsByDefaultInInline" : true,
        "hidePriceInCompactMenu" : true,
        "categoryColumnsCount" : 1
    },
    "promocodesEnabled" : true,
    "captionConfig" : {
        "maxlength" : 4000,
        "template" : [ 
            "*$name$*", 
            "$description$", 
            "[.]($imageUrl$)"
        ]
    },
    "prices" : {
        "maxDiscount" : {
            "value" : 50,
            "type" : "F"
        }
    },
    "checkoutSteps" : [ 
        {
            "name" : "Выбор пути",
            "label" : "Выбор пути",
            "type" : "option-question",
            "message" : "Хей хей, выбери первое - попадешь на вопрос 2, выбери второе - попадешь на вопрос 3",
            "answerOptions" : [ 
                {
                    "label" : "К шагу 2",
                    "name" : "К шагу 2",
                    "price" : 0,
                    "enablePayment" : false,
                    "nextStepName" : "Шаг 2"
                }, 
                {
                    "label" : "К шагу 3",
                    "name" : "К шагу 3",
                    "price" : 0,
                    "enablePayment" : false,
                    "nextStepName" : "Шаг 3"
                }, 
                {
                    "label" : "К завершению заказа",
                    "name" : "К завершению заказа",
                    "price" : 0,
                    "enablePayment" : false,
                    "nextStepName" : "confirm"
                }, 
                {
                    "label" : "К тексту",
                    "name" : "К тексту",
                    "price" : 0,
                    "enablePayment" : false,
                    "nextStepName" : "Адрес доставки"
                }
            ]
        }, 
        {
            "name" : "Шаг 2",
            "label" : "Шаг 2",
            "type" : "location-request",
            "message" : "Запрос местоположения",
            "allowText" : true,
            "nextStepName" : "confirm"
        }, 
        {
            "name" : "Шаг 3",
            "label" : "Шаг 3",
            "type" : "contact-request",
            "message" : "Шаг 3: Напиши что-нибудь",
            "nextStepName" : "confirm"
        }, 
        {
            "name" : "Адрес доставки",
            "label" : "Адрес доставки",
            "type" : "open-question",
            "message" : "Напишите куда доставить, или выберите ранее введенный адрес:",
            "suggestAnswer" : true
        }, 
        {
            "name" : "123123",
            "label" : "123123",
            "type" : "open-question",
            "message" : "",
            "suggestAnswer" : true
        }, 
        {
            "name" : "confirm",
            "type" : "final-confirm",
            "hidden" : true
        }
    ],
    "top_commands" : [ 
        [ 
            {
                "name" : "search",
                "label" : "Поиск",
                "message" : "Что Вы ищете?",
                "_id" : "0"
            }, 
            {
                "name" : "orders",
                "label" : "Заказы",
                "message" : "Ваши заказы: 1",
                "_id" : "1"
            }
        ], 
        [ 
            {
                "_id" : "2",
                "message" : "Корзина",
                "label" : "Корзина",
                "name" : "cart"
            }, 
            {
                "_id" : "3",
                "message" : "Каталог",
                "label" : "Каталог",
                "name" : "menu"
            }
        ], 
        [ 
            {
                "_id" : "4",
                "message" : "support",
                "label" : "support",
                "name" : "support",
                "callback_enabled" : true
            }, 
            {
                "name" : "version",
                "label" : "/version",
                "display" : false
            }
        ], 
        [ 
            {
                "name" : "command",
                "label" : "/command",
                "display" : false
            }, 
            {
                "name" : "start",
                "label" : "/start",
                "message" : "Откройте меню, чтобы посмотреть, что у нас есть",
                "parse_mode" : "Markdown",
                "display" : false
            }
        ]
    ],
    "checkout" : {
        "payment" : {
            "payInBot" : false,
            "paymentToken" : "",
            "formConfig" : {
                "need_name" : true
            }
        },
        "configs" : {
            "telegram" : {
                "ordersChatId" : [ 
                    -351845364, 
                    254528172
                ]
            }
        },
        "type" : "telegram"
    },
    "phoneExample" : "+99999",
    "registeredDate" : 1574932084161.0,
    "operatorReceiptConfig" : {
        "showTags" : true
    },
    "tokens" : [ 
        "api-token-hash", 
    ],
    "admins" : [ 
        254528172
    ],
    "menu" : {
        "subMenu" : [ 
            {
                "_id" : "5e791684ae2f83567a981526",
                "label" : "Платья",
                "name" : "261",
                "tag_id" : "261",
                "parents" : [],
                "tags" : [ 
                    "261"
                ]
            }, 
            {
                "_id" : "5e791684ae2f83567a981528",
                "label" : "Куртки",
                "name" : "391",
                "tag_id" : "391",
                "parents" : [],
                "subMenu" : [ 
                    {
                        "_id" : "5e791684ae2f83567a981527",
                        "label" : "Мужская одежда",
                        "name" : "3",
                        "tag_id" : "3",
                        "parents" : [ 
                            "391"
                        ],
                        "tags" : [ 
                            "3"
                        ]
                    }
                ],
                "tags" : [ 
                    "391"
                ]
            }, 
            {
                "_id" : "5e791aeb14f6325fa92da5c4",
                "label" : "Kek",
                "name" : "Kek",
                "tag_id" : "Kek",
                "tags" : [ 
                    "Kek"
                ]
            }, 
            {
                "_id" : "5e791aeb14f6325fa92da5c5",
                "label" : "Усе",
                "name" : "Усе",
                "tag_id" : "Усе",
                "tags" : [ 
                    "Усе"
                ]
            }, 
            {
                "_id" : "5e791aeb14f6325fa92da5c6",
                "label" : "Футболки",
                "name" : "Футболки",
                "tag_id" : "Футболки",
                "tags" : [ 
                    "Футболки"
                ]
            }
        ]
    },
    "_info" : {
        "id" : 786930858,
        "is_bot" : true,
        "first_name" : "B4S bot",
        "username" : "krabo_bot",
        "can_join_groups" : true,
        "can_read_all_group_messages" : false,
        "supports_inline_queries" : true
    },
    "_startMessage" : "Откройте меню, чтобы посмотреть, что у нас есть",
    "_stats" : {
        "productCount" : 4,
        "promocodeCount" : 8,
        "mailingCount" : 18,
        "orderCount" : 5,
        "contactCount" : 4
    }
}
Product
{
    "_id" : "5e791ff2600578604e590922",
    "name" : "Футболка з принтом 'SOUND GUY'",
    "description" : "Унісекс. 95% бавовна, 5% еластан.",
    "price" : 450,
    "tags" : [ 
        1584996338009.0
    ],
    "imageUrl" : "https://storage.googleapis.com/eb-general/sound-t-shirt.jpeg",
    "product_id" : "3",
    "options" : [ 
        {
            "name" : "XS/S",
            "price" : 450,
            "external_product_option_id" : 0
        }, 
        {
            "name" : "S/M",
            "price" : 460,
            "external_product_option_id" : 1
        }, 
        {
            "name" : "M/L",
            "price" : 472,
            "external_product_option_id" : 2
        }, 
        {
            "name" : "L/XL",
            "price" : 480,
            "external_product_option_id" : 3
        }, 
        {
            "name" : "XL/XXL",
            "price" : 490,
            "external_product_option_id" : 4
        }
    ],
    "createDate" : 1584996338009.0,
    "updateDate" : 1584996338009.0
}
Order
{
    "_id" : "5e7bb3449207a96d7567c4ec",
    "orderId" : "25-03-2020-13",
    "status" : 1585145089501.0,
    "orderInfo" : {
        "Выбор пути" : {
            "label" : "К адресу доставки",
            "name" : "К адресу доставки",
            "price" : 0,
            "enablePayment" : false,
            "nextStepName" : "Адрес доставки"
        },
        "Адрес доставки" : "Ко мне домой"
    },
    "chatId" : 254528172,
    "items" : [ 
        {
            "productId" : "2",
            "quantities" : {
                "0" : 1,
                "1" : 1
            },
            "details" : {
                "_id" : "5e791ff2600578604e590923",
                "name" : "Футболка 'Supreme Bart'",
                "description" : "Унісекс. 95% бавовна, 5% еластан.",
                "price" : 450,
                "tags" : [ 
                    "Футболки"
                ],
                "imageUrl" : "https://storage.googleapis.com/eb-general/supreme-t-shirt.jpeg",
                "product_id" : "2",
                "options" : [ 
                    {
                        "name" : "XS/S",
                        "price" : 450,
                        "external_product_option_id" : 0
                    }, 
                    {
                        "name" : "S/M",
                        "price" : 460,
                        "external_product_option_id" : 1
                    }, 
                    {
                        "name" : "M/L",
                        "price" : 472,
                        "external_product_option_id" : 2
                    }, 
                    {
                        "name" : "L/XL",
                        "price" : 480,
                        "external_product_option_id" : 3
                    }, 
                    {
                        "name" : "XL/XXL",
                        "price" : 490,
                        "external_product_option_id" : 4
                    }
                ],
                "createDate" : 1584996338061.0,
                "updateDate" : 1584996338061.0
            }
        }, 
        {
            "productId" : "1",
            "quantities" : {
                "0" : 1
            },
            "details" : {
                "_id" : "5e791ff2600578604e590924",
                "name" : "Футболка біла",
                "description" : "Унісекс. 95% бавовна, 5% еластан.",
                "price" : 450,
                "tags" : [ 
                    "3"
                ],
                "imageUrl" : "https://storage.googleapis.com/eb-general/white-t-shirt.jpeg",
                "product_id" : "1",
                "options" : [ 
                    {
                        "name" : "XS/S",
                        "price" : 450,
                        "external_product_option_id" : 0
                    }, 
                    {
                        "name" : "S/M",
                        "price" : 460,
                        "external_product_option_id" : 1
                    }, 
                    {
                        "name" : "M/L",
                        "price" : 472,
                        "external_product_option_id" : 2
                    }, 
                    {
                        "name" : "L/XL",
                        "price" : 480,
                        "external_product_option_id" : 3
                    }, 
                    {
                        "name" : "XL/XXL",
                        "price" : 490,
                        "external_product_option_id" : 4
                    }
                ],
                "createDate" : 1584996338113.0,
                "updateDate" : 1584996338113.0
            }
        }
    ],
    "promocode" : {
        "_id" : "5e39b2815d03bd025bac45a4",
        "code" : "test",
        "type" : "P",
        "discount" : 10,
        "promocode_id" : "1580839553312",
        "products" : [],
        "categories" : []
    },
    "closedTimestamp" : 1585166925487.0
}
Tag
{
    "_id" : "5e791aeb14f6325fa92da5c6",
    "label" : "Футболки",
    "name" : "Футболки",
    "tag_id" : "127",
    "parents" : [ "391"]
}
Contact
{
    "_id" : "5e67f0ab6306a2440c2a2f8b",
    "chat_id" : 254528172,
    "chat_title" : null,
    "chat_type" : "private",
    "first_name" : "Fyodor",
    "language_code" : "ru",
    "user_id" : 254528172,
    "username" : "username",
    "phone_number" : "+380999999999"
}
Если остались вопросы или есть идеи как улучшить статью, пишите нашему боту - @bot4shop_support_bot.

Описание большей части настроек телеграм магазина