Загрузка платежей и расходов из файла

Может использоваться как протокол обмена между внешними программами по приёму платежей и сервером биллинга. Загрузка производится из текстового, либо DBF-файла. Менеджер загрузки расположен в меню Сервис=>Автоматизация=>Загрузка платежей и расходов.

Загрузка платежей и расходов может производится из файлов различных форматов. Для каждого формата файла должен быть определён шаблон, шаблоны загрузки платежа (расхода) описываются в конфигурации сервера биллинга (меню Сервис=>Настройка=>Конфигурация).

Для загрузки строки с платежом (расходом) из файла программа выполняет следующие шаги:

1. Разбор строки на части (только для TXT-файлов). При этом из сплошной строки образуется запись, содержащая позиции (подстроки), нумерующиеся с единицы. Очевидно, что для DBF файлов данный этап не требуется, т.к. файл изначально состоит из записей;

2. Вычленение из записи сумм платежей (расходов), идентификатора договора, комментария платежа (расхода), даты платежа\расхода (опционально);

3. Сопоставление записи договору в биллинге;

4. Зачисление (снятие) суммы на договор.

Каждый шаблон обозначается уникальным числовым идентификатором (<id>), он должен присутствовать в каждой строке, описывающей шаблон. Шаблоны следует нумеровать строго по порядку. Приведённые ниже примеры описывают шаблон с кодом 1.

В каждом шаблоне должны быть обязательно определены параметры:

payment.load.pattern.<id>=<Название>
payment.load.pattern.<id>.type=<Тип>
payment.load.pattern.<id>.encoding=<Кодировка>
payment.load.pattern.<id>.payment_type=<Типы платежей>
payment.load.pattern.<id>.position_sum=<Позиции сумм>

Где:

• Название - текстовая строка, обозначающая шаблон в выпадающем списке менеджера загрузки платежей
• Тип - число, определяющее тип файла. 1 - для текстового файла, 2 - DBF.
• Кодировка - кодировка файла (Cp1251, UTF-8, Cp866).
• Типы платежей - коды типов платежа, которыми вносятся платежи в договор. Лучше, если это будет не редактируемый тип. Код вы можете посмотреть в справочнике типов платежей Справочники=>Другие=>Типы платежей.
• Позиции сумм - из какой позиции записи брать суммы платежей.

Начиная с версии 4.6 появилась возможность указывать в одной строке одновременно несколько сумм для разных типов платежей. Для этого в полях payment_type и position_sum нужно указывать типы платежей и позиции сумм через запятую, в правильном, соответственном порядке. Т.е. если указать payment_type=1,2,3 и position_sum=2,3,4, то это будет означать, что на 2ой позиции расположена сумма с платежом типа 1, на 3ей позиции - типа 2 и т.п

В случае если тип формата определён как 1 (текстовый файл), то должен быть определён REGEXP разбития строки файла на позиции записи.

payment.load.pattern.<id>.regexp=<REGEXP>

Дополнительно для каждого шаблона могут быть определены следующие необязательные параметры:

payment.load.pattern.<id>.summa.replace=<Строка замен>
payment.load.pattern.<id>.position_id=<Позиция уникального идентификатора>
payment.load.pattern.<id>.position_date=<Позиция даты>
payment.load.pattern.<id>.date_format=<Формат даты платежа>
payment.load.pattern.<id>.position_comment=<Позиции комментария платежа через запятую>
payment.load.pattern.<id>.comment_delimiter=<Разделитель полей комментария>
payment.load.pattern.<id>.handler_class=<Динамический класс с реализацией интерфейса ru.bitel.bgbilling.kernel.integration.server.bean.RegisterHandler (класс реализует предварительную обработку загружаемого реестра)>

Где:

