Депозитный модуль¶

CIMController является COM-объектом, обеспечивающим единообразную логику приема наличных на покупюрных и пачечных устройствах приема наличных. CIMController интегрирован с платформой ПроАТМ, в процессе своей работы осуществляет журналирование процесса приема наличных, а также формирует записи в БД транзакций приема. Наиболее полный перечень интерфейсов и классов, входящих в библиотеку типов AXCashInModule, можно получить с помощью утилиты OleView.Exe (Microsoft). В настоящем руководстве рассматриваются интерфейсы класса CIMController: ICIMController и ICIMControllerEvents.

Идентификаторы подключения¶

PROGID: AXCashInModule.CCIMController;
CLSID: 0091FC9E-E87C-4aa8-B906-4BF50F244244.

Справочные функции¶

HRESULT VersionNo( [ out, retval ] BSTR* pResult )

В текстовом виде возвращает номер сборки ПроАТМ, например, «5.7.2.20651».

HRESULT Is1NoteAcceptor( [ out, retval ] VARIANT_BOOL* pResult )

Признак устройства с покупюрным приемом.

HRESULT IsEscrowNoteAcceptor( [ out, retval ] VARIANT_BOOL* pResult )

Признак устройства с промежуточным стекером (Escrow).

HRESULT IsConjointCashIn( [ out, retval ] VARIANT_BOOL* pResult )

Признак режима непрерывного приема (conjoint).

HRESULT BanknoteTypes( [ out, retval ] IDispatch ppResult )

Перечисляет номиналы банкнот, с которыми умеет работать устройство.

Возвращает коллекцию INoteTypes, которая содержит свойства:

Length – количество элементов;
Item(n) – возвращает элемент коллекции по номеру.

Элементы коллекции имеют интерфейс INoteType и обладают ниже следующими свойствами:

NoteID – числовой идентификатор банкноты в системе XFS/CIM;
Value – номинал;
Currency – валюта, буквенный код ISO4217;
Str – строка, содержащая номинал и валюту, разделенные пробелом;
Release – номер выпуска банкноты (если устройство способно различать).

Пример javascript-кода, осуществляющего настройку разрешенных к приему индивидуальных номиналов:

 // На входе - перечень разрешенных номиналов (ключ - валюта)
 var allowedNotesForTheTransaction = {
         "RUB" : [ 50, 100, 500, 1000 ]
 };

 // На выходе - перечень вендор-зависимых идентификаторов к использованию
 // (на разных моделях/версиях прошивок ДМ, имеют различные значения)
 var allowedNoteIDs = new Array();

 // Функция преобразования номиналов ISO4217 в вендор-зависимые идентификаторы
{
         var noteTypesCollection = cimCtrl.BanknoteTypes;
         for( i = 0; i < noteTypesCollection.Length; ++i ) {

         var noteType = noteTypesCollection.Item( i );
         var allowedValues = allowedNotesForTheTransaction[ noteType.Currency ];
                 if( typeof allowedValues === 'undefined' ) {
                         continue;
                 }

                 if( allowedValues.indexOf( noteType.Value ) != -1 ) {
                         allowedNoteIDs.push( noteType.NoteID );
                 }
         }
}

 // Разрешаем прием
 cimCtrl.AllowedXfsNoteIDs = allowedNoteIDs.toString();

HRESULT EscrowCapacity( [ out, retval ] ULONG* lpResult )

Физическая емкость временного накопителя. На купюроприемниках равна единице.

Методы¶

Подготовка к приему¶

Прежде чем начать транзакцию приема наличных, необходимо выполнить предварительные настройки, описанные ниже. Настройки выполняются в условиях закрытой транзакции приема наличных. Если транзакция не завершена – ее следует завершить путем остановки приема и подачи AsyncCommit, AsuncRefund или AsyncRetract.

HRESULT AllowedXfsNoteIDs( [ in ] BSTR bstrXfsNoteIDs )

Установить перечень разрешенных банкнот для предстоящей транзакции приема наличных. Указываются идентификаторы банкнот в системе XFS/CIM, разделенные запятой.

Внимание

