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

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

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

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

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

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

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

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

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

Все дальнейшие примеры будут описывать шаблоны загрузки только реестров платежей. Шаблоны реестров расходов идентичны шаблонам платежей с точностью до слова payment в начале каждой строки (для расходов следует писать charge, например charge.load.pattern.1=Новый шаблон) и до указания типа payment_type (следует писать charge_type). Нумерация шаблонов расходов независима от нумерации шаблонов платежей (т.е. может быть как шаблон платежа, так и шаблон расхода с номером 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_comment=<Позиция комментария платежа>
payment.load.pattern.<id>.position_id=<Позиция уникального идентификатора>
payment.load.pattern.<id>.position_date=<Позиция даты>
payment.load.pattern.<id>.date_format=<Формат даты платежа>

Где:

  • Строка замен - несколько записей вида {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 (код договора), contracts (название договора), 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%*.

     Пример шаблона 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
 Пример шаблона 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
 Пример шаблона 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%
 Пример шаблона 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

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

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

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

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

Загрузка платежей

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

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

Лог загрузки реестра
Выделенные платежи

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

Автоматическая загрузка реестров платежей

Для настроенных шаблонов реестров платежей возможна автоматическая загрузка по планировщику.

Работает ТОЛЬКО для загрузки платежей.

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

report.mail=<E-Mail адрес, на который высылать ошибки разбора реестров>
load.from.dir=<полный путь к каталогу, из которого загружаются реестры>
processed.to.dir=<полный путь к каталогу, в который перемещаются обработанные реестры>

Все возможные типы файлов-реестров должны быть описаны следующим образом, <id> - уникальный для каждого типа файла код.

filetype.<id>.load_pattern=<Код шаблона загрузки>
filetype.<id>.name_pattern=<REGEXP имени файла>

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

filetype.<id>.date_format=<формат даты>
filetype.<id>.position_date=<номер группы в REGEXP имени файла, где записана дата>

В данном примере имена реестров представляют из себя файлы вида TNEyyyMMdd.DBF:

report.mail=shamil@avantis.ru
load.from.dir=/home/shamil/tmp/payments
processed.to.dir=/home/shamil/tmp/payments/processed
filetype.1.load_pattern=3
filetype.1.name_pattern=TNE(\d{8})\.DBF
filetype.1.date_format=yyyyMMdd
filetype.1.position_date=1