Налаштування колекцій 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 підтримує змінні середовища — ключовий інструмент для перемикання між сервером розробки та production без правки кожного запиту.
Створюються два середовища:
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-авторизацією токен потрібно отримати та підставити в кожен запит. У 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 дні.