Может использоваться как протокол обмена между внешними программами по приёму платежей и сервером биллинга. Загрузка производится из текстового, либо DBF-файла. Менеджер загрузки расположен в меню .
Загрузка платежей и расходов может производится из файлов различных форматов. Для каждого формата файла должен быть определён шаблон, шаблоны загрузки платежа (расхода) описываются в конфигурации сервера биллинга (меню ).
Для загрузки строки с платежом (расходом) из файла программа выполняет следующие шаги:
Разбор строки на части (только для TXT-файлов). При этом из сплошной строки образуется , содержащая (подстроки), нумерующиеся с единицы. Очевидно, что для DBF файлов данный этап не требуется, т.к. файл изначально состоит из записей;
Вычленение из записи сумм платежей (расходов), идентификатора договора, комментария платежа (расхода), даты платежа\расхода (опционально);
Сопоставление записи договору в биллинге;
Зачисление (снятие) суммы на договор.
Каждый шаблон обозначается уникальным числовым идентификатором (<id>), он должен присутствовать в каждой строке, описывающей шаблон. Шаблоны следует нумеровать по порядку. Приведённые ниже примеры описывают шаблон с кодом 1.
Внимание
Все дальнейшие примеры будут описывать шаблоны загрузки только реестров платежей. Шаблоны реестров расходов идентичны шаблонам платежей с точностью до слова в начале каждой строки (для расходов следует писать , например ) и до указания типа (следует писать ). Нумерация шаблонов расходов независима от нумерации шаблонов платежей (т.е. может быть как шаблон платежа, так и шаблон расхода с номером 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 появилась возможность указывать в одной строке одновременно несколько сумм для разных типов платежей. Для этого в полях и нужно указывать типы платежей и позиции сумм через запятую, в правильном, соответственном порядке. Т.е. если указать и , то это будет означать, что на 2ой позиции расположена сумма с платежом типа 1, на 3ей позиции - типа 2 и т.п
В случае если тип формата определён как 1 (текстовый файл), то должен быть определён REGEXP разбития строки файла на позиции записи.
payment.load.pattern.<id>.regexp=<REGEXP>
Дополнительно для каждого шаблона могут быть определены следующие необязательные параметры:
payment.load.pattern.<id>.summa.replace=<Строка замен> payment.load.pattern.<id>.position_comment=<Позиция комментария платежа> payment.load.pattern.<id>.position_id=<Позиция уникального идентификатора> payment.load.pattern.<id>.position_date=<Позиция даты> payment.load.pattern.<id>.date_format=<Формат даты платежа>
Где:
| - несколько записей вида , разделённые вертикальной чертой; |
| - из какой позиции записи брать комментарий платежа, если параметр не указан, то комментарий - пустая строка; |
| - из какой позиции записи брать уникальный строковый идентификатор платежа. При указании данного поля загрузчик будет считать ошибочными платёж, если в уже загруженных реестрах с датой реестра в том же месяце, что и загружаемый реестр, уже есть платёж с таким идентификатором; |
| и - из какой позиции записи брать дату платежа и в каком формате она указана. Если параметры не указаны, то дата платежа равна дате реестра. |
Макрос замен используется для приведения произвольного формата суммы к виду сплошной записи с десятичной точкой в качестве разделителя, например: 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=<Метод сопоставления>
Где:
| - может принимать значения: (код договора), (название договора), (комментарий договора), (текстовый параметр договора), (параметр договора типа E-Mail), (номер карты в модуле CerberCrypt), (логин, либо алиас модуля DialUp/VoiceIP), (номер телефона модуля 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
Где:
| - список через запятую кодов групп договоров, разрешённых к поиску данным методом.Группы можно посмотреть в справочнике ; |
| - ограничение искомых договоров по их названию, следует учитывать, что используется MySQL REGEXP; |
| - преобразование идентификатора договора с помощью REGEXP-выражения. Возможно указание нескольких замен, разделённых двойной вертикальной чертой (||). Каждая замена состоит из REGEXP-шаблона, далее строка => и на что необходимо заменять шаблон. В строке-замене возможно использование макросов $0-$5, соответствующих номерам групп из REGEXP-выражения. Например при методе сопоставления LIKE (см. ранее) можно добавлять в конец строки-идентификатора "", указав в replace-параметре: |
Пример 1.6. Пример шаблона 1
Формат строки в исходном файле (разделители полей - точка с запятой). Первым идёт название договора, далее сумма платежа и комментарий. Даты платежа нет, в этом случае она равна дате реестра.
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
Пример 1.7. Пример шаблона 2
Формат строки в исходном файле (разделители полей - табуляторы). На второй позиции идёт номер телефона, на четверной - сумма платежа, на пятой - комментарий договора. Дата платежа из файла не используется.
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
Пример 1.8. Пример шаблона 3
Формат строки в исходном файле (разделители полей - точка с запятой). Первым идёт номер договора, далее сумма, комментарий договора и дата платежа. Обратите внимание, что комментарий договора может быть указан не полностью, только фамилия.
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% #
Пример 1.9. Пример шаблона 4
Загрузка производится из DBF-файла, второй столбец - дата платежа, третий - сумма, шестой - номер договора. Описание шаблона в конфигурации. Идентификация клиента производится по номеру договора.
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
Обработка платежей осуществляется на основании реестров следующим образом:
загрузка файла в реестр с проверкой ошибок формата, сопоставлением платежей договорам;
проведение реестра с начислением платежей в баланс;
откат реестра при необходимости.
Каждый реестр характеризуется датой и названием. Дата реестра устанавливается в дату платежа в случае, если дата не берётся из записи. Проведение реестра - процесс занесения приходов по разобранному реестру в договоры. Откат реестра - процесс удаления платежей, может быть полезен при ошибочном реестре.
Для загрузки реестра необходимо выбрать файл, дату реестра и шаблон для разбора. Если название реестра не указано, оно принимается равным имени файлу. После нажатия кнопки реестр отображается в таблице (фильтр по дате должен включать дату реестра) и в нижнем окне выводится лог загрузки реестра и выделенные платежи.
Для проведения реестра - выбрать строку в таблице и нажать кнопку . Для отката - также выбор строки и кнопка .