Інтеграція з постачальниками через API: покроковий посібник з підключення

Що таке API і як це працює: пояснення для нетехнічних користувачів

API (Application Programming Interface) – це спосіб, яким дві програми обмінюються даними автоматично. Представте офіціанта в ресторані: ви (ваш магазин) замовляєте страву (дані), офіціант (API) передає замовлення на кухню (постачальнику) та приносить готову страву назад (прайс-лист, залишки).

Ключові переваги API-інтеграції:

• Автоматизація — дані оновлюються без участі людини, за розкладом чи реальним часом
• Точність — виключені помилки ручного введення, помилки та неправильні формати
• Швидкість — оновлення даних займає секунди замість годинника ручної роботи
• Актуальність - інформація про ціни та залишки завжди свіжа, синхронізація кожні 15-60 хвилин
• Масштабованість - легко підключити десятки постачальників, система впорається з будь-яким обсягом
• Економія — менеджери витрачають час на продаж, а не на завантаження прайсів

Як працює API-інтеграція на прикладі:

1. Ваша система надсилає запит - "Дай мені актуальні ціни на всі товари категорії 'Електроніка'"
2. API постачальника обробляє запит - перевіряє вашу авторизацію, шукає дані у базі
3. Постачальник відправляє відповідь список товарів з цінами, залишками, описами у форматі JSON
4. Ваша система обробляє відповідь - оновлює базу даних, змінює ціни на сайті
5. Процес повторюється автоматично - за розкладом (кожні 30 хвилин) або за подією (webhook)

Покроковий посібник з інтеграції з постачальником через API

Процес інтеграції з постачальником API складається з 10 послідовних кроків. Навіть якщо у вас немає освіти, ви зможете розібратися за допомогою цієї інструкції.

Крок 1. Отримайте доступ до API постачальника

Зверніться до свого постачальника та зверніться до документації API. Зазвичай вам видадуть:

• API endpoint — URL-адреса, на яку надсилати запити (наприклад, https://api.supplier.com/v1)
• API key - Унікальний ключ для авторизації (наприклад, sk_live_51K3xYz...)
• Документацію — опис доступних методів, параметрів запитів та форматів відповідей
• Ліміти - обмеження на кількість запитів (зазвичай 100-1000 за годину)

Крок 2. Вивчіть документацію API

Перед початком інтеграції уважно вивчіть документацію. Зверніть увагу на:

• Доступні методи API (отримання прайс-листа, перевірка залишків, оформлення замовлення)
• Формати даних (JSON, XML, CSV)
• Обов'язкові параметри запитів
• Формат відповідей та коди помилок
• Rate limits (обмеження на частоту запитів)

Крок 3. Налаштуйте автентифікацію

API вимагає підтвердження вашої особи перед кожним запитом. Існує три основні методи аутентифікації:

API Key (найпростіший метод)

Ключ передається в заголовку або параметрах запиту:

 GET https://api.supplier.com/v1/products Headers: Authorization: Bearer sk_live_51K3xYz7HqP4mD8f... Content-Type: application/json

OAuth 2.0 (для складних інтеграцій)

Вимагає отримання тимчасового токена через процес авторизації:

 POST https://api.supplier.com/oauth/token Body:{ "grant_type": "client_credentials", "client_id": "your_client_id", "client_secret": "your_client_secret" } Response:{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600 }

JWT (JSON Web Token)

Зашифрований токен з інформацією про користувача та права доступу.

Крок 4. Створіть тестовий запит

Протестуйте підключення за допомогою простого запиту. Використовуйте інструмент Postman або cURL:

Приклад з Postman:

1. Завантажте та встановіть Postman (Безкоштовно)
2. Створіть новий запит: метод GET
3. Введіть URL-адресу: https://api.supplier.com/v1/products
4. Додати заголовок Authorization з вашим API ключем
5. Натисніть Send і перевірте відповідь

Приклад з cURL (командний рядок):

 curl -X GET "https://api.supplier.com/v1/products" \-H "Authorization: Bearer sk_live_51K3xYz..." \-H "Content-Type: application/json"

Крок 5. Отримайте перелік товарів

Основний запит для отримання прайс-листа з актуальними цінами та залишками:

Запит:

 GET https://api.supplier.com/v1/products?category=electronics&in_stock=true Headers: Authorization: Bearer sk_live_51K3xYz... Content-Type: application/json

Відповідь (JSON):

 { "status": "success", "total": 156, "page": 1, "per_page": 50, "data": [{ "sku": "ELEC-12345", "name": "Wireless Headphones Sony WH-1000XM5", "price": 349.99, "currency": "USD", "stock": 47, "warehouse": "EU-Warsaw", "category": "Electronics", "brand": "Sony", "ean": "4548736134683", "weight": 0.25, "updated_at": "2025-10-21T08:30:00Z" },{ "sku": "ELEC-12346", "name": "Smart Watch Apple Watch Series 9", "price": 429.00, "currency": "USD", "stock": 23, "warehouse": "EU-Amsterdam", "category": "Electronics", "brand": "Apple", "ean": "0195949038569", "weight": 0.15, "updated_at": "2025-10-21T08:30:00Z" } ] }

Крок 6. Опрацюйте відповідь API

Ваша система має правильно обробити отримані дані:

1. Перевірити статус відповіді (status: "success" або код HTTP 200)
2. Витягти масив товарів з поля "data"
3. Для кожного товару оновити або створити запис у базі даних
4. Порівняти товари за SKU або EAN кодом
5. Оновити ціни, залишки, описи
6. Логувати зміни для аудиту

 async function updateProductsFromAPI() { try { const response = await fetch('https://api.supplier.com/v1/products', { method: 'GET', headers:{ 'Authorization': 'Bearer sk_live_51K3xYz...', 'Content-Type': 'application/json' } }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); for (const product of data.data) { await updateProductInDatabase({ sku: product.sku, price: product.price, stock: product.stock, updated_at: product.updated_at } ); } console.log(`Updated ${data.total} products successfully`); } catch (error){ console.error('API integration error:', error); sendAlertToAdmin(error); } }

Крок 7. Налаштуйте обробку помилок

API може повертати помилки з різних причин. Важливо коректно їх обробляти:

Типові коди помилок HTTP:

Логіка повторних спроб (Retry Logic):

 async функція fetchWithRetry(url, options, maxRetries = 3) { for (let i = 0; i< maxRetries; i++) { try { const response = await fetch(url, options); if (response.ok) { return await response.json(); } // Если 429 (Too Many Requests) - ждем дольше if (response.status === 429) { const retryAfter = response.headers.get('Retry-After') || 60; console.log(`Rate limit hit, waiting ${retryAfter} seconds`); await sleep(retryAfter * 1000); continue; } // Если 5xx - повторяем с экспоненциальной задержкой if (response.status > = 500) {const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s console.log(`Server error, retrying in ${delay}ms`); await sleep(delay); continue; } // Для інших помилок - не повторюємо throw new Error(`HTTP ${response.status}: ${response.statusText}`); } catch (error) { if (i === maxRetries - 1) throw error; console.log(`Attempt ${i + 1} failed, retrying...`); } } }

Крок 8. Налаштуйте Rate Limiting та Throttling

Більшість API обмежують кількість запитів для запобігання навантаженню серверів. Типові ліміти:

• 100 запитів на хвилину - для базових тарифів
• 1000 запитів на годину - для стандартних тарифів
• 10000 запитів на день - для преміум тарифів

Як уникнути перевищення лімітів:

1. Використовуйте пагінацію - Завантажуйте дані порціями (50-100 товарів за запит)
2. Додати затримки між запитами - 100-500 мс для безпеки
3. Кешуйте відповіді — не просіть одні й ті самі дані повторно
4. Використовуйте webhooks — отримуйте оновлення лише при зміні даних
5. Запитуйте лише змінені дані — Використовуйте параметр updated_since

Приклад з обмеженням швидкості:

 // Обмеження: максимум 10 запитів на секунду const rateLimiter = { requests: [], maxRequests: 10, interval: 1000, // 1 секунда async waitIfNeeded() { const now = Date.now(); this.requests = this.requests.filter(time => now - time< this.interval); if (this.requests.length > = this.maxRequests) { const oldestRequest = Math.min(...this.requests); const waitTime = this.interval - (now - oldestRequest); await sleep(waitTime); } this.requests.push(Date.now()); } }; // Використання перед кожним запитом await rateLimiter.waitIfNeeded(); const data = await fetch(apiUrl);

Крок 9. Налаштуйте Webhooks для оновлень у реальному часі

Webhooks — це спосіб отримувати сповіщення від постачальника автоматично, коли змінюються ціни або залишки. Замість того, щоб постійно опитувати API, постачальник сам надішле вам дані при зміні.

Як працюють webhooks:

1. Ви надаєте постачальнику URL-адресу для отримання повідомлень (наприклад, https://yourstore.com/api/webhook/supplier)
2. Постачальник реєструє цю URL у своїй системі
3. При зміні даних (ціна знизилася, товар з'явився) постачальник відправляє POST-запит на ваш URL
4. Ваша система отримує дані та оновлює базу миттєво

Приклад webhook-повідомлення:

 POST https://yourstore.com/api/webhook/supplier Headers: X-Webhook-Signature: sha256=5d41402abc4b2a76b9719d911017c592 Content-Type: application/json Body: { "event": "product "2025-10-21T09:15:00Z", "data":{ "sku": "ELEC-12345", "price": 329.99, "old_price": 349.99, "stock": 52, "old_stock": 47, "changes": ["price", "stock"] } }

Обробка webhook на вашому боці:

 app.post('/api/webhook/supplier', async (req, res) => { try { // Перевірка підпису для безпеки const signature = req.headers['x-webhook-signature']; if (!verifyWebhookSignature(req.staty)) } const { event, data } = req.body;{ sku: data.sku, price: data.price, stock: data.stock } ); console.log(`Product ${data.sku} updated via webhook`); } // Важливо: швидко відповісти 200 OK res.status(200).send('Webhook received'); } catch (error){ console.error('Webhook processing error:', error); res.status(500).send('Error processing webhook'); } });

Крок 10. Налаштуйте моніторинг та тестування

Після запуску інтеграції необхідно постійно контролювати її роботу:

Що моніторити:

• Успішність запитів - Відсоток успішних відповідей (має бути 98-99%)
• Час відповіді API - Швидкість обробки запитів (норма 200-500 мс)
• Кількість помилок - Частота 4xx і 5xx помилок
• Актуальність даних - час останнього успішного оновлення
• Зміни цін та залишків лог всіх оновлень для аудиту

Інструменти для моніторингу:

• Sentry - відстеження помилок у реальному часі
• Datadog / New Relic - Моніторинг продуктивності API
• Pingdom/UptimeRobot - Перевірка доступності endpoint
• Custom dashboard - Панель з метриками інтеграції

REST API vs SOAP: який протокол вибрати

Існує два основні протоколи для API-інтеграцій: REST та SOAP. Більшість сучасних API використовують REST, але деякі старі системи працюють лише через SOAP.

Коли використовувати REST:

• Нові інтеграції із сучасними постачальниками
• Веб-додатки та мобільні програми
• Коли важлива швидкість та простота розробки
• Коли потрібна гнучкість у форматах даних

Коли використовувати SOAP:

• Інтеграція із застарілими ERP-системами (SAP, Oracle)
• Високі вимоги до безпеки та транзакцій
• Банківські та фінансові інтеграції
• Коли постачальник надає лише SOAP API

Методи аутентифікації: API Key, OAuth2, JWT

Аутентифікація – це спосіб підтвердження вашої особи перед API. Різні постачальники використовують різні методи, кожен із своїми особливостями.

1. API Key (ключ доступу)

Як працює: Постачальник видає унікальний ключ (довгий рядок символів), який ви надсилаєте з кожним запитом.

Переваги:

• Простота реалізації – один ключ для всіх запитів
• Не потребує складної логіки авторизації
• Ідеально для server-to-server інтеграцій

Недоліки:

• Якщо ключ вкрадено, зломщик отримує повний доступ
• Не можна обмежити права доступу (усі чи нічого)
• Важко відкликати доступ для конкретного клієнта

Приклад використання:

 // У заголовку Authorization curl -H "Authorization: Bearer sk_live_51K3xYz7HqP4mD8f..." \ https://api.supplier.com/v1/products // Або в query параметрі curl https://api.supplier.com/v1/z

2. OAuth 2.0 (стандарт авторизації)

Як працює: Ви отримуєте тимчасовий токен доступу через процес авторизації. Токен діє обмежений час (зазвичай 1:00), потім оновлюється.

Переваги:

• Висока безпека - токени тимчасові та автоматично оновлюються
• Гнучкі права доступу (scopes) — Ви можете обмежити доступ до певних даних
• Можна відкликати токен без зміни облікових даних

Недоліки:

• Складна реалізація - потрібна логіка оновлення токенів
• Потрібно зберігати client_id, client_secret, refresh_token

Приклад використання:

 // Крок 1: Отримання access token POST https://api.supplier.com/oauth/token Content-Type: application/json{ "grant_type": "client_credentials", "client_id": "your_client_id_here", "client_secret": "your_client_secret_here", "scope": "products:read orders:write" } // Відповідь:{ "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "def50200a1b2c3d4e5f6..." } // Крок 2: Використання токена для запитів GET https://api.supplier.com/v1/products Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... // Крок 3: Оновлення токена коли закінчується POST https{ "grant_type": "refresh_token", "refresh_token": "def50200a1b2c3d4e5f6...", "client_id": "your_client_id_here" }

3. JWT (JSON Web Token)

Як працює: Зашифрований токен, який містить інформацію про користувача та його права. Сервер перевіряє підпис токена без звернення до бази даних.

Переваги:

• Не вимагає зберігання сесій на сервері
• Містить всю інформацію про права доступу всередині токена
• Швидка перевірка - не потрібно звертатися до бази даних

Структура JWT:

 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6Ikpv aG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c // Розшифровка: {"header":{ "alg": "HS256", "typ": "JWT" }, "payload":{ "sub": "1234567890", "name": "John Doe", "iat": 1516239022, "scope": ["products:read", "orders:write"] }, "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c" }

Безпека API-інтеграцій: найкращі практики

Неправильна реалізація API може призвести до витоку даних, злому облікового запису або фінансових втрат. Дотримуйтесь цих правил безпеки:

1. Зберігайте ключі API безпечно

• Ніколи не зберігайте ключі в коді - використовуйте змінні оточення (.env файли)
• Не коментуйте ключі в Git - Додайте.env в.gitignore
• Використовуйте секретні сховища — AWS Secrets Manager, Azure Key Vault, HashiCorp Vault
• Різні ключі для розробки та продакшену - test/sandbox ключі для тестів

2. Використовуйте HTTPS завжди

• Всі запити до API повинні йти через HTTPS, ніколи через HTTP
• Перевіряйте SSL-сертифікати (не вимикайте перевірку)
• Використовуйте TLS 1.2 або вище

3. Перевіряйте webhook підписи

• Завжди перевіряйте підпис webhook-запитів перед обробкою
• Використовуйте HMAC-SHA256 для перевірки автентичності
• Відхиляйте запити без валідного підпису

Приклад перевірки webhook підпису:

 const crypto = require('crypto'); function verifyWebhookSignature(payload, signature, secret) { const hmac = crypto.createHmac('sha256', secret); const digest = 'sha256=' + hmac.update(JSON.stringify(payload)).digest('hex'); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(digest) ); } // Використання const isValid = verifyWebhookSignature( req.body, req.headers['x-webhook-signature'], process.env.WEBHOOK_SECRET ); if (!isValid) { return res.status(401).send('Invalid signature'); }

4. Логуйте всі дії

• Записуйте всі API-запити та відповіді (але не логіруйте API ключі)
• Зберігайте логи щонайменше 30 днів для аудиту
• Моніторьте підозрілу активність (багато помилок 401, незвичайні запити)

5. Обмежуйте права доступу

• Запитуйте лише необхідні права (scopes)
• Використовуйте read-only ключі, де можливо
• Різні ключі для різних інтеграцій

Інструменти для роботи з API

Для розробки та налагодження API-інтеграцій використовуйте професійні інструменти:

1. Postman (найпопулярніший)

• Призначення: Тестування API-запитів, створення колекцій, автоматизація тестів
• Ціна: Безкоштовно для базових функцій, Pro від $12/місяць
• Особливості: Графічний інтерфейс, збереження запитів, змінні оточення, автотести
• Посилання: postman.com

2. cURL (командний рядок)

• Призначення: Швидкі випробування з терміналу, скрипти автоматизації.
• Ціна: Безкоштовно, вбудований в Linux/Mac, для Windows завантажити окремо
• Особливості: Потужний, гнучкий, але вимагає знання синтаксису

Приклади команд cURL:

 # GET запит з авторизацією curl -X GET "https://api.supplier.com/v1/products" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" # POST запит з даними curl -X POST "https://api" "Authorization: Bearer YOUR_API_KEY" \-H "Content-Type: application/json" \-d'{ "product_sku": "ELEC-12345", "quantity": 5, "delivery_address": "Kyiv, Ukraine" } ' # Збереження відповіді у файл curl -X GET "https://api.supplier.com/v1/products" \ -H "Authorization: Bearer YOUR_API_KEY" \ -o products.json

3. Insomnia

• Призначення: Альтернатива Postman з більш простим інтерфейсом
• Ціна: Безкоштовно, Pro від $5/місяць
• Посилання: insomnia.rest

4. Swagger/OpenAPI

• Призначення: Документація та тестування API, автогенерація коду клієнтів
• Ціна: Безкоштовно для open source
• Особливості: Багато постачальників публікують Swagger-документацію для API

5. Webhook.site

• Призначення: Тестування webhooks без написання коду
• Ціна: Безкоштовно
• Як використовувати: Отримайте тимчасовий URL, вкажіть його як webhook endpoint, дивіться запити, що надходять у браузері
• Посилання: webhook.site

Інтеграція з платформою Elbuz

Платформа Elbuz пропонує готові рішення для інтеграції з постачальниками через API. Замість розробки інтеграції з нуля ви можете використовувати вбудовані інструменти.

Можливості Elbuz API:

• Готові конектори — підключення до популярних постачальників у кілька кліків
• Універсальний REST API — підключення будь-якого постачальника документації
• Автоматична синхронізація - Налаштування розкладу оновлень (кожні 15-60 хвилин)
• Мапінг полів - зіставлення полів вашої бази та полів постачальника
• Обробка помилок - Автоматичні повтори при збоях
• Webhooks - Підтримка оновлень у реальному часі
• Логування - історія всіх запитів та змін
• Моніторинг - Повідомлення при проблемах з інтеграцією

Дізнайтесь більше про можливості автоматизації в нашому повному посібнику з управління даними та синхронізації.

Часті питання (FAQ)

Пов'язані матеріали

• Управление данными: импорт и синхронизация прайс-листов
• Как настроить автоматическую синхронизацию цен и остатков с сайтом
• Автоматическая загрузка прайс-листов по Email и FTP
• Работа с прайс-листами через Google Sheets API