Идентификаторы банкнот зависят от конкретной модели ДМ, а также от установленной прошивки. Информацию о действующих идентификаторах следует запрашивать через свойство BanknoteTypes.

HRESULT AllowedCurrency( [ in ] BSTR bstrCurrencyId )

Альтернативный вариант – установить перечень разрешенных банкнот одной валюты для предстоящей транзакции приема наличных. Буквенный идентификатор ISO4217.

Примечание

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

HRESULT IsOperatingCycleOpened( [ out, retval ] VARIANT_BOOL* pResult )

Проверить, открыт ли ОЦ депозитного модуля. Если ОЦ закрыт, то прием запрещен, попытка исполнить StartTransaction будет завершена с ошибкой.

HRESULT ModuleId( [ out, retval ] ECimModuleId* pEnModuleId ), HRESULT ModuleId( [ in ] ECimModuleId enModuleId )

Установить или прочитать идентификатор клиентского модуля, в адрес которого осуществляется прием наличных (отражается в статистике)

Параметр ECimModuleId – перечисление возможных значений:

MODULE_UNDEFINED = 0;
MODULE_PROSET = 1;
MODULE_MBK = 3;
MODULE_ROP = 4;
MODULE_WEB = 5.

В случае организации приема наличных через WEB-приложение, данное свойство носит формальный характер и его всегда следует устанавливать в значение 5.

HRESULT BundleId( [ out, retval ] BSTR* pbstrBundleId ), HRESULT BundleId( [ in ] BSTR bstrBundleId )

Установить идентификатор записи в БД транзакций приема наличных, предварительно созданной клиентским модулем. В случае организации приема наличных через WEB-приложение, данный шаг носит чисто формальный характер. Запись уже создана, следует указать значение auto.

HRESULT MinAmount( [ out, retval ] BSTR* pMinAmountSerialized ), HRESULT MinAmount( [ in ] BSTR minAmountSerialized )

Минимальная сумма транзакции, опциональное свойство. Если определено, то в процессе приема наличных можно поинтересоваться, было ли достигнуто указанное значение.

HRESULT MaxAmount( [ out, retval ] BSTR* pMaxAmountSerialized ), HRESULT MaxAmount( [ in ] BSTR maxAmountSerialized )

Максимально допустимая сумма транзакции, опциональное свойство. Если определено, то в процессе приема наличных можно поинтересоваться, не превысили ли указанную сумму. Кроме того, если устройство приема наличных имеет встроенную функцию работы с лимитами по сумме на аппаратном уровне (например, при обработке пачки возвращать банкноты сверх лимита), ему также будет передано это значение.

HRESULT MaxNotesCount( [ out, retval ] BSTR* pVal ), HRESULT MaxNotesCount( [ in ] BSTR val )

Максимально допустимое число банкнот за одну транзакцию приема наличных. Актуально для устройств пачечного приема. Если значение определено, то в процессе приема наличных можно поинтересоваться, не превысили ли указанный лимит. Кроме того, если устройство приема наличных имеет встроенную функцию работы с лимитами по количеству банкнот на аппаратном уровне, ему также будет передано это значение.

HRESULT OneNoteDevices_ParallelAcceptanceAllowed( [out, retval] VARIANT_BOOL* pVal ), HRESULT OneNoteDevices_ParallelAcceptanceAllowed( [ in ] VARIANT_BOOL val )

Если устройство самообслуживания оборудовано двумя и более классическими купюроприемниками (без escrow), разрешить прием одновременно через несколько устройств.

Примечание

Ограничение: все устройства должны иметь общую таблицу идентификаторов банкнот (banknote types). Данное свойство должно быть установлено прежде, чем будет вызван метод Initialize().

Управление приемом¶

HRESULT Initialize( [ in ] BSTR bstrCimInstanceName )

Инициализация контроллера, смена устройства при наличии двух и более депозитных модулей. Если значение аргумента bstrCimInstanceName пустое, выбирается устройство по умолчанию. Данный метод должен быть вызван хотя бы раз после запуска ПроАТМ. Для уверенности не будет ошибкой оставить вызов данного метода перед началом каждой транзакции приема наличных.

HRESULT Uninitialize()

