Free library and client Postcalc Light

PostcalcLight - это библиотека для работы с Postcalc.RU и простой веб-интерфейс в одном архиве.
PostcalcLight объявляется public domain, то есть вы можете использовать его в своих проектах полностью или частично без ограничений.

Опробовать PostcalcLight в работе онлайн
Посмотреть статистику работы PostcalcLight
Скачать документацию
Документация онлайн

Библиотека легковесная, в сжатом виде - менее 30 Кб в архиве, основная функция опроса - около 60 строк кода.
Начиная с версии 2.0 (декабрь 2015 г.) база данных скачивается отдельно. Она предоставляется в двух форматах на выбор: простых текстовых файлов (аналогично версии 1.x) и дампа MySQL.

ЗАГРУЗКА

Для кодировки UTF-8:
http://www.postcalc.ru/download/PostcalcLight_UTF8.zip - последняя версия программы, 26 Кб.
http://www.postcalc.ru/download/PostcalcLight_UTF8_TXT.zip - последняя версия базы данных в формате TXT, около 640 Кб.

Для кодировки Windows-1251:
http://www.postcalc.ru/download/PostcalcLight_cp1251.zip - последняя версия программы, 24 Кб.
http://www.postcalc.ru/download/PostcalcLight_cp1251_TXT.zip - последняя версия базы данных в формате TXT, около 570 Кб.

Для любой кодировки:
http://www.postcalc.ru/download/PostcalcLight_SQL.zip - последняя версия базы данных в формате дампа MySQL, около 670 Кб.

Все приведенные выше ссылки являются символьными ссылками на самую последнюю версию программы или базы данных. При желании вы можете настроить скрипты на вашем сайте для обновления в автоматическом режиме.
Все существующие версии можно посмотреть по ссылке:
http://www.postcalc.ru/download/PostcalcLight/

Базы данных основаны на "Эталонном справочнике" Почты России:
http://vinfo.russianpost.ru/database/ops.html

Исходные базы "Эталонных справочников" Почты России обновляются 2 раза в месяц. Базы Postcalc.RU синхронизируются с этими обновлениями в автоматическом режие ежедневно. Подробно изменения можно просмотреть по ссылке.

Следует учесть, что изменения обычно не касаются реальных расчетов клиентов: обычно добавляются/изменяются технические индексы, которые используются во внутренней обработке Почты России.

По практике, достаточно синхронизировать базы один раз в месяц.

БАЗА ДАННЫХ

Какой формат выбрать (SQL или TXT) - дело больше вкуса.

Текстовые файлы не требуют дополнительной настройки и доступа к базе данных, работают сразу "из коробки".

База MySQL дает возможность интеграции с другими вашими проектами.

Вы можете просмотреть список используемых названий населенных пунктов, стран и почтовых индексов онлайн:

• Населенные пункты России.
• Почтовые индексы и названия ОПС.
• Страны.

1. Файлы в формате текста, разделенного табуляцией, и соответствующие индексные файлы:
postcalc_light_cities.txt
postcalc_light_cities.idx
postcalc_light_post_indexes.txt
postcalc_light_post_indexes.idx
postcalc_light_countries.txt

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

Для настройки пишем в конфигурационном файле postcalc_light_config.php:

 'source' => 'txt',
 'txt_dir' => __DIR__,

Если файлы баз данных находятся в том же каталоге, что и файл postcalc_light_lib.php, то параметр txt_dir можно оставить как есть, то есть __DIR__. Иначе укажите полный маршрут к ним.

2. Дамп базы данных MySQL postcalc_light.sql. Его необходимо импортировать в текущую базу данных через phpmyadmin или войти в каталог PostcalcLight и выполнить из командной строки:

mysql -uпользователь -pпароль база_данных < postcalc_light.sql 

Для настройки пишем в конфигурационном файле postcalc_light_config.php:

    'source' => 'mysql',  
    'mysql_host' => 'localhost',    // Для mysql: имя хоста
    'mysql_user' => 'testuser',     // Для mysql: имя пользователя БД
    'mysql_pass' => 'testpass',     // Для mysql: пароль пользователя БД
    'mysql_db'   => 'postcalc',     // Для mysql: имя базы данных

