☰

Бесплатная библиотека и клиент Postcalc Light

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

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

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

Внимание! С 2021 года для интеграции с собственными проектами рекомендуется использовать не таблицы PostcalcLight, а таблицы, которые находятся в зоне загрузки для разработчиков. Они содержат дополнительные поля (в частности, географические координаты и адрес ОПС), а Эталонный справочник ОПС является официальной базой данных Почты России, которая обновляется два раза в месяц и гарантирует актуальность почтовых индексов.

ЗАГРУЗКА

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

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

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

При желании вы можете настроить скрипты на вашем сайте для обновления в автоматическом режиме.
Базы данных основаны на "Эталонном справочнике" Почты России:
https://www.pochta.ru/support/database/ops

Исходные базы "Эталонных справочников" Почты России обновляются 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: имя базы данных

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

Можно скачать два варианта базы данных: в формате простого текста, разделенного табуляцией, и формате дампа 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 и правильно заполните значение следующих переменных:

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

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

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

ИЗМЕНЕНИЯ

ВЕРСИЯ 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 (размер коробки Почты России).