Деинициализация контроллера. Однократно вызывается ПроАТМ при завершении работы ПО. В сценариях Web-приложения нет необходимость вызывать данный метод.

HRESULT StartTransaction( [ in ] VARIANT_BOOL bUseRecycleUnits, [ out, retval ] ICimOperationResult** ppRes )

Подготовка к транзакции приема наличных. Флаг bUseRecycleUnits указывает на разрешение задействовать кассеты замкнутого оборота наличных.

Внимание

Перечень разрешенных номиналов, лимиты на сумму и прочие атрибуты, представленные в разделе, должны быть сконфигурированы прежде, чем будет вызван данный метод.

Здесь и далее управляющие методы возвращают результат в виде объекта с интерфейсом ICimOperationResult:

  // ICimOperationResult
[
        object,
        uuid("E4ED7843-341E-4764-A064-3DC3D6A4EF49"),
        dual,        helpstring("ICimOperationResult Interface"),
        pointer_default(unique)
]
__interface ICimOperationResult : IDispatch
{
        [propget, id(1), helpstring("IsError - Флаг, есть ли ошибка")]
HRESULT IsError([out, retval] VARIANT_BOOL* pVal);

[propget, id(2), helpstring("ErrorType -  Тип ошибки (где она произошла)")] HRESULT ErrorType([out, retval] ECimErrorType* pVal);

[propget, id(3), helpstring("ErrorTypeStr -  Тип ошибки в виде строки (где она произошла)")]
HRESULT ErrorTypeStr([out, retval] BSTR* pVal);

[propget, id(4), helpstring("ErrorCode - идентификатор ошибки (либо перечисление ECimResult, либо идентификаторы WFS_ERR_*)")]
HRESULT ErrorCode([out, retval] VARIANT* pVal);

[propget, id(5), helpstring("ErrorCodeStr - идентификатор ошибки в виде строки (например 'WFS_ERR_API_VER_TOO_HIGH')")]
HRESULT ErrorCodeStr([out, retval] BSTR* pVal);
};

Не допускается вызов данного метода в условиях открытой транзакции приема наличных. В случае повторного вызова данного метода предусмотрено два варианта поведения CIMController:

Попытка экстренно завершить текущую транзакцию путем подачи команды складирования оставленных банкнот в сейф, в случае успеха будет открыта новая транзакция.
Возврат кода ошибки CR_TRANSACTION_ALREADY_ACTIVE (24), если в настоящий момент контроллер занимается отработкой одной из асинхронных операций: AsyncCashIn, AsyncRefund, AsyncRetract.

Ниже представлены четыре асинхронных (неблокирующих) метода, осуществляющие постановку операций приема наличных в очередь на исполнение в фоновом рабочем потоке: AsyncCashIn, AsyncCommit, AsyncRefund и AsyncRetract. В ходе исполнения данные методы могут генерировать различного рода оповещения (события). По завершении работы генерируется событие вида On<methodName>Completed, где methodName – название метода.

Если в настоящий момент контроллер занят выполнением предыдущего асинхронного метода, запрос ставится в очередь и будет запущен на исполнение после отработки текущего.

Если контроллер отказывает в постановке запроса в очередь, возвращается ошибка через выходную переменную ppRes.

Для двух асинхронных методов предусмотрены методы асинхронной отмены. Вызов данных методов приводит к подаче сигнала отмены в исполняющий модуль. Если это технически возможно, исполнение будет прервано, а целевой отменяемый метод штатно завершится с кодом WFS_ERR_CANCELED (-4).

HRESULT AsyncCashIn( [ out, retval ] ICimOperationResult** ppRes )

Запуск приема наличных. Метод является асинхронным. Этапы выполнения метода, а также результат следует отслеживать через события:

OnWaitingForNotes( [ in ] ULONG ulMaxBundleSize ) – ожидается вставка банкнот.
OnProcessingNotes() – осуществляется обработка банкнот.
OnInputRefuse( [ in ] VARIANT fwXfsReason ) – в процессе обработки обнаружены отвергнутые банкноты, которые позже будут возвращены.
OnWaitingForRefusedNotesTobeTaken( [ in ] long nNotesCount ) – отвергнутые банкноты возвращены, ожидается их изъятие клиентом.
OnItemsTaken() – банкноты забраны.
OnDoUpdateAmount() – обработка банкнот завершена, сумма банкнот во временном накопителе изменилась. Для получения обновленной суммы предлагается воспользоваться свойством AcceptedL4Notes.
OnCashInCompleted( [ in ] ULONG hResult ) – операция завершена с передачей кода завершения (XFS/CIM).

