Как подключить GigaChat к n8n

GigaChat подключается к n8n двумя HTTP-запросами. Первый получает токен доступа, второй отправляет текст модели. Ниже настройка по шагам, включая сертификат, без которого запросы не проходят.

Что понадобится

• n8n на своём сервере, установленный по нашей инструкции или похожим способом через Docker Compose.
• Проект GigaChat API в личном кабинете Studio на developers.sber.ru.
• Доступ к серверу по SSH.

С 1 сентября 2026 года Сбер предлагает новым корпоративным клиентам оплачивать модели на платформе Cloud.ru. Там свои ключи и адреса API, их уточните в документации Cloud.ru. Эта инструкция описывает прямое подключение к GigaChat API.

Шаг 1. Получить ключ авторизации

1. В личном кабинете Studio откройте проект GigaChat API.
2. В разделе «Настройки API» нажмите «Получить ключ».
3. Сохраните Authorization Key, Client ID и Client Secret. Ключ и Client Secret показываются один раз.

Ключ авторизации нужен только для получения токена. Это строка в Base64, собранная из Client ID и Client Secret. Готовый ключ удобнее скопировать из кабинета.

При запросе токена вы указываете версию API в параметре scope:

Шаг 2. Установить сертификат Минцифры

Серверы GigaChat используют сертификаты Национального удостоверяющего центра Минцифры. Их цепочка заканчивается корневым сертификатом Russian Trusted Root CA, которого нет в стандартном наборе доверенных сертификатов. Поэтому без настройки n8n получит ошибку вида self-signed certificate in certificate chain или unable to get local issuer certificate.

В узле HTTP Request есть опция Ignore SSL Issues, но с ней n8n перестаёт проверять, с тем ли сервером он соединяется. Надёжнее добавить корневой сертификат. n8n умеет доверять своим сертификатам начиная с версии 1.42. Их кладут в папку и подключают к контейнеру по пути /opt/custom-certificates.

cd ~/n8n
mkdir -p pki
curl -o pki/russian_trusted_root_ca.crt https://gu-st.ru/content/lending/russian_trusted_root_ca_pem.crt
sudo chown -R 1000:1000 pki

Ссылку на сертификат публикует Сбер в документации GigaChat. Сам сертификат также можно скачать на Госуслугах.

Добавьте папку в сервис n8n в файле docker-compose.yml:

    volumes:
      - ./n8n_data:/home/node/.n8n
      - ./pki:/opt/custom-certificates

Перезапустите контейнер командой docker compose up -d. В логе n8n должна появиться строка Trusting custom certificates from /opt/custom-certificates.

Проверить ключ и сертификат можно прямо с сервера:

curl -X POST 'https://ngw.devices.sberbank.ru:9443/api/v2/oauth' \
  --cacert ~/n8n/pki/russian_trusted_root_ca.crt \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json' \
  -H "RqUID: $(cat /proc/sys/kernel/random/uuid)" \
  -H 'Authorization: Basic ВАШ_КЛЮЧ_АВТОРИЗАЦИИ' \
  --data-urlencode 'scope=GIGACHAT_API_CORP'

Шаг 3. Получить токен в сценарии

Сценарий начинается с получения токена, затем идут узлы, которые забирают тексты для обработки.

1. Узел Crypto: действие Generate, тип UUID, поле rquid. Это идентификатор запроса, который GigaChat требует в заголовке RqUID в формате uuid4.
2. Узел HTTP Request, назовите его «Токен GigaChat»:
   • Method: POST
   • URL: https://ngw.devices.sberbank.ru:9443/api/v2/oauth
   • Authentication: Generic Credential Type → Header Auth. В доступе укажите Name Authorization и Value Basic ВАШ_КЛЮЧ_АВТОРИЗАЦИИ.
   • Send Headers: RqUID со значением {{ $json.rquid }} и Accept со значением application/json.
   • Send Body: Form URLencoded, параметр scope со значением GIGACHAT_API_CORP или вашим.

Ответ выглядит так:

{
  "access_token": "eyJhbGci...",
  "expires_at": 1739784663483
}

Поле expires_at содержит время окончания действия токена в миллисекундах. Токен живёт 30 минут. Если сценарий обрабатывает данные дольше, запрашивайте токен заново внутри цикла.

Шаг 4. Отправить запрос к модели

Узел HTTP Request:

• Method: POST
• URL: https://api.giga.chat/v1/chat/completions
• Send Headers: Authorization со значением Bearer {{ $('Токен GigaChat').first().json.access_token }}
• Send Body: JSON

{
  "model": "GigaChat-2",
  "messages": [
    {
      "role": "system",
      "content": "Ты помощник отдела продаж. Кратко перескажи обращение клиента и определи его тему."
    },
    {
      "role": "user",
      "content": {{ JSON.stringify($json.text) }}
    }
  ],
  "temperature": 0.3,
  "max_tokens": 500
}

Сообщение с ролью system должно быть одно и стоять первым, иначе API вернёт ошибку 422. Для модели укажите GigaChat-2 (Lite), GigaChat-2-Pro или GigaChat-2-Max. Актуальный список моделей есть в документации.

Базовый адрес API в текущей документации https://api.giga.chat/v1. В старых примерах встречается https://gigachat.devices.sberbank.ru/api/v1. Оба адреса используют сертификат Минцифры.

Шаг 5. Разобрать ответ

Текст ответа лежит в поле:

{{ $json.choices[0].message.content }}

Ещё два поля пригодятся в сценарии:

• {{ $json.choices[0].finish_reason }}. Значение stop означает полный ответ, length означает, что ответ обрезан по max_tokens, blacklist означает, что запрос попал под тематические ограничения.
• {{ $json.usage.total_tokens }} показывает, сколько токенов ушло на запрос. Сохраняйте его, чтобы видеть расходы.

Персональные данные

В стандартных соглашениях GigaChat для корпоративных клиентов сказано, что соглашение не предполагает передачу персональных данных физических лиц. Перед отправкой в модель текстов с именами, телефонами и адресами клиентов уточните условия у Сбера или замаскируйте данные.

Сколько стоит

Физическим лицам доступен бесплатный freemium-лимит. ИП и юрлица покупают пакеты токенов или платят по факту использования. Lite-модель заметно дешевле Pro и Max. Цены меняются, актуальные смотрите на странице тарифов для юрлиц. Чтобы оценить расходы, прогоните через сценарий 50–100 реальных текстов и умножьте total_tokens на ваш месячный объём.

Частые ошибки

• Ошибка сертификата. Корневой сертификат не подключён к контейнеру или файлы недоступны для чтения. Проверьте папку pki, владельца файлов и строку о сертификатах в логе n8n.
• 400 при получении токена. Нет заголовка RqUID, он не в формате uuid4 или тело отправлено как JSON вместо Form URLencoded.
• 401. Неверный ключ авторизации, пропущено слово Basic или scope не совпадает с типом вашего доступа. При запросе к модели 401 означает, что токен истёк.
• 422. Неверные параметры, например два системных сообщения.
• 429. Слишком много запросов. Включите повтор с паузой в настройках узла или обрабатывайте тексты пачками с узлом Wait.

Если вы выбираете между моделями, сравнение есть в статье YandexGPT, GigaChat или локальная модель.