Как преобразовать числовую дату из API эквайринга Сбербанка (Unix Timestamp) в формат 1С

При интеграции 1С с внешними сервисами, такими как интернет-эквайринг Сбербанка, разработчики часто сталкиваются с ситуацией, когда вместо привычной строки с датой API возвращает длинное число, например, 1580977931223. Разберем подробно, что это за формат, как правильно перевести его в понятную дату 1С и какие нюансы при этом стоит учитывать.

Выясняем причину: что такое Unix-время в миллисекундах

Число, которое вы получаете в ответе JSON от шлюза Сбербанка, является так называемым Unix-временем (или POSIX-временем). В классическом понимании это количество секунд, прошедших с полуночи (00:00:00 UTC) 1 января 1970 года. Однако современные банковские системы и языки программирования (особенно на базе Java) используют расширенный стандарт — количество миллисекунд с той же даты.

Проанализируем структуру полученного числа 1 580 977 931 223:

1. Первые 10 знаков (1580977931) — это количество полных секунд.
2. Последние 3 знака (223) — это миллисекунды.

Поскольку встроенный тип данных Дата в 1С:Предприятие 8 поддерживает точность только до секунды, при конвертации дробную часть (миллисекунды) мы будем отсекать.

Алгоритм преобразования числа в дату 1С

Для того чтобы получить корректный объект типа Дата, нам необходимо взять «точку отсчета» (эпоху Unix) и прибавить к ней количество секунд, полученное из API. Рассмотрим, как это реализовать программно.

Посмотрим на пример кода, который выполняет это преобразование:

// Предположим, значение получено из JSON в переменную ЧисловаяДата
ЧисловаяДата = 1580977931223; 

// 1. Переводим миллисекунды в секунды
КоличествоСекунд = ЧисловаяДата / 1000;

// 2. Прибавляем секунды к базовой дате 01.01.1970
ДатаРезультат = '19700101' + КоличествоСекунд;

// 3. Выводим результат
Сообщить(ДатаРезультат); // Получим дату в формате UTC

В данном примере мы используем особенность 1С: при сложении объекта типа Дата и числа, система интерпретирует число как количество секунд, которое нужно добавить к дате.

Учет часового пояса (UTC vs Локальное время)

Важно помнить, что API Сбербанка возвращает время в формате UTC (универсальное координированное время). Если ваш бизнес-процесс требует отображения времени по Москве или другому местному времени, результат необходимо скорректировать. Рассмотрим два способа:

1. Использование функции МестноеВремя: Эта функция преобразует время из UTC в локальное время сервера, на котором выполняется код, основываясь на настройках операционной системы.

// Правильный способ с учетом локальных настроек сервера
ДатаUTC = '19700101' + (ЧисловаяДата / 1000);
ДатаЛокальная = МестноеВремя(ДатаUTC);

1. Ручное смещение: Если сервер находится в одном часовом поясе, а учет ведется в другом (например, Москва UTC+3), можно добавить смещение вручную в секундах.

СмещениеМСК = 3 * 3600; // 3 часа по 3600 секунд
ДатаМСК = ('19700101' + (ЧисловаяДата / 1000)) + СмещениеМСК;

Разбор ответа JSON и обработка типов данных

При работе с getOrderStatusExtended или аналогичными методами, данные обычно приходят в виде строки JSON. Разберем по шагам, как правильно извлечь и обработать это поле, чтобы избежать ошибок приведения типов.

// Пример обработки ответа от API
Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(ТекстОтветаОтСбербанка);
СтруктураОтвета = ПрочитатьJSON(Чтение);

Если СтруктураОтвета.Свойство("date") Тогда
    ЗначениеДаты = СтруктураОтвета.date; // Здесь может быть Число или Строка
    
    // Приводим к числу на случай, если API вернуло строку
    ЧисловаяДата = Число(ЗначениеДаты); 
    
    // Проверяем длину числа (10 знаков - секунды, 13 знаков - миллисекунды)
    Если ЧисловаяДата > 10000000000 Тогда
        СекундыДляДобавления = ЧисловаяДата / 1000;
    Иначе
        СекундыДляДобавления = ЧисловаяДата;
    КонецЕсли;
    
    ДатаЗаказа = '19700101' + СекундыДляДобавления;
КонецЕсли;

Особенности различных полей даты в Сбербанке

В документации Сбербанка могут встречаться разные поля. Проанализируем ситуацию, чтобы не перепутать время события:

• date — обычно это время регистрации заказа в системе платежного шлюза. Оно может не совпадать с временем фактической оплаты.
• authDateTime — время авторизации платежа (когда банк подтвердил наличие средств).
• actionDate — дата и время совершения последней операции по заказу.

Важный нюанс: В некоторых версиях API формат полей может различаться. Поле date чаще всего передается как Long (число), а authDateTime может прийти в виде отформатированной строки "2023-10-27 14:20:00". Перед обработкой всегда проверяйте тип данных через функцию ТипЗнч() или используйте универсальный парсер.

Резюме для разработчика

Для корректной работы с датами интернет-эквайринга Сбербанка в 1С:

1. Всегда делите полученное 13-значное число на 1000, чтобы получить секунды.
2. Используйте базовую дату '19700101' для расчетов.
3. Не забывайте про часовой пояс — банковские системы работают в UTC.
4. Помните, что 1С не хранит миллисекунды в типе Дата. Если они критичны для логов, сохраняйте исходное число в отдельный реквизит документа или справочника с типом Число(15,0).

Использование этих простых правил позволит избежать ошибок при синхронизации оплат и обеспечит корректное отображение времени транзакций в вашей информационной базе.