ИЗМЕНЕНИЯ

ВЕРСИЯ 2.0 - 25 декабря 2015.
1. Добавлены конфигурационные параметры city_as_pindex и dir_txt. Эти переменные обязательно должны присутствовать в конфигурационном файле!

2. Изменен формат баз данных - теперь это стандартный Tabbed Separated Values, который можно импортировать в БД SQL. Для баз данных postcalc_light_post_indexes.txt и postcalc_light_cities.txt генерируются индексные файлы с тем же именем и расширением .idx. Не удаляйте их и не вносите изменения в эти файлы - это приведет к сбою.

3. Удалена база данных postcalc_light_locations.txt. Поддержка названий регионов типа 'Ленинградская область' пока сохраняется на уровне API, однако в будущем может быть также прекращена. В планируемом API 2.0 будут стандартно поддерживаться либо 6-значные индексы, либо названия населенных пунктов из postcalc_light_cities.txt.

ВЕРСИЯ 2.1 - 26 января 2016.
1. Откорректирован принцип, по которому формируются названия населенных пунктов из трех частей: 3-я часть теперь строго следует официальному справочнику ОКТМО.

2. Исправлены небольшие ошибки в коде.

ВЕРСИЯ 2.2 - 28 июня 2016.

Изменения в дизайне клиента. Библиотека не изменилась.

1. Добавлен конфигурационный параметр debug. Если 1 - под таблицей с тарифами выводится полный массив ответа сервера. Переменная [_server][REMOTE_ADDR] содержит реальный IP, с которого ушел запрос клиента.

2. Добавлен конфигурационный параметр arrColumns. Можно включать/отключать вывод следующих колонок таблицы: Количество, Доставка, Ценность, Срок доставки.

3. Добавлены кофигурационные параметры skin и arrSkins. Параметр skin - выбор одной из 24 доступных тем оформления из стандартной библиотеки jQuery UI. Доступные темы можно посмотреть по ссылке:
http://jqueryui.com/themeroller/

4. Добавлен конфигурационный параметр arrParcels - список всех возможных отправлений. Чтобы ненужные виды отправлений не выводились в итоговой таблице, просто закомментируйте их в arrParcels.

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

ВЕРСИЯ 2.3 - 26 апреля 2017 г.

Если установлена библиотека PHP curl, то обращение к серверам проекта делается через нее, иначе - через функцию file_get_contents. Функция file_get_contents из-за особенностей архитектуры делает вместо одного обращения к серверу два, что увеличивает время обслуживания по логам сервера в 2 раза, а реально - примерно в 1.5 раза.

Никаких изменений в пользовательский код вносить не требуется.

ВЕРСИЯ 2.4 - 16 ноября 2017 г.

1. В таблицу postcalc_light_post_indexes добавлен условный почтовый индекс 000000, поле opsname которого содержит дату и номер "Эталонного справочника почтовых индексов ОПС" Почты России, из которого была сгенерирована данная таблица.

"Эталонный справочник" находится по ссылке:
http://vinfo.russianpost.ru/database/ops.html

2. Поле city в таблице postcalc_light_cities теперь формируется только из "Эталонного справочника почтовых индексов", без привлечения иных источников. Таким образом, произошел возврат к формату поля city, который был до версии 2.1 (январь 2016 года). В целом настоятельно рекомендуется использовать настройку по умолчанию city_as_pindex = 1.

ВЕРСИЯ 2.4.1 - 25 декабря 2019 г.

Добавлен конфигурационный параметр key (ключ запроса). Ключ необходимо получить бесплатно в Личном кабинете:
https://www.postcalc.ru/lk/

ВЕРСИЯ 2.5 - 14 марта 2020 года.

1. Добавлен конфигурационный параметр co (корпоративные клиенты). В данный момент влияет на расчеты Посылки и EMS Оптимальное.

2. Добавлен 6-й опциональный параметр функции postcalc_request() - $Box (размер коробки). Принимает значения s,m,l,xl,ng (негабарит).