HRESULT AsyncCancelCashIn( [ out, retval ] ICimOperationResult** ppRes )

Затребовать отмену приема наличных. После успешного останова будет вызван обработчик OnCashInCompleted() с кодом WFS_ERR_CANCELED. Если обработка банкнот уже началась, данное управляющее воздействие будет проигнорировано. Данный метод не является асинхронным.

HRESULT AsyncRefund( [ out, retval ] ICimOperationResult** ppRes )

Запуск процедуры возврата банкнот из временного накопителя. Метод является асинхронным. Этапы его выполнения, а также результат следует отслеживать через события:

OnNotesReturning() – осуществляется возврат банкнот;
OnWaitingForReturnedNotesTobeTaken() – ожидается изъятие возвращенных банкнот. Внимание! Некоторые устройства допускают возврат содержимого временного накопителя в несколько приемов. После данного события может снова поступить событие OnNotesReturning() – будет означать, что осуществляется возврат следующей порции;
OnNotesRetracting() – в случае подачи асинхронной отмены с предписанием удержать банкноты на хранение, будет сгенерировано данное событие.

HRESULT AsyncCancelRefund( [ in ] RefundCancellationAction cancellationAction, [ out, retval ] ICimOperationResult** ppRes )

Затребовать отмену ожидания изъятия возвращенных наличных. Параметр cancellationAction предписывает, как поступить с незабранными наличными:

enum RefundCancellationAction {
        RTA_LEAVE = 1,               // Оставить банкноты на позиции возврата
        RTA_RETRACT = 2,             // Поместить в Retract-кассету
        RTA_REJECT = 3,              // Поместить в Reject-кассету
        RTA_ESCROW = 4,              // Поместить в ESCROW
        RTA_TRANSPORT = 5,           // Поместить на транспортные пути
        RTA_BILLCASSETTES = 6,       // Поместить в кассеты приема
};

Если после подачи данной команды клиент успеет забрать банкноты, возврат наличных будет считаться выполненным успешно.

HRESULT AsyncCommit( [ out, retval ] ICimOperationResult** ppRes )

Запуск процедуры складирования банкнот из временного накопителя в кассеты. Метод является асинхронным. После завершения работы генерируется событие OnCommitCompleted( [ in ] ULONG hResult ) с передачей кода завершения (XFS/CIM).

Внимание

Запрещено выполнять расходные операции или закрытие транзакции приема наличных в системе WebApp до тех пор, пока не будет выполнена отработка данного метода (т.е. после додачи AsyncCommit и до получения OnCommitCompleted).

HRESULT AsyncRetract( [ out, retval ] ICimOperationResult** ppRes )

Запуск процедуры удержания банкнот на хранение. Задержание можно выполнить как с выходной позиции, так и из временного накопителя. Метод является асинхронным. После завершения работы генерируется событие OnRetractCompleted( [ in ] ULONG hResult ) с передачей кода завершения (XFS/CIM).

Статусы и состояние¶

Ниже приводится перечень свойств и методов, позволяющих отследить статусную информацию в ходе и после завершения транзакции приёма наличных.

HRESULT LastTransactionCertificate( [ out, retval ] BSTR* pbstrCertificate )

Получить сертификат (формат: [0-7][0-9A-F]{7}) последней (текущей или завершённой) транзакции приёма наличных. Является уникальным идентификатором в пределах данного устройства самообслуживания и может быть использован в качестве ключа поиска наравне с идентификатором транзакции приёма наличных bundle_id.

HRESULT HasMoneyEscrowed( [ out, retval ] VARIANT_BOOL* pHasMoneyEscrowed )

Проверить, есть ли во временном накопителе банкноты.

HRESULT TransactionStatus( [ out, retval ] CashInTransactionStatus* pResult );[Get]

