Метод answerShippingQuery

Описание

Если вы отправили счёт с запросом адреса доставки и был указан параметр is_flexible, Bot API отправит боту Update с полем shipping_query. Используйте этот метод для ответа на запросы о доставке. При успешном выполнении возвращается True.

Параметр	Тип	Обязательный	Описание
shipping_query_id	String	Да	Уникальный идентификатор запроса, на который нужно ответить
ok	Boolean	Да	Укажите True, если доставка по указанному адресу возможна, и False, если есть какие-либо проблемы (например, если доставка по указанному адресу невозможна)
shipping_options	Array of ShippingOption	Опционально	Обязателен, если ok равен True. JSON-сериализованный массив доступных вариантов доставки.
error_message	String	Опционально	Обязателен, если ok равен False. Сообщение об ошибке в удобочитаемой форме, объясняющее, почему невозможно выполнить заказ (например, «Извините, доставка по указанному адресу недоступна»). Telegram покажет это сообщение пользователю.

Примеры

php

<?php

// Токен вашего бота
$botToken = 'YOUR_BOT_TOKEN';

// ID запроса на доставку из объекта shipping_query
$shippingQueryId = 'UNIQUE_SHIPPING_QUERY_ID';

// Вариант 1: Подтверждение возможности доставки с вариантами доставки
$url = "https://api.telegram.org/bot{$botToken}/answerShippingQuery";

// Создаем варианты доставки
$shippingOptions = [
    [
        'id' => 'express',
        'title' => 'Экспресс доставка',
        'prices' => [
            [
                'label' => 'Стоимость доставки',
                'amount' => 50000 // 500.00 в минимальных единицах валюты
            ]
        ]
    ],
    [
        'id' => 'standard',
        'title' => 'Стандартная доставка',
        'prices' => [
            [
                'label' => 'Стоимость доставки',
                'amount' => 25000 // 250.00 в минимальных единицах валюты
            ]
        ]
    ]
];

// Данные для успешного ответа
$dataSuccess = [
    'shipping_query_id' => $shippingQueryId,
    'ok' => true,
    'shipping_options' => json_encode($shippingOptions)
];

// Отправка успешного ответа
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataSuccess);
$response = curl_exec($ch);
curl_close($ch);

// Обработка ответа
$result = json_decode($response, true);
if ($result['ok']) {
    echo "Варианты доставки успешно отправлены\n";
} else {
    echo "Ошибка: " . $result['description'] . "\n";
}

// Вариант 2: Отказ в доставке с сообщением об ошибке
$dataError = [
    'shipping_query_id' => $shippingQueryId,
    'ok' => false,
    'error_message' => 'Извините, доставка в указанный регион временно недоступна'
];

// Отправка ответа об ошибке
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $dataError);
$response = curl_exec($ch);
curl_close($ch);

// Обработка ответа
$result = json_decode($response, true);
if ($result['ok']) {
    echo "Сообщение об ошибке доставки успешно отправлено\n";
} else {
    echo "Ошибка: " . $result['description'] . "\n";
}

// Пример использования в обработчике webhook
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $update = json_decode(file_get_contents('php://input'), true);
    
    if (isset($update['shipping_query'])) {
        $shippingQuery = $update['shipping_query'];
        $queryId = $shippingQuery['id'];
        
        // Проверяем адрес доставки
        $address = $shippingQuery['shipping_address'];
        $countryCode = $address['country_code'];
        
        if ($countryCode === 'RU') {
            // Доступные варианты доставки для России
            $options = [
                [
                    'id' => 'ru_standard',
                    'title' => 'Доставка по России (5-7 дней)',
                    'prices' => [
                        ['label' => 'Доставка', 'amount' => 30000]
                    ]
                ]
            ];
            
            $responseData = [
                'shipping_query_id' => $queryId,
                'ok' => true,
                'shipping_options' => json_encode($options)
            ];
        } else {
            // Отказ для других стран
            $responseData = [
                'shipping_query_id' => $queryId,
                'ok' => false,
                'error_message' => 'Доставка в вашу страну временно не осуществляется'
            ];
        }
        
        // Отправляем ответ
        $ch = curl_init("https://api.telegram.org/bot{$botToken}/answerShippingQuery");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $responseData);
        curl_exec($ch);
        curl_close($ch);
    }
}

?>

python

import requests

def answer_shipping_query(bot_token, shipping_query_id, ok, shipping_options=None, error_message=None):
    """
    Ответ на запрос о доставке.
    
    :param bot_token: Токен бота
    :param shipping_query_id: Уникальный идентификатор запроса
    :param ok: True если доставка возможна, False если есть проблемы
    :param shipping_options: Список вариантов доставки (требуется если ok=True)
    :param error_message: Сообщение об ошибке (требуется если ok=False)
    :return: Результат запроса
    """
    
    url = f"https://api.telegram.org/bot{bot_token}/answerShippingQuery"
    
    payload = {
        "shipping_query_id": shipping_query_id,
        "ok": ok
    }
    
    if ok and shipping_options:
        payload["shipping_options"] = shipping_options
    elif not ok and error_message:
        payload["error_message"] = error_message
    
    response = requests.post(url, json=payload)
    return response.json()

# Пример использования:
if __name__ == "__main__":
    BOT_TOKEN = "YOUR_BOT_TOKEN"
    
    # Пример 1: Успешный ответ с вариантами доставки
    shipping_options = [
        {
            "id": "standard",
            "title": "Standard Shipping",
            "prices": [
                {"label": "Delivery", "amount": 500}
            ]
        },
        {
            "id": "express",
            "title": "Express Shipping",
            "prices": [
                {"label": "Delivery", "amount": 1000}
            ]
        }
    ]
    
    result = answer_shipping_query(
        bot_token=BOT_TOKEN,
        shipping_query_id="UNIQUE_QUERY_ID",
        ok=True,
        shipping_options=shipping_options
    )
    print(f"Success response: {result}")
    
    # Пример 2: Ответ с ошибкой
    result = answer_shipping_query(
        bot_token=BOT_TOKEN,
        shipping_query_id="ANOTHER_QUERY_ID",
        ok=False,
        error_message="Sorry, delivery to your address is not available"
    )
    print(f"Error response: {result}")

История изменений

API 3.0. Добавлен метод answerShippingQuery

Дополнительно

Update - Объект Update представляет входящее событие в Telegram Bot API, содержащее информацию о сообщениях, запросах, изменениях статуса участников и других действиях, связанных с ботом.
ShippingOption - Объект, описывающий один вариант доставки с его идентификатором, названием и составом цены.