Конфігурація через URL-параметри

Кожен контрольний заголовок MirApi має еквівалентний псевдонім у вигляді URL query-параметра. Це дозволяє налаштовувати всі можливості шлюзу — повтори, кешування, каскади, асинхронні вебхуки — безпосередньо в URL, без додавання кастомних HTTP-заголовків.

Ця можливість розроблена для сторонніх вебхук-провайдерів (Shopify, GitHub, Stripe, CRM-платформи), які приймають лише одне URL-поле та не дозволяють вставляти кастомні заголовки.

---

Навіщо потрібні query-параметри?

Раніше MirApi налаштовувався виключно через кастомні X-* HTTP-заголовки. Це добре працює, коли запит виконує ваш власний код. Але багато платформ, що надсилають вебхуки — Shopify Admin, GitHub Actions, Stripe Events, HubSpot, Salesforce — дозволяють вказати лише URL призначення. Вони надсилають власні фіксовані заголовки, не надаючи жодної можливості додати кастомні.

Відображення query-параметрів як запасний варіант вирішує цю проблему: будь-який заголовок маршрутизації, стійкості або безпеки можна передати як GET query-параметр, доданий до URL вебхука MirApi.

---

Основні правила

Обережно

Пріоритет заголовків: HTTP-заголовки завжди мають пріоритет над query-параметрами. Якщо в одному запиті присутні і X-Target-URL (заголовок), і target (query-параметр), шлюз використовує значення заголовка та ігнорує параметр. Це дозволяє безпечно комбінувати обидва підходи — заголовки завжди перемагають.

Небезпечно

URL-кодування є обов’язковим. Будь-який URL, переданий у query-параметрі (цільові ендпоінти, адреси callback), повинен бути URL-закодований. Замініть https:// на https%3A%2F%2F, а / на %2F. Без кодування шлюз неправильно розпарсить вкладений URL і відхилить запит з помилкою 400 Bad Request.

Використовуйте encodeURIComponent() у JavaScript або urllib.parse.quote() у Python.

Порада

Рядки тривалості: Усі параметри тайм-аутів і затримок приймають стандартні рядки тривалості Go: 200ms, 5s, 1m, 1h30m. Прості числа є недійсними — використовуйте 5s, а не 5.

---

Повна таблиця відповідності: заголовок → query-параметр

HTTP Заголовок	Псевдонім(и) query-параметра	Опис
X-MirApi-Key	mirapi_key або apiKey	Токен автентифікації MirApi. Обов’язковий у кожному запиті.
X-Target-URL	target_url або target	Кінцевий API-ендпоінт для пересилання запиту. Повинен бути URL-закодований.
X-Route-Key	route_key або route	Вибирає попередньо налаштований каскадний маршрут з вашого дашборду.
X-Webhook-Callback	webhook_callback або callback	Вмикає асинхронний режим черги. Визначає callback-ендпоінт. Повинен бути URL-закодований.
X-Failover-URL	failover_url	Резервний ендпоінт, якщо цільовий не відповідає після всіх спроб. Повинен бути URL-закодований.
X-Proxy-Timeout	proxy_timeout або timeout	Загальний тайм-аут запиту (наприклад, 10s). Обмежує весь час виконання, включно із затримками повторів.
X-Attempt-Timeout	attempt_timeout	Тайм-аут на одну спробу (наприклад, 2s). Перевищення вважається помилкою і тригерить наступну спробу.
X-Retry-Count	retry_count або retries	Максимальна кількість спроб повтору при помилці 5xx або збої з’єднання.
X-Retry-Delay	retry_delay або delay	Початкова затримка для експоненційного повтору (наприклад, 100ms). При кожній спробі затримка подвоюється плюс джиттер.
X-Circuit-Breaker	circuit_breaker або cb	Вмикає circuit breaker для цільового хоста. Приймає on або true.
X-Smart-Cache	smart_cache або cache	Кешує останню успішну відповідь і повертає її при збої upstream (наприклад, 60s).
X-Extract-Map	extract_map або map	Витягує та перейменовує поля з JSON-відповіді upstream (наприклад, $.id=>new_id).
X-Extract-Redirect	extract_redirect або redirect	Витягує URL перенаправлення з JSON-відповіді upstream і повертає 302 Found.

