Небольшой класс для быстрого и удобного получения данных с сайта украинской службы доставки «Нова Пошта». Отлично подойдет для встраивания в движок собственного сайта или модуля для CMS.

Не является официальным продуктом компании!

• Поиск отделения по его адресу, городу или области.
• Поиск ближайшего отделения по указанному адресу.
• Получение статуса доставки по номеру накладной.

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

Использование начинается с создания экземпляра класса:

require 'Novaposhta.php';
$NP = new Novaposhta();

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

$config = array(
    'cacheFile' => '/path/to/cachefile',
    'cacheExpire' => 7 * 24 * 3600 // 1 неделя
);

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

Список всех отделений можно получить так:

$NP->getAllOffices();

Каждое отделение представлено в виде ассоциативного массива следующего вида:

array (
    'id' =>      '', //Идентификатор
    'link' =>    '', //Ссылка на страницу отделения на сайте Новой Почты
    'name' =>    '', //Номер отделения
    'address' => '', //Адрес
    'phone' =>   '', //Номер телефона
    'city' =>    '', //Город
    'region' =>  ''  //Область
);

Можно ограничить количество возвращаемых отделений, для этого есть два отдельных метода:

1. Чтобы получить отделение, зная его идентификатор, используется

   $NP->getOfficeById($id);

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

   $NP->getOfficesBy($field, $value);

   где $field это ключ массива (city, region и т.д.), а $value - его значение. Например, все отделения Киева можно получить так

   $NP->getOfficesBy('city', 'Киев');

   Так как все данные находятся в кодировке UTF-8, то значение $value тоже должно быть в ней.

Для того, чтобы получить 5 ближайших отделений Новой Почты к какому-либо адресу, можно воспользоваться следующим методом:

$NP->getClosestOffices($address);

где $address - строка вида "Киев, Хрещатик", также в кодировке UTF-8.

Чтобы получить информацию о состоянии доставки, зная номер накладной, достаточно будет вызвать соответствующий метод:

$NP->getDeliveryStatus($ttn);

где $ttn это и есть номер накладной.

Ответом на такой запрос будет массив с описанием состояния доставки, либо строка с сообщением об ошибке.

Если смотреть статус на сайте Новой Почты, то там он представлен в виде сводной таблицы. Каждая строка этой таблицы преобразовывается в массив вида:

array (
    'caption'    => '', //Заголовок сообщения
    'message'    => '', //Текст сообщения
    
    //Необязательный элемент. Присутствует только когда в message упоминается какое-либо отделение
    'ref_office' => ''  //упоминаемое отделение
);

Больше примеров в файле example.php.

Данные, предоставляемые данным классом, получаются с помощью парсинга страниц сайта Новой Почты. Т.е. класс самым прямым образом привязан к текущей верстке и при смене дизайна просто перестанет работать. Поэтому использовать следует на свой страх и риск.