Как обновить токен для telephony.externalcall.finish в Bitrix24

При получении ошибки ‘expired_token’ при вызове метода telephony.externalcall.finish в Bitrix24 необходимо обновить авторизационный токен с помощью refresh_token. Для этого нужно отправить POST-запрос на специальный endpoint с параметрами grant_type=refresh_token, refresh_token, client_id и client_secret, что вернёт новый access_token и refresh_token.

Содержание

• Причина ошибки expired_token
• Как обновить токен
• Пример обновления токена
• Автоматическое обновление в коде
• Рекомендации по обработке

Причина ошибки expired_token

Ошибка expired_token возникает потому, что access token в Bitrix24 имеет ограниченное время жизни. Как указано в документации Bitrix24, access token:

• Действует всего 1 час (3600 секунд)
• После истечения срока становится недействительным
• Требует обновления с помощью refresh token

В вашем случае при вызове telephony.externalcall.finish система определяет, что предоставленный access token истёк, и отклоняет запрос с соответствующей ошибкой.

Как обновить токен

Для обновления токена используется механизм OAuth 2.0 с refresh token. Процесс включает следующие шаги:

1. Сохраните refresh token - при первоначальной авторизации Bitrix24 возвращает вместе с access token также refresh token, который нужно сохранить

2. Отправьте запрос на обновление - используйте специальный endpoint с необходимыми параметрами

3. Обработайте ответ - в случае успеха вы получите новый access token и refresh token

Важно: Refresh token имеет более длительный срок действия - 28 дней или до отзыва, как указано в источниках Bitrix24.

Пример обновления токена

URL для обновления токена

https://[ваш_портал].bitrix24.com/oauth/token/

Параметры запроса

Необходимо отправить POST-запрос со следующими параметрами:

Пример запроса

curl -X POST "https://yourcompany.bitrix24.com/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=ваш_refresh_token" \
  -d "client_id=ваш_client_id" \
  -d "client_secret=ваш_client_secret"

Пример ответа

{
  "access_token": "новый_access_token",
  "refresh_token": "новый_refresh_token",
  "expires_in": 3600,
  "domain": "yourcompany.bitrix24.com",
  "server_endpoint": "https://oauth.bitrix.info/rest/",
  "client_endpoint": "https://yourcompany.bitrix24.com/rest/",
  "member_id": "ваш_member_id",
  "application_token": "ваш_application_token"
}

Как показано в примерах Bedaya, этот запрос возвращает ту же структуру, что и первоначальный запрос на получение токенов.

Автоматическое обновление в коде

Обработка ошибок в вызовах API

Рекомендуется реализовать обработку ошибок expired_token с автоматическим обновлением токена:

import requests

class Bitrix24API:
    def __init__(self, portal, client_id, client_secret, refresh_token):
        self.portal = portal
        self.client_id = client_id
        self.client_secret = client_secret
        self.refresh_token = refresh_token
        self.access_token = None
        self.token_expires = 0
        
    def refresh_access_token(self):
        """Обновляет access token с помощью refresh token"""
        url = f"https://{self.portal}.bitrix24.com/oauth/token/"
        data = {
            'grant_type': 'refresh_token',
            'refresh_token': self.refresh_token,
            'client_id': self.client_id,
            'client_secret': self.client_secret
        }
        
        response = requests.post(url, data=data)
        if response.status_code == 200:
            token_data = response.json()
            self.access_token = token_data['access_token']
            self.refresh_token = token_data['refresh_token']  # Обновляем refresh token
            self.token_expires = time.time() + token_data['expires_in']
            return True
        return False
    
    def make_api_call(self, method, params=None):
        """Выполняет вызов API с автоматическим обновлением токена"""
        if not self.access_token or time.time() >= self.token_expires:
            if not self.refresh_access_token():
                raise Exception("Не удалось обновить токен")
        
        url = f"https://{self.portal}.bitrix24.com/rest/{method}.json"
        headers = {'Content-Type': 'application/json'}
        params = params or {}
        params['auth'] = self.access_token
        
        response = requests.get(url, headers=headers, params=params)
        result = response.json()
        
        if result.get('error') == 'expired_token':
            # Обновляем токен и повторяем вызов
            if self.refresh_access_token():
                params['auth'] = self.access_token
                response = requests.get(url, headers=headers, params=params)
                result = response.json()
        
        return result

Использование для telephony.externalcall.finish

# Инициализация API
bitrix = Bitrix24API(
    portal="yourcompany",
    client_id="your_client_id", 
    client_secret="your_client_secret",
    refresh_token="your_refresh_token"
)

# Вызов метода telephony.externalcall.finish
try:
    result = bitrix.make_api_call("telephony.externalcall.finish", {
        'USER_ID': 1,
        'CALL_ID': 'call123',
        'TIME': 120,
        'DISPOSITION': 'answered'
    })
    print("Результат:", result)
except Exception as e:
    print("Ошибка:", e)

Как видно из примеров библиотек pybitrix24, современные клиенты Bitrix24 API реализуют автоматическое обновление токенов.

Рекомендации по обработке

1. Хранение токенов

• Сохраняйте refresh token в безопасном месте (не в коде)
• Регулярно обновляйте access token перед его истечением
• Обрабатывайте ошибки expired_token в логике вашего приложения

2. Периодичность обновления

• Обновляйте токены proactively - за 5-10 минут до истечения срока
• Мониторьте время жизни токенов в системе
• Реализуйте повторные попытки при ошибках аутентификации

3. Безопасность

• Используйте HTTPS для всех запросов к Bitrix24 API
• Храните секретные ключи в переменных окружения или защищённых хранилищах
• Ограничивайте scope запрашиваемых разрешений

4. Логирование

• Фиксируйте моменты обновления токенов
• Логируйте ошибки аутентификации для анализа
• Мониторьте оставшееся время действия refresh token

Как отмечено в документации, правильное использование refresh_token позволяет приложению получать доступ к REST API без участия пользователя, что критически важно для автоматизированных систем, таких как интеграция с Астериск.

Источники

1. Refreshing Authorization For External Applications - Bitrix24
2. Examples - Bitrix24 OAuth
3. OAuth 2.0 automatic extension - Bitrix24 Training
4. Access the Bitrix24 API - Bedaya
5. GitHub - pybitrix24 refresh tokens example
6. GitHub - 2BAD/bitrix client implementation

Заключение

• Ошибка expired_token означает, что access token истёк и требует обновления через refresh token
• Обновление токена выполняется POST-запросом на /oauth/token/ с параметрами grant_type=refresh_token, refresh_token, client_id и client_secret
• Автоматизируйте процесс обновления токенов в коде для бесперебойной работы с API
• Храните refresh token безопасно и обновляйте его при получении новых значений
• Реализуйте обработку ошибок expired_token с повторными попытками после обновления токена

Для интеграции с Астериск рекомендуется добавить логику автоматического обновления токенов в обработчик событий, чтобы избежать прерывания вызовов из-за истечения срока действия авторизационных данных.