---

Приклади

Приклад 1 — Асинхронна черга вебхуків Shopify

Shopify надсилає вебхуки при оформленні замовлень. Якщо ваш ERP або CRM тимчасово недоступний, Shopify позначить ваш ендпоінт як несправний і може деактивувати його після певної кількості невдач.

Використовуючи асинхронний режим вебхуків MirApi, вкажіть URL MirApi як призначення в Shopify. MirApi негайно повертає 202 Accepted до Shopify (запобігаючи деактивації), зберігає корисне навантаження в чергу Redis і доставляє його до вашого ERP з автоматичними повторами.

URL вебхука Shopify:

https://proxy.mirapi.io/v1/webhook?mirapi_key=your_api_key&callback=https%3A%2F%2Fmy-erp.com%2Fapi%2Forders&retries=10&delay=1s&timeout=5s

Розбір параметрів:

Параметр	Значення	Еквівалентний заголовок
mirapi_key	your_api_key	X-MirApi-Key
callback	https%3A%2F%2Fmy-erp.com%2Fapi%2Forders	X-Webhook-Callback
retries	10	X-Retry-Count
delay	1s	X-Retry-Delay
timeout	5s	X-Proxy-Timeout

Що відбувається:

1. Shopify надсилає POST на URL MirApi з даними замовлення.
2. MirApi перевіряє mirapi_key і негайно повертає 202 Accepted до Shopify.
3. Корисне навантаження додається до черги воркера Redis.
4. Воркер виконує POST https://my-erp.com/api/orders з до 10 повторами, починаючи із затримки 1 секунда з експоненційним збільшенням (до 5s за спробу).
5. У разі успіху завдання завершується. У разі повного збою callback-ендпоінт отримує повідомлення про помилку.

---

Приклад 2 — Синхронне проксіювання з розумним кешуванням

Використовуйте цей варіант, коли потрібно отримувати дані від стороннього API з автоматичними повторами та кешем, що повертає останню відому успішну відповідь при збої upstream.

GET https://proxy.mirapi.io/v1/proxy?mirapi_key=your_api_key&target=https%3A%2F%2Fapi.external-service.com%2Fv1%2Fproducts&retries=3&cache=60s HTTP/1.1

Що відбувається:

1. MirApi пересилає GET на https://api.external-service.com/v1/products.
2. У разі успіху відповідь кешується на 60 секунд та повертається вам.
3. Якщо upstream повертає 5xx або перевищує тайм-аут, MirApi повторює спробу до 3 разів з експоненційним відкатом.
4. Якщо всі спроби невдалі, MirApi повертає закешовану успішну відповідь (якщо є). Відповідь містить X-Rescued: cache.

---

Приклад 3 — Каскадний маршрут з дашборду через URL вебхука

Якщо у вас є складний багатоцільовий каскад з відображенням тіла запиту, попередньо налаштованим у дашборді MirApi, посилайтеся на нього одним параметром route.

URL вебхука Shopify:

https://proxy.mirapi.io/v1/webhook?mirapi_key=your_api_key&route=shopify_to_crm

Це вказує шлюзу завантажити маршрут shopify_to_crm з вашого акаунту, який може включати:

• Кілька каскадних цілей (наприклад, Salesforce → HubSpot → Pipedrive)
• Відображення полів тіла запиту (наприклад, line_items => order_lines)
• Тайм-аути та стратегію аварійного перемикання для кожної цілі

Не потрібно повторювати URL цілей, тайм-аути та правила відображення в кожному URL.

---

Покрокова інструкція: Інтеграція вебхуків Shopify