ВЕРСИЯ 2.6 - 30 марта 2020 года.

1. Добавлен конфигурационный параметр p (список кодов отправлений через запятую). Например, p=bv,pv,p1,em,is,ib,ip,iem - запросить расчеты по ценной бандероли, ценной посылке, ценной посылке 1-го класса, EMS; межд. мелкий пакет, бандероль, посылка, ЕMS с товарами.

2. Добавлен конфигурационный параметр sv (опции и дополнительные услуги).

3. Добавлен конфигурационный параметр pa: если 0, то неделимое отправление, если 1, то товар можно отправить в нескольких посылках.

ВЕРСИЯ 2.7 - 31 марта 2020 года.

В интерфейс клиентской части добавлена панель "Дополнительные настройки" для задания переменных p (список отправлений), sv (список услуг), bo (размер коробки Почты России).

ОСНОВНЫЕ ВОЗМОЖНОСТИ

• Можно скачать два варианта базы данных: в формате простого текста, разделенного табуляцией, и формате дампа MySQL. По умолчанию программа настроена на базу в формате текста и работает "из коробки", без дополнительных настроек.
  Базы данных сгенерированы на основе Эталонного справочника Почты России и обновляются в автоматическом режиме.
• Проверка аргументов на правильность. Отправитель и получатель проверяются по прилагаемым базам данных в формате простых текстовых файлов: postcalc_light_post_indexes.txt и postcalc_light_locations.txt. Страна проверяется по файлу postcalc_light_сountries.txt.
• Правильное перекодирование аргументов.
• Опрос в цикле доступных серверов проекта Postcalc.RU - если один сервер недоступен, запрашивается следующий.
• Разархивирование ответа и перевод его в массив PHP.
• Кэширование правильного ответа.
• Настройка всех необходимых параметров в конфигурационном файле.
• Для дизайна была использована тема Start из стандартной библиотеки jQuery UI. При желании ее можно заменить на любую другую из 24 тем библиотеки.
• Автодополнение индекса отделения связи и местоположения для полей "Откуда" и "Куда".
• Javascript необязателен - он используется только в автодополнении и некоторых элементах дизайна.
• Ведение журнала успешных и неуспешных соединений. Скрипт postcalc_light_stat.php позволяет просматривать статистику по месяцам и дням, скрипт postcalc_light_view_log.php - журналы (они разбиты по месяцам).
  Если число ошибок превышает 10, на контактный email отсылается извещение (параметр error_log_send).

ИСПОЛЬЗОВАНИЕ

1. Разархивируйте PostcalcLight_UTF8.zip или PostcalcLight_cp1251.zip в каталог веб-сервера.

2. Настройте базу данных.

Если вы предпочитаете работать с базой в формате текстовых файлов, разархивируйте содержимое PostcalcLight_UTF8_TXT.zip или PostcalcLight_cp1251_TXT.zip в тот же каталог.

Если вы выбрали работу с сервером MySQL, скачайте и разархивируйте PostcalcLight_SQL.zip. Затем воспользуйтесь для импорта дампа программой phpmyadmin или войдите в каталог PostcalcLight и выполните из командной строки:

mysql -uпользователь -pпароль база_данных < postcalc_light.sql 

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

3. Для проверки откройте в веб-браузере страницу /PostcalcLight/postcalc_light_test.php - она обратится к серверу Postcalc.RU, используя библиотеку PostcalcLight, и, если все в порядке, нарисует таблицу.

4. Откройте в веб-браузере страницу /PostcalcLight/postcalc_light.php - это простой клиент для работы с Postcalc.RU.

5. Окончательно настройте клиент в рабочем режиме: откройте файл postcalc_light_config.php и правильно заполните значение следующих переменных:

1. default_from - Почтовое отделение отправителя по умолчанию.
2. key - Ключ доступа. Его следует получить в Личном Кабинете. С тестовым ключом test можно сделать не более 50 запросов в сутки с одного адреса IP.

Также вы можете изменить значение других переменных запроса - их описание имеется в файле postcalc_light_config.php.

6. Следите за работой библиотеки через /PostcalcLight/postcalc_light_stat.php.