Глава 5. HTTP-запросы и внешние API

Нода HTTP Request — рабочая лошадка n8n. Она умеет обращаться к любому REST API, скачивать файлы, отправлять данные и обрабатывать сложную пагинацию. Если для сервиса нет готовой интеграции, HTTP Request закроет 95% задач.

Основные параметры

Метод и URL

Поле URL принимает как статический адрес, так и выражения:

https://api.example.com/users/{{ $json.userId }}

Поддерживаемые методы: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS.

Query Parameters (параметры строки запроса)

Вместо ручного добавления ?key=value&... в URL используйте вкладку Query Parameters:

Name	Value
limit	100
offset	{{ $json.page * 100 }}
filter	active

n8n сам собирает параметры в URL и корректно их экранирует.

Headers (заголовки)

Content-Type    application/json
X-API-Version   2024-01-01
Accept          application/json

Body (тело запроса)

Для POST/PUT/PATCH нужно передать тело. Варианты:

JSON — наиболее распространённый:

{
  "name": "{{ $json.fullName }}",
  "email": "{{ $json.email }}",
  "role": "user"
}

Form Data (multipart) — для загрузки файлов:

field: file
value: {{ $binary.data }}

URL-encoded — для старых API и OAuth:

grant_type=client_credentials&client_id=abc&client_secret=xyz

Raw — для нестандартных форматов (XML, GraphQL и т.д.):

<query><id>&#123;&#123; $json.id &#125;&#125;</id></query>

Аутентификация

Переключатель Authentication в верхней части ноды открывает готовые схемы.

Predefined Credential Type

Для популярных сервисов n8n предлагает готовые шаблоны credential. Выберите тип (например GitHub API) — n8n сам подставит правильные заголовки.

Generic Credential Type

Header Auth — токен в заголовке (самый частый случай):

Header Name:  Authorization
Header Value: Bearer YOUR_TOKEN

Basic Auth — логин и пароль (Base64-кодируются автоматически):

User: myuser
Password: mypassword

Query Auth — API-ключ в параметре URL:

Name: api_key
Value: abc123

OAuth2 — трёхшаговая авторизация. Настраивается через Credentials UI, нода получает access token автоматически и обновляет его при истечении.

Храните секреты в Credentials

Не вставляйте токены прямо в поле URL или Headers — они будут видны в истории выполнений и логах. Создайте Credential типа Header Auth и выберите его в ноде.

Обработка ответа

Send Response Headers

Включите, чтобы получить заголовки ответа в $json.headers. Полезно для чтения X-Rate-Limit-Remaining или Link с пагинацией.

Response Format

Формат	Когда использовать
Autodetect	Для большинства JSON/текстовых API
JSON	Когда сервер не ставит правильный Content-Type
Text	Для plain text, CSV
File	Для скачивания бинарных файлов (PDF, изображения)
ArrayBuffer	Для ручной обработки байт

Работа с ошибками HTTP

По умолчанию коды 4xx и 5xx выбрасывают исключение и прерывают воркфлоу. Чтобы обрабатывать их вручную:

• Включите Options → Ignore HTTP Status Errors — ошибочные ответы попадут в обычный поток с полями statusCode, headers, body

Затем добавьте IF-ноду после:

{{ $json.statusCode }} greater than or equal 400  → ветка обработки ошибки

Пагинация

Большинство API возвращают данные порциями. HTTP Request умеет проходить их автоматически через Pagination.

По номеру страницы

Type: Update a parameter in each request
Parameter Name: page
Parameter Location: Query
Initial Value: 1
Increment By: 1

Условие остановки — когда ответ содержит меньше limit записей:

Pagination Complete When: Response Body Is Empty

или через выражение:

&#123;&#123; $response.body.data.length < 100 &#125;&#125;

По cursor / next_url

Многие современные API возвращают next_cursor или next_url:

{
  "data": [...],
  "paging": {
    "cursors": { "after": "MTAxNTEx" },
    "next": "https://api.example.com/users?cursor=MTAxNTEx"
  }
}

Настройка:

Type: Update a parameter in each request
Parameter Name: cursor
Parameter Value (expression): {{ $response.body.paging.cursors.after }}
Pagination Complete When: {{ !$response.body.paging.next }}

По заголовку Link (GitHub, GitLab стиль)

Type: URL from response
URL source: Response Header
Header Name: Link
Regex to extract URL: <([^>]+)>; rel="next"
Pagination Complete When: &#123;&#123; !$response.headers.link?.includes('rel="next"') &#125;&#125;

Работа с файлами

Скачивание файла

Method: GET
URL: https://example.com/report.pdf
Response Format: File

Файл попадёт в $binary.data в виде бинарных данных. Его можно передать в Email-ноду, сохранить через FTP или преобразовать.

Загрузка файла

Method: POST
Body Content Type: Form-Data
Field Name: file
Field Value: {{ $binary.data }}   (тип: File)

Практика: получить все репозитории GitHub

// HTTP Request 1 — список репозиториев с пагинацией
Method: GET
URL: https://api.github.com/user/repos
Authentication: Header Auth (Authorization: Bearer ghp_xxx)
Query Parameters:
  per_page: 100
  sort: updated

Pagination:
  Type: URL from Response Header
  Header Name: Link
  Complete When: {{ !$response.headers.link?.includes('rel="next"') }}

После нода Code для фильтрации:

return items.filter(i => i.json.stargazers_count > 10).map(i => ({
  json: {
    name: i.json.full_name,
    stars: i.json.stargazers_count,
    url: i.json.html_url
  }
}));

Тестирование HTTP запросов

Нажмите Execute Node на выбранной ноде — она выполнится один раз с тестовыми данными, не запуская весь воркфлоу. Удобно для отладки параметров.