Получить статус текущей транзакции приёма наличных. Перечисляемый тип CashInTransactionStatus описывается следующим образом:

enum CashInTransactionStatus
{
        TS_ACTIVE = 0,                               // Транзакция активна

        TS_COMMITTED = 1,                            // Транзакция завершена

        TS_LEFT_ON_REFUSE_POSITION = 2,              // Транзакция прервана на этапе
// возврата отвергнутых банкнот

        TS_REFUNDED = 3,                             // Транзакция отменена, ден.средства
// (если были) возвращены

        TS_LEFT_ON_REFUND_POSITION = 4,              // Транзакция отменена, возвращенные
// ден.средства остались на позиции
// выдачи

        TS_RETRACTED = 5,                            // Транзакция отменена, забытые
                                                        // ден.средства задержаны на хранение

        TS_UNKNOWN = 6                               // Во время выполнения транзакции
// приёма произошла ошибка (либо после
// инициализации и до запуска новой
// транзакции)
};

HRESULT IsTransactionActive( [ out, retval ] VARIANT_BOOL* pResult )

Проверить, что транзакция приёма активна и ожидает завершения.

HRESULT IsEscrowFull( [ out, retval ] VARIANT_BOOL* pResult )

Проверить временный накопитель на достижение предельной ёмкости. Если истина, то дальнейшее внесение денежных средств в рамках текущей транзакции невозможно. Возможные действия: складирование в сейф, возврат, удержание на хранение.

HRESULT DeviceStopFlag( [ out, retval ] VARIANT_BOOL* pResult )

Дальнейший приём невозможен по причине ошибки устройства.

HRESULT AcceptedL4Notes( [ out, retval ] INoteNumbers** ppResult )

Получить сведения о принятых или складированных в сейф банкнот (в зависимости от фазы транзакции).

INoteNumbers является коллекцией элементов, содержащих сведения о том, какие номиналы и в каком количестве были приняты.

Коллекция INoteNumbers предоставляет свойства:

Length – количество элементов;
Item( n ) – возвращает элемент коллекции по номеру.

Элементы коллекции INoteNumbers имеют интерфейс INoteNumber и обладают ниже следующими свойствами:

Count – количество банкнот данного номинала;
Amount – сумма банкнот в основных единицах валюты;
Value – номинал банкнот;
Currency – валюта, буквенный код ISO4217;
NoteID – числовой идентификатор банкноты в системе XFS/CIM;
NoteRelease – номер выпуска банкноты (если устройство способно различать).

Коллекция INoteNumbers предоставляет дополнительные методы:

MergeReleases() – объединяет записи о разных релизах одного и того же номинала в одну запись путём суммирования счётчиков банкнот, таким образом, чтобы упростить дальнейшую работу с коллекцией. Может потребоваться на устройствах, которые на уровне XFS API различают релизы одного и того же номинала.

Группа методов, обеспечивающих поучение итоговых сумм по валютам (если к приёму разрешены банкнот одной валюты – возвращается только одна сумма):

AmountsCount( [out, retval] long* pVal ) – количество сумм
GetAmount( [in] VARIANT index, [out, retval] IAmount pVal )** – получить сумму с индексом index [0 .. N - 1], где N – результат, возвращаемый AmountsCount(). Объект IAmount содержит два свойства:
- Currency – трёхбуквенный код валюты ISO4217;
- Amount – сумма в минорных единицах валюты (копейки, центы и т.п.).

Пример использования:

var acceptedNoteNumberList = cimCtrl.AcceptedL4Notes;
for( var i = 0; i < acceptedNoteNumberList.AmountsCount(); ++i ) {
        var amount = acceptedNoteNumberList.GetAmount( i );
        alert( amount.Amount + ' ' + amount.Currency );
}

Примечание

В CIMController ведется учет принятых подозрительных L3 и фальшивых L2 банкнот. Однако на практике такая обработка устройствами приема наличных чаще всего не поддерживается (исключение составляет ряд европейских стран, подчиняющихся требованиям ЕЦБ, который вынуждает банки изымать из оборота фальшивые и подозрительные банкноты на устройствах самообслуживания).

