Чому 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-колекції й забудьте про ручні тести. Отримати консультацію можна через форму на сайті — ми відповімо протягом робочого дня.