Почему Postman-коллекция обязательна для API Битрикс
Разработчик CusDev сталкивается с десятками эндпоинтов — обмен товарами 1С, создание лидов, обработка заказов. Без готовых запросов каждый тест превращается в копирование cURL из документации. Мы настраиваем Postman-коллекцию так, что один клик — и API отвечает. Наш опыт работы с Битрикс — более 10 лет, 50+ проектов, гарантия качества. Postman-коллекция для 1С-Битрикс — это не просто набор HTTP-запросов, а полноценный инструмент автоматизации тестирования и документирования API. Она включает автоматическую авторизацию, переменные окружения для разных стендов, тесты на статус и структуру ответа. С такой коллекцией регрессионное тестирование из 20 эндпоинтов занимает 1–2 минуты вместо 30–60 минут ручного труда. Экономия времени на каждом цикле — до 20 часов в месяц.
Проблемы, которые решает коллекция
- Отсутствие документации. Битрикс-разработчики часто полагаются на устные договорённости. Коллекция становится единым источником правды.
- Ошибки авторизации. JWT-токены протухают, ключи API путаются. Автоматизация в Pre-request Script исключает человеческий фактор.
- Долгий регресс. После каждого обновления нужно проверять все эндпоинты. Collection Runner и Newman делают это за минуты.
| Сценарий | Без коллекции | С коллекцией |
|---|---|---|
| Проверка 20 эндпоинтов | 30–60 минут | 1–2 минуты |
| Смена окружения (dev→prod) | Правка каждого запроса | Смена переменной окружения |
| Регресс после деплоя | Ручной, пропуски ошибок | Автоматический, 100% покрытие |
Как автоматизировать авторизацию в Postman?
При работе с JWT-авторизацией token нужно получать и подставлять в каждый запрос. В Postman это решается через Pre-request Script в запросе логина:
pm.sendRequest({ url: pm.environment.get('base_url') + '/api/v1/auth/login', method: 'POST', header: { 'Content-Type': 'application/json' }, body: { mode: 'raw', raw: JSON.stringify({ login: pm.environment.get('api_login'), password: pm.environment.get('api_password') }) } }, function(err, res) { if (!err) { pm.environment.set('token', res.json().token); } }); Для остальных запросов в разделе Authorization → Bearer Token: {{token}}. Либо настроить авторизацию на уровне коллекции — тогда все запросы наследуют её. Это сокращает время настройки каждого запроса с 5 минут до 10 секунд — в 30 раз быстрее.
Что входит в настройку коллекции
- Проектирование структуры коллекции (группы эндпоинтов: Auth, Catalog, Orders, CRM)
- Создание переменных окружения для dev/stage/prod
- Настройка Pre-request Script для автоматической авторизации
- Добавление тестов для каждого запроса (статус, структура ответа, обязательные поля)
- Экспорт коллекции в JSON (Collection v2.1) и интеграция с Git
- Документация по запуску (включая Newman для CI/CD)
- Обучение команды (1 час онлайн)
Как мы настраиваем коллекцию: процесс работы
- Анализ API. Изучаем эндпоинты, методы, авторизацию, форматы данных.
- Проектирование структуры. Разбиваем на логические группы, создаём папки.
- Создание окружений. Готовим переменные для каждого стенда.
- Реализация запросов. Добавляем заголовки, тела, параметры.
- Автоматизация авторизации. Пишем Pre-request Script.
- Тесты. Добавляем проверки для каждого запроса.
- Экспорт и интеграция. Сохраняем в репозиторий, настраиваем Newman в CI/CD.
Collection Runner и Newman
Collection Runner позволяет запустить все запросы коллекции последовательно и увидеть, все ли тесты прошли. Это базовое smoke-тестирование API.
Newman — CLI-инструмент для запуска коллекций из командной строки. Интегрируется в CI/CD:
npm install -g newman newman run bitrix-api.postman_collection.json \ -e production.postman_environment.json \ --reporters cli,html После каждого деплоя CI автоматически прогоняет коллекцию и проверяет работоспособность API. Экономия времени на регресс — до 20 часов в месяц.
Как избежать типичных ошибок при настройке?
Одна из частых проблем — неправильное хранение чувствительных данных. Никогда не кладите логины и пароли в саму коллекцию. Используйте переменные окружения, которые не попадают в Git. Вторая ошибка — забыть обновить коллекцию после изменения API. Рекомендуем хранить JSON-файл коллекции в том же репозитории, что и код, и обновлять его в рамках той же задачи.
| Ошибка | Последствие | Решение |
|---|---|---|
| Пароли в коллекции | Утечка данных | Переменные окружения |
| Коллекция не в Git | Рассинхрон с командой | Хранить в репозитории |
| Нет тестов | Пропуск ошибок | Добавить тесты на каждый запрос |
Документация из коллекции
Postman генерирует документацию из коллекции автоматически: описание каждого запроса, примеры ответов, параметры. Это не полноценная OpenAPI-документация, но достаточно для внутреннего использования.
Почему стоит инвестировать в настройку коллекции?
Настройка коллекции для API из 15–20 эндпоинтов с тестами и окружениями — 1–2 дня. Свяжитесь с нами для консультации — оценим ваш проект за один день. Закажите настройку Postman-коллекции и забудьте о ручных тестах. Получить консультацию можно через форму на сайте — мы ответим в течение рабочего дня.