• Строка замен - несколько записей вида {REGEXP что}=>{На что}, разделённые вертикальной чертой;
• Позиции комментария платежа - из какой позиции записи брать комментарий платежа, если параметр не указан, то комментарий - пустая строка; если необходимо собрать комментарий из нескольких полей, то можно указать номера полей через запятую;
• Разделитель полей комментария - любая строка, которая будет вставлена между полями комментария. По умолчанию используется пробел.
• Позиция уникального идентификатора - из какой позиции записи брать уникальный строковый идентификатор платежа. При указании данного поля загрузчик будет считать ошибочными платёж, если в уже загруженных реестрах с датой реестра в том же месяце, что и загружаемый реестр, уже есть платёж с таким идентификатором;
• Позиция даты и Формат даты платежа - из какой позиции записи брать дату платежа и в каком формате она указана. Если параметры не указаны, то дата платежа равна дате реестра.

Макрос замен используется для приведения произвольного формата суммы к виду сплошной записи с десятичной точкой в качестве разделителя, например: 545454.55. Для приведения записи 545 454-55 к этому формату необходимо указать следующий макрос:

payment.load.pattern.<id>.summa.replace=\-=>.|\s=>

Последнее, что необходимо определить для каждого шаблона - метод сопоставления записи с договором биллинга. Для этого могут быть определены один или несколько методов поиска. По умолчанию результаты поиска по всем методам складываются, но можно соединить их условием логическое И, установив опцию:

payment.load.pattern.<id>.search.mode=and

В системе установленно жёсткое ограничение, по которому каждый тип поиска возвращает не более 10 результатов. Это реализовано в MySQL опцией LIMIT. Режимы поиска работают с учётом даты платежа, она сравнивается с периодом действия договора, логина, телефона и пр. В результаты поиска не попадают договоры, помеченные как "скрытые".

Каждый метод поиска имеет свой подход (<s_id>) в пределах шаблона. В методе поиска должны быть определены обязательно параметры:

payment.load.pattern.<id>.search.<s_id>.type=<Тип метода>
payment.load.pattern.<id>.search.<s_id>.pos=<Позиция>
payment.load.pattern.<id>.search.<s_id>.regime=<Метод сопоставления>

Где:

• Тип метода - может принимать значения: cid (код договора), contract (название договора), comment (комментарий договора), parameter (текстовый параметр договора), parameter_email (параметр договора типа E-Mail), cerbercrypt (номер карты в модуле CerberCrypt), login (логин, либо алиас модуля DialUp/VoiceIP), phone (номер телефона модуля phone);
• Позиция - из какой позиции записи брать идентификатор для данного метода поиска;
• Метод сопоставления - какое MySQL-выражение использовать для запроса поиска. 1 - "=", точное совпадение идентификатора с записью в базе; 2 - LIKE; 3 - REGEXP.

При типах метода parameter, parameter_email необходимо указание кода параметра:

payment.load.pattern.<id>.search.<s_id>.pid=<Код параметра договора>

При типах поиска, связанных с конкретным модулем (login, phone, cerbercrypt), необходимо указать код экземпляра модуля:

payment.load.pattern.<id>.search.<s_id>.mid=<Код экземпляра модуля>

Дополнительно для каждого метода поиска могут быть указаны следующие необязательные параметры:

payment.load.pattern.<id>.search.<s_id>.groups=<Группы договоров>
payment.load.pattern.<id>.search.<s_id>.pattern=<REGEXP-фильтр>
payment.load.pattern.<id>.search.<s_id>.replace=<REGEXP замены>
# Не учитывать период действия договора при поиске
payment.load.pattern.<id>.search.<s_id>.no.contract.period.check=1

Где:

• Группы договоров - список через запятую кодов групп договоров, разрешённых к поиску данным методом.Группы можно посмотреть в справочнике Справочники=>Другие=>Группы договоров;
• REGEXP фильтр - ограничение искомых договоров по их названию, следует учитывать, что используется MySQL REGEXP;
• REGEXP замены - преобразование идентификатора договора с помощью REGEXP-выражения. Возможно указание нескольких замен, разделённых двойной вертикальной чертой (||). Каждая замена состоит из REGEXP-шаблона, далее строка => и на что необходимо заменять шаблон. В строке-замене возможно использование макросов $0-$5, соответствующих номерам групп из REGEXP-выражения. Например при методе сопоставления LIKE (см. ранее) можно добавлять в конец строки-идентификатора "%", указав в replace-параметре: ..replace=.*=>$0%.