HRESULT RefusedNotesCount( [ out, retval ] ULONG* lpResult )

Число отвергнутых за текущую транзакцию приема наличных банкнот.

HRESULT RefundedNotes( [ out, retval ] INoteNumbers** ppResult )

Перечень возвращенных (по команде Refund) банкнот. Может отличаться от перечня принятых, если устройство в рамках отработка параграфа 6 правил ЕЦБ осуществляет удержание фальшивых и подозрительных банкнот. Пустой, если возврата в рамках транзакции не было.

HRESULT RetractedNotes( [ out, retval ] INoteNumbers** ppResult )

Перечень удержанных на хранение (по команде Retract) банкнот. Может отличаться от перечня принятых или возвращенных, если перед удержанием клиент отщипнет из пачки часть банкнот (при улови, что устройство пересчитывает банкноты перед их удержанием).

HRESULT RetractedListBasedOnRecalcInfo( [ out, retval ] VARIANT_BOOL* pResult )

Флаг состоявшегося пересчета при удержании банкнот. Если ложь, то пересчета не было.

HRESULT DisputedNotes( [ out, retval ] INoteNumbers** ppResult )

Спорные банкноты в рамках транзакции, которая завершилась ошибкой. Как правило, такие банкноты возникают на купюроприемниках, где после распознавания клиент по-прежнему имеет теоретический доступ к еще не складированной банкноте (привязанная леска или скотч).

HRESULT IsMinAmountSatisfied( [ out, retval ] VARIANT_BOOL* pResult )

Флаг, сигнализирующий о том, что требование к минимальной сумме внесенных наличных удовлетворено.

HRESULT IsMaxAmountReached( [ out, retval ] VARIANT_BOOL* pResult )

Флаг, сигнализирующий о том, что во временном накопителе находится сумма, равная предельно допустимой для текущей транзакции.

HRESULT IsMaxAmountOverrun( [ out, retval ] VARIANT_BOOL* pResult )

Флаг, сигнализирующий о превышении предельно допустимой суммы для текущей транзакции. Возникает на пачечных устройствах, не поддерживающих учет максимальной суммы при обработке пачки.

HRESULT IsMaxNotesCountReached( [ out, retval ] VARIANT_BOOL* pResult )

Флаг, сигнализирующий о том, что во временном накопителе находится предельно допустимое для данной транзакции число банкнот.

HRESULT IsMaxNotesCountOverrun( [ out, retval ] VARIANT_BOOL* pResult )

Флаг, сигнализирующий о превышении предельно допустимого количества банкнот, установленного для текущей транзакции. Возникает на пачечных устройствах, не поддерживающих ограничение по числу банкнот при обработке пачки.

Особенность работы с купюроприемником¶

Не поддерживается возврат пачки, набранной в ходе транзакции (операция Refund).

Ввиду отсутствия временного накопителя банкноты по одной поступают сразу же в кассету, поэтому всякий раз, когда в настоящем документе упоминается временный накопитель, применительно к купюроприемнику следует рассматривать именно кассету приема наличных.

Операции Commit и Retract носят формальный характер, поскольку банкноты уже находятся в кассете, то всегда завершаются успешно. Разница лишь в том, к какому разделу статистики будет отнесена принятая сумма: к успешно принятым или задержанным на хранение.

Поддержка лимитов по верхней границе. Если превышено максимальное число банкнот, то CIMController перестанет принимать банкноты и будет выводить соответствующий признак превышения лимита. Если очередная распознанная банкнота даст сумму, превышающую установленный лимит, то данная банкнота будет автоматически возвращена.

На покупюрных устройствах приема, после обработки очередной банкноты (успешная отработка AsyncCashIn() ) рекомендуется автоматически приступать к приему следующей, тогда как на пачечных устройствах предпочтительнее выводить результат обработки банкнот и давать на выбор: дополнительное внесение, возврат или зачисление.

Депозитный модуль¶

Идентификаторы подключения¶

Справочные функции¶

Методы¶

Подготовка к приему¶

Управление приемом¶

Статусы и состояние¶

Рекомендации по обработке ошибок¶

Особенность работы с купюроприемником¶