Настройка Postman-коллекций для API 1С-Битрикс

Настройка Postman-коллекций для API 1С-Битрикс

Postman-коллекция — это набор сохранённых HTTP-запросов с параметрами, заголовками, телами и тестами. Для API 1С-Битрикс коллекция позволяет быстро проверить работу эндпоинтов, не писая код — разработчик открывает Postman, выбирает запрос, нажимает Send.

Структура Postman-коллекции

Коллекция организована иерархически:

Коллекция: My Bitrix API
├── Auth
│   ├── POST /auth/login
│   └── POST /auth/refresh
├── Catalog
│   ├── GET /products
│   ├── GET /products/:id
│   ├── POST /products
│   └── PUT /products/:id
├── Orders
│   ├── GET /orders
│   └── POST /orders
└── CRM
    ├── GET /leads
    └── POST /leads

Переменные окружения

Postman поддерживает переменные окружения — ключевой инструмент для переключения между сервером разработки и продакшеном без правки каждого запроса.

Создаётся два окружения:

Development:

base_url = http://atlas.loc
api_key = dev-key-12345
token = (заполняется скриптом)

Production:

base_url = https://mysite.ru
api_key = prod-key-67890
token = (заполняется скриптом)

В запросах используются переменные: {{base_url}}/api/v1/products.

Автоматизация авторизации

При работе с JWT-авторизацией token нужно получать и подставлять в каждый запрос. В Postman это решается через Pre-request Script в запросе логина:

// Pre-request Script для POST /auth/login
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}}.

Либо настроить авторизацию на уровне коллекции — тогда все запросы наследуют её.

Тесты в Postman

К каждому запросу добавляются автоматические проверки на вкладке Tests:

// GET /products — базовые тесты
pm.test("Status 200", () => pm.response.to.have.status(200));
pm.test("Response is JSON", () => pm.response.to.be.json);

const json = pm.response.json();
pm.test("Has data array", () => {
    pm.expect(json).to.have.property('data');
    pm.expect(json.data).to.be.an('array');
});

pm.test("Product has required fields", () => {
    if (json.data.length > 0) {
        const product = json.data[0];
        pm.expect(product).to.have.all.keys(['id', 'name', 'price']);
    }
});

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.

Экспорт и совместное использование

Коллекция экспортируется в JSON (Collection v2.1) и хранится в репозитории рядом с кодом. При изменении API — обновляется файл коллекции.

Для совместного использования командой: публикация в Postman Workspace (командная функция Postman) или обмен через Git.

Документация из коллекции

Postman генерирует документацию из коллекции автоматически: описание каждого запроса, примеры ответов, параметры. Это не полноценная OpenAPI-документация, но достаточно для внутреннего использования.

Настройка коллекции для API из 15-20 эндпоинтов с тестами и окружениями — 1-2 дня.