Курси валют з вашого сайту до Elbuz: завантаження за своїм посиланням у форматі JSON

Ви маєте власний сайт або програму бухгалтерії, CMS Opencart, WooCommenrce, Prestashop, Magento або іншу систему, де вже зберігаються «правильні» курси валют? Ті самі, якими ви реально вважаєте ціни — не біржові, а ваші робітники. Раніше їх доводилося переносити до Elbuz руками. Тепер – ні. Ви розміщуєте на своєму сайті маленький скрипт, який віддає курси у простому форматі, вказуєте посилання на нього в Elbuz і система сама забирає свіжі курси та перераховує ціни.

Одного разу налаштували посилання — далі Elbuz бере курси з вашого джерела автоматично, як із офіційного банку.

Навіщо це потрібно і яку проблему вирішує

Elbuz вміє тягнути курси з громадських джерел — біржі та центробанки. Але в реальному бізнесі курс «з банку» і курс, яким ви продаєте, — це часто різні числа. У вас може бути:

свій внутрішній курс, який встановлює бухгалтерія чи керівник;
курс із вашої основної системи (сайт на Magento, OpenCart, 1С, самописна CRM), де він вже заданий та використовується у всіх розрахунках;
курс із націнкою «Банк + 0.5», за яким ви купуєте валюту у постачальника.

Головне завдання цієї функції - зробити так, щоб Elbuz вважав ціни за тими ж курсами, що і ваша головна система. Щоб ніде не було розбіжностей: на сайті, в обліку та Elbuz цифри збігаються копійка в копійку.

Що ви отримуєте в результаті:

єдине джерело правди для курсів — ваше;
автоматичне оновлення без ручного введення та без помилок «забули поправити»;
миттєвий перерахунок цін у прайсах, щойно курс змінився.

Як це працює простими словами

Уявіть обмін «питання - відповідь»:

На вашому сайті лежить маленька сторінка (скрипт). Коли до неї звертаються за посиланням, вона віддає курси валют у вигляді тексту у форматі JSON.
У налаштуваннях Elbuz ви вибираєте джерело "Custom JSON URL" та вставляєте посилання на цю сторінку.
У момент оновлення Elbuz відкриває ваше посилання, читає відповідь, перераховує курси щодо своєї базової валюти та зберігає їх.

Тобто ваш сайт виступає постачальником курсів, а Elbuz — отримувачем. Все, що вам потрібно — віддавати дані у зрозумілому форматі. Про нього – нижче.

Формат файлу: що Elbuz очікує отримати за посиланням

За вказаним посиланням ваш сайт повинен повернути текст у форматі JSON зі строго певною структурою. Ось мінімальний приклад того, що має прийти у відповідь:

 { "base": "USD", "date": "2026-04-28 14:15:00", "source": "magento_1.9", "source_url": "https://moysite.com", "rates":{ "USD": 1.0, "UAH": 43.80000000, "EUR": 0.92000000 } }

Опис полів

Поле	Обов'язкове	Що означає
base	Так	Базова валюта вашого джерела – та, щодо якої пораховано всі курси. У прикладі це `USD`. Записується трилітерним кодом (USD, EUR, UAH, PLN…).
rates	Так	Перелік курсів. Це пари "код валюти → число". Число - це скільки одиниць даної валюти дорівнює одній одиниці базової валюти (Див. нижче).
date	Ні	Дата та час, на які актуальні курси. Використовується для інформації та зручності, на розрахунок не впливає.
source	Ні	Назва вашого джерела (наприклад, `magento_1.9` або `1c` ). Пояснювальне поле.
source_url	Ні	Адреса сайту-джерела. Пояснювальне поле.

Найважливіше правило про «rates»

Це місце, де найчастіше помиляються, тому розберемо окремо. Число в rates читається так:

1 одиниця базової валюти (base) = вказана кількість одиниць цієї валюти.

У нашому прикладі base - це USD, а в rates написано "UAH": 43.8. Це означає: 1 долар = 43.8 гривні. І "EUR": 0.92 значить: 1 долар = 0.92 євро.

Сама базова валюта завжди дорівнює одиниці: "USD": 1.0. Це правильно і обов'язково – залишайте її у списку.

Підказка: якщо ви вивантажуєте дані з Magento, OpenCart або 1С, там курси зберігаються рівно в цій логіці - з базової валюти в цільову. Тому формат збігається природно, нічого обчислювати вручну не потрібно.

Як Elbuz перераховує курси під себе

У вас в Elbuz є своя базова валюта (Та, що зазначена «за умовчанням»). Вона може не збігатися з базовою валютою вашого джерела – і це нормально. Elbuz уміє перераховувати через так званий крос-курс.

Логіка проста та безпечна:

Elbuz бере з вашої відповіді курс своєї базової валюти та курси решти всіх валют, які в нього заведені та включені.
Перераховує їх один щодо одного, щоб отримати курси саме до своєї базової валюти.
Базова валюта Elbuz завжди залишається рівною 1.

Єдина жорстка умова: у вашій відповіді у блоці rates обов'язково має бути присутня базова валюта Elbuz. Якщо її там немає — перерахувати курси нема від чого, і оновлення не виконається. Наприклад, якщо базова валюта в Elbuz – гривня (UAH), то rates зобов'язаний містити рядок "UAH":....

Практичний висновок: увімкніть у rates усі валюти, які ви використовуєте в Elbuz і обов'язково - базову валюту Elbuz. Зайві валюти не завадять: ті, яких немає у списку валют Elbuz, просто ігноруються.

Зіставлення йде за кодом валюти (наприклад, USD ). Якщо у валюти в Elbuz заповнений додатковий код (поле «другий код»), Elbuz спробує знайти курс і по ньому це допомагає при невеликих розбіжностях в позначеннях.