x0000;13.4;sfdsdfdsd

payment.load.pattern.1=Шаблон1
payment.load.pattern.1.type=1
payment.load.pattern.1.encoding=UTF-8
payment.load.pattern.1.payment_type=2
payment.load.pattern.1.position_sum=2
payment.load.pattern.1.regexp=(\w+);([\d\.]+);(\w+)
payment.load.pattern.1.position_comment=3
payment.load.pattern.1.search.1.type=contract
payment.load.pattern.1.search.1.pos=1
# 1 - eq, 2 - LIKE, 3 -REGEXP
payment.load.pattern.1.search.1.regime=1

2 2775102 20.07.07 147.88 Мурева Вова Витальевна г. Самара, ул Потейская д.144 кв.17

payment.load.pattern.1=Шаблон
payment.load.pattern.1.regexp=(\d+)\t(\d+)\t([\d\.]+)\t([\d\.]+)\t([а-яА-я \w]+)\t(.+)
# Позиция суммы и комментария (в комментарий идёт идентификатор платежа из файла)
payment.load.pattern.1.payment_type=2
payment.load.pattern.1.position_sum=4
payment.load.pattern.1.position_comment=1
# Метод поиска по телефону
payment.load.pattern.1.search.1.type=phone 
# Код экземпляра модуля телефонии
payment.load.pattern.1.search.1.mid=1
# В какой группе REGEXP идёт номер телефона
payment.load.pattern.1.search.1.pos=2
# Номер телефона дополняется перед поиском до E.164
payment.load.pattern.1.search.1.replace=.*=>7846$0
# ФИО
payment.load.pattern.1.search.2.type=comment
# ФИО идёт на пятой позиции файла
payment.load.pattern.1.search.2.pos=5
# Проверка ФИО+телефона
payment.load.pattern.1.search.mode=and

x0000;13-4;Иванов ;04.07.2008

payment.load.pattern.2=Шаблон2
payment.load.pattern.2.type=1
payment.load.pattern.2.encoding=UTF-8
payment.load.pattern.2.payment_type=2
payment.load.pattern.2.regexp=(\w+);([\d\,\.\s\-]+);([а-яА-Я\s]+);([\d\.]+)
payment.load.pattern.2.position_sum=2
# Преобразование суммы к нужному виду
payment.load.pattern.2.summa.replace=\-=>.|\s=>
# Дата платежа берётся из файла
payment.load.pattern.2.position_date=4
payment.load.pattern.2.date_format=dd.MM.yyyy
payment.load.pattern.2.search.mode=and
payment.load.pattern.2.search.1.type=contract
payment.load.pattern.2.search.1.pos=1
payment.load.pattern.2.search.1.regime=1
payment.load.pattern.2.search.2.type=comment
payment.load.pattern.2.search.2.pos=3
payment.load.pattern.2.search.2.regime=2
payment.load.pattern.2.search.2.replace=\s*([а-яА-Я]+)\s*=>%$1%
#

payment.load.pattern.3=Шаблон3
payment.load.pattern.3.type=2
payment.load.pattern.3.encoding=Cp866
payment.load.pattern.3.payment_type=2
payment.load.pattern.3.position_sum=3
payment.load.pattern.3.position_date=2
payment.load.pattern.3.date_format=yyyy-MM-dd
payment.load.pattern.3.search.1.type=contract
payment.load.pattern.3.search.1.pos=6
payment.load.pattern.3.search.1.regime=1

Обработка платежей осуществляется на основании реестров следующим образом:

1. загрузка файла в реестр с проверкой ошибок формата, сопоставлением платежей договорам;

2. проведение реестра с начислением платежей в баланс;

3. откат реестра при необходимости.

Каждый реестр характеризуется датой и названием. Дата реестра устанавливается в дату платежа в случае, если дата не берётся из записи. Проведение реестра - процесс занесения приходов по разобранному реестру в договоры. Откат реестра - процесс удаления платежей, может быть полезен при ошибочном реестре.

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

Для проведения реестра - выбрать строку в таблице и нажать кнопку Провести реестр. Для отката - также выбор строки и кнопка Откат реестра.