Налаштуйте Shopify для доставки подій orders/create до вашого ERP через MirApi з асинхронною чергою та захистом повторів.

1. Отримайте ваш API-ключ MirApi

   Увійдіть до mirapi.io, відкрийте дашборд і скопіюйте ваш API-ключ. Він виглядатиме приблизно так: la_5fa62960e7c9af7c***.

2. Визначте ваш ендпоінт ERP для вебхуків

   Це URL, куди Shopify має доставляти дані замовлень в кінцевому підсумку. Наприклад:

   https://my-erp.com/api/orders/shopify

3. URL-закодуйте ваш ендпоінт ERP

   URL-закодуйте URL ERP перед вставкою в рядок запиту:

   Вхід:  https://my-erp.com/api/orders/shopify
   Вихід: https%3A%2F%2Fmy-erp.com%2Fapi%2Forders%2Fshopify

   Швидке кодування у вашій мові програмування:

   • JavaScript: encodeURIComponent('https://my-erp.com/api/orders/shopify')
   • Python: urllib.parse.quote('https://my-erp.com/api/orders/shopify', safe='')
   • Go: url.QueryEscape("https://my-erp.com/api/orders/shopify")

4. Побудуйте ваш URL вебхука MirApi

   Зберіть фінальний URL з параметрами стійкості:

   https://proxy.mirapi.io/v1/webhook?mirapi_key=la_5fa62960e7c9af7c***&callback=https%3A%2F%2Fmy-erp.com%2Fapi%2Forders%2Fshopify&retries=10&delay=1s&timeout=5s&cb=on

   Використані параметри:

   Параметр	Значення	Ефект
   mirapi_key	la_5fa62960e7c9af7c***	Автентифікація запиту
   callback	https%3A%2F%2F...	Ендпоінт ERP (URL-закодований)
   retries	10	До 10 спроб, якщо ERP недоступний
   delay	1s	Початкова затримка 1s, подвоюється кожної спроби
   timeout	5s	Кожна спроба доставки завершується після 5s
   cb	on	Вмикає circuit breaker для хоста ERP

5. Налаштуйте в Shopify Admin

   Перейдіть до Settings → Notifications → Webhooks і створіть новий вебхук:

   • Event (Подія): Order creation
   • Format (Формат): JSON
   • URL: (вставте ваш URL MirApi з Кроку 4)

6. Перевірте в дашборді MirApi

   Створіть тестове замовлення в Shopify. У дашборді MirApi відкрийте вкладку Webhook Queue, щоб знайти вхідне завдання. Панель завдання показує:

   • Спроби доставки з мітками часу
   • HTTP-код статусу за кожну спробу
   • Фінальний статус доставки та будь-яке повідомлення про помилку

Порада

Потрібне перетворення payload? Якщо ваш ERP очікує іншу JSON-структуру, ніж надсилає Shopify (наприклад, line_items → items), налаштуйте маршрут в дашборді з правилами відображення полів і замініть параметр callback=... на route=shopify_to_erp. Шлюз автоматично перетворить payload перед кожною спробою доставки.

---

Міркування безпеки

API-ключ у URL
Query-параметри, включно з mirapi_key, відображаються в логах доступу сервера та можуть бути збережені в історії браузера або сторонніх аналітичних системах. Ставтеся до URL вебхука як до секрету. Негайно змінюйте API-ключ, якщо підозрюєте, що URL був скомпрометований.

Тільки HTTPS
Використовуйте виключно https://proxy.mirapi.io/.... Query-параметри, передані через звичайний HTTP, видно при передачі.

Перевірка callback-ендпоінту
Щоб підтвердити, що callback-запити, що надходять до вашого ERP, дійсно від MirApi, а не є підробленими, використовуйте:

• IP-фільтрацію: Обмежте вхідні запити до опублікованих діапазонів вихідних IP MirApi.
• Секретний токен у шляху: Вставте секретний токен у шлях URL callback (наприклад, /api/orders/shopify/s3cr3t-token), відомий тільки MirApi.