Покрокове налаштування

Крок 1. Розмістіть скрипт-розвантаження на своєму сайті

Вам потрібна сторінка на вашому сайті, яка віддає курси у форматі вище. Якщо у вас Magento 1.9 можна взяти готовий приклад (див. розділ нижче) практично без змін. Для іншої системи скрипт пишеться за аналогією: головне – щоб на виході був JSON із полями base і rates.

Рекомендуємо захистити сторінку простим ключем-токеном, щоб курси не міг запитувати будь-хто. У прикладі це параметр ?key=ВАШ_ТОКЕН.

Крок 2. Перевірте посилання у браузері

Відкрийте своє посилання у звичайному браузері, наприклад:

https://moysite.com/etrade_http_tunnel2/currency_rates_magento19.php?key=ВАШ_ТОКЕН

Ви повинні побачити на екрані цей JSON з курсами. Якщо бачите його, половина справи зроблена. Якщо ви бачите помилку або порожню сторінку — спочатку виправте скрипт, перш ніж йти далі.

Крок 3. Виберіть джерело в Elbuz

Відкрийте розділ Валюти (Список валют).
Знайдіть поле «Джерело курсів».
Виберіть варіант "Custom JSON URL (standard format)".
З'явиться поле "Custom JSON URL" - Вставте в нього своє посилання повністю (разом з токеном ?key=... ).

Налаштування зберігається автоматично, окрему кнопку не потрібно натискати.

Крок 4. Запустіть оновлення та перевірте результат

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

Порада: оновлення курсів зазвичай ставлять на регулярне автоматичне виконання (за розкладом). Тоді Elbuz «ходитиме» за вашим посиланням сам, наприклад раз на добу, і триматиме курси свіжими без вашої участі.

Готовий приклад: вивантаження курсів з Magento 1.9

Нижче – робочий приклад скрипта, який читає курси прямо з бази Magento 1.9 та віддає їх у потрібному форматі. Покладіть файл у папку на вашому сайті (наприклад, etrade_http_tunnel2/ в корені Magento) і звертайтеся до нього за посиланням з токеном.

 /etrade_http_tunnel2/) $magento_root = dirname(__DIR__); $local_xml_path = $magento_root. '/app/etc/local.xml'; header('Content-Type: application/json; charset=utf-8'); // Перевірка токена $provided_token = isset($_GET['key'])? (string)$_GET['key']: ''; if (!hash_equals($access_token, $provided_token)) { http_response_code(403); echo json_encode(['error' => 'forbidden']); exit; } // Читаємо налаштування БД Magento з local.xml $xml = simplexml_load_file($local_xml_path); $conn = $xml->global->resources->default_setup->connection; $tbl_prefix = (string)$xml->global->resources->db->table_prefix; $pdo = new PDO( 'mysql:host='. (string)$conn->host. ';dbname='. (string)$conn->dbname. PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC] ); // Базова валюта Magento $stmt = $pdo->prepare("SELECT value FROM {$tbl_prefix}core_config_data WHERE path = 'currency/options/base' AND scope = 'default' AND scope_id = 0 LIMIT 1"); $stmt->execute(); $base = $stmt->fetchColumn(); // Курси: з базової валюти у всі налаштовані $stmt = $pdo->prepare("SELECT currency_to, rate FROM {$tbl_prefix}directory_currency_rate WHERE currency_from =:base AND rate > 0"); $stmt->execute([':base' => $base]); $rates = [(string)$base => 1.0]; // базова валюта завжди = 1 foreach ($stmt->fetchAll() as $row) { $rates[$row['currency_to']] = (float)$row['rate']; } echo json_encode([ 'base' => (string)$base, 'date' => date('Ymd H:i:s'), 'source' => 'magento_1.9', 'rates' => $rates, ], JSON_UNESCAPED_SLASHES | JSON_PR

Якщо у вас не Magento, а інша система — використовуйте цей приклад як зразок: підключіться до своєї бази або API, отримайте курси та зберіть такий же масив із полями base і rates. Структура відповіді повинна залишитися такою самою.

Часті питання та вирішення проблем

Симптом	Ймовірна причина та рішення
Курси не оновилися взагалі	Перевірте посилання у браузері. Якщо сторінка недоступна, дає помилку чи порожнечу – проблема на стороні вашого скрипта. Також переконайтеся, що посилання вставлене повністю разом із токеном.
Видно помилка «forbidden» (403)	Чи не збігається токен. Перевірте, що `?key=` на засланні дорівнює токену в скрипті.
Оновлення пройшло, але курси не змінилися	Швидше за все, в `rates` немає базової валюти Elbuz, або коди валют у відповіді не збігаються з кодами Elbuz. Перевірте позначення (USD, UAH тощо).
Курси "перевернуті" (наприклад, замість 43.8 вийшло 0.022)	Порушено правило `rates`: число має означати «1 базова = N цієї валюти», а чи не навпаки. Перевірте логіку вивантаження.
Відповідь надходить не в JSON	Переконайтеся, що скрипт дає заголовок `Content-Type: application/json` і у відповіді немає зайвого тексту, попереджень PHP або HTML до/після JSON.

Коротко про головне

Ця функція перетворює будь-який ваш сайт або систему на персональне джерело курсів валют для Elbuz. Ви один раз розміщаєте простий скрипт, який віддає JSON із полями base і rates, вставляєте посилання в налаштування "Custom JSON URL" - і Elbuz починає рахувати ціни рівно за вашими курсами, оновлюючи їх автоматично. Жодного ручного введення, ніяких розбіжностей між системами.

Збережи посилання на цю сторінку

Політика конфіденційності

Завантажуйте курси валют зі свого джерела - за одним посиланням