Форматирование цены и валюты в Битрикс: CCurrencyLang и Sale

В карточке товара, письме и чеке цена должна выглядеть одинаково: разрядность, символ валюты, пробелы. В Битрикс для этого есть CCurrencyLang::CurrencyFormat и обёртки модуля Sale — не собирайте строку через number_format и ручной «₽».

Ниже — рабочие варианты для каталога, заказа и писем, плюс типичные грабли с округлением и мультивалютностью.

Базовый формат через Currency

<?php
\Bitrix\Main\Loader::includeModule('currency');

$price = 12990.5;
$currency = 'RUB';

// учитывает шаблон валюты из настроек (символ, позиция, десятичные)
echo \CCurrencyLang::CurrencyFormat($price, $currency);
// например: 12 990,50 ₽

Шаблон берётся из настроек валюты в админке. Меняете формат один раз — меняется вывод везде, где зовёте CurrencyFormat.

Цена позиции заказа (Sale)

<?php
use Bitrix\Sale\Order;
use Bitrix\Main\Loader;

Loader::includeModule('sale');
Loader::includeModule('currency');

$order = Order::load($orderId);
$currency = $order->getCurrency();

foreach ($order->getBasket() as $item) {
    $sum = (float)$item->getFinalPrice(); // цена * количество с учётом округления корзины
    $formatted = \CCurrencyLang::CurrencyFormat($sum, $currency);
    // в шаблон письма / печати
}

Для одной единицы смотрите getPrice(), для итога строки — getFinalPrice(). Не смешивайте: в письме «итог по позиции» почти всегда Final.

Каталог: цена из PriceTable / GetOptimalPrice

<?php
\Bitrix\Main\Loader::includeModule('catalog');
\Bitrix\Main\Loader::includeModule('currency');

$optimal = \CCatalogProduct::GetOptimalPrice($productId, 1, $USER->GetUserGroupArray());
if (!$optimal || empty($optimal['RESULT_PRICE'])) {
    return;
}

$price = (float)$optimal['RESULT_PRICE']['DISCOUNT_PRICE'];
$currency = (string)$optimal['RESULT_PRICE']['CURRENCY'];

echo \CCurrencyLang::CurrencyFormat($price, $currency);

Если цена уже в другой валюте заказа — конвертируйте через CCurrencyRates::ConvertCurrency до формата, иначе получите «красивую» строку в неверной валюте.

Без HTML-сущностей (для JSON/API)

<?php
$html = \CCurrencyLang::CurrencyFormat(1000, 'RUB'); // может вернуть &nbsp; и ₽
$plain = html_entity_decode(str_replace('&nbsp;', ' ', $html), ENT_QUOTES | ENT_HTML5, 'UTF-8');
// для REST/мессенджеров удобнее plain

Типичные ошибки

• number_format($price, 2, ',', ' ') . ' руб.' — ломает единый стиль и игнорит настройки валюты.
• Форматируют до скидки, а в корзине показывают после — расхождение на витрине и в чеке.
• Забывают Loader::includeModule('currency') в агенте/cron — фатал или пустая строка.
• Отдают HTML-строку в JSON без decode — в приложении видны  .

Связанные темы: ошибки сервисов через Result/Error, даты заказа — DateTime D7.

Вывод

Для вывода цены в Битрикс достаточно CCurrencyLang::CurrencyFormat и явной валюты заказа/каталога. Один API — меньше сюрпризов в письмах, печати и карточках. Ручной number_format оставляйте только если сознательно уходите от настроек валют.