API (Application Programming Interface, интерфейс прикладного программирования) — это набор готовых методов, процедур и функций, предоставляемых сервисом «ПартПостер» для использования во внешних программных продуктах.
Web API «ПартПостер» представляет собой определенный набор HTTP-запросов, для выражения которых используется формат JSON.
Адрес API: http://api.partposter.ru/v1/
API — это REST приложение, принимающее и возвращающее данные в формате JSON. При помощи данного API можно получить список посылок, осуществлять их поиск, редактирование, а также производить расчет стоимости отправки.
Адрес интерфейса содержит номер версии. На данный момент актуальной является версия 1. Каждая версия API будт иметь уникальный адрес с указанием своего номера версии.
Более подробная информация о методах API представлена ниже.
Внимание! Если вы нашли ошибку или неточность в описании, то, пожалуйста, напишите нам об этом по электронному адресу: info@partposter.ru. Мы будем рады любым предложениям или рекомендациям по данному сервису.
Пример запроса к API, выдающего 20 посылок типа «Бандероль 1 класса, без уведомления»:
GET http://partposter.api/v1/parcels/index/?page=1&p_type=ptWrapper1c&n_type=ntNone&sort=-order_fullname&fields=id,order_fullname,order_email,order_phone&expand=sent
В данном случае, мы имеем
| Поле | Описание |
|---|---|
| GET | Тип запроса к API |
| http://partposter.api/v1 | Непосредственно адрес API, версии 1 |
| parcels | Ресурс посылок. При помощи данного ресурса можно получить доступ к базе посылок, осуществлять поиск и фильтрацию выводимых результатов |
| /index/ | Функция доступа к списку посылок |
| ?page=1 | Параметр деления на страницы |
| &p_type=ptWarpper1c | Параметр фильтра типа посылки, ptWrapper1c — тип посылки «Бандероль 1 класса» |
| &n_type=ntNone | Параметр фильтра типа уведомления, ntNone — тип уведомления «Без уведомления» |
| &sort=-order_fullname | Параметр сортировки вывода результатов. Значение -order_fullname значит, что сортировать нужно по имени получателя в обратном порядке |
| &fields=id,order_fullname, order_email,order_phone |
Поля, которые необходимо выводить в результат запроса. В данном случае выводятся Идентификатор посылки: id, ФИО получателя: order_fullname, Email получателя: order_email, Телефон получателя: order_phone. По-умолчанию выводится список наиболее популятрных полей. |
| &expand=sent | Параметр для вывода расширенных значений объекта. В данном случае — флаг отправки посылки. |
«ПартПостер» API возвращает результат ответа в формате JSON, поля ответа зависят от отправленных в запросе заголовков.
[
{
"id": 158,
"order_fullname": "Иванов Иван Иванович",
"order_email": "ivanovivan@mail.ru",
"order_phone": "+79211549865",
"sent": true
},
{
"id": 281,
"order_fullname": "Петров Петр Петрович",
"order_email": "petrovitch@yandex.ru",
"order_phone": "+79191362598",
"sent": false
},
…
]
При выдаче ошибок, API выдает соответствующий данной ошибке код статуса HTTP.
Список кодов ошибок:
| Код | Описание |
|---|---|
| 400 | Ошибочный запрос. Ошибка может возникнуть в случае, если какие-либо параметры запроса были нераспознаны. |
| 403 | Доступ запрещен. Как правило, данная ошибка возникает в случае ошибочной аутентификации. |
| 404 | Объект не найден. Запрос на неправильный URL, либо попытка обращения к несуществующему объекту. |
| 405 | Метод недоступен. Попытка обращения к неизвестному методу API. |
| 422 | Ошибка валидации данных. Возникает при указании неправильных данный в запросе на создание или изменение объекта. |
| 500 | Внутренняя ошибка сервера. При возникновении данной ошибки рекомендуется повторить запрос позднее. |
В случае ошибки, выдается объект следующего вида:
{
"error": 1,
"message": "Страница не найдена.",
"title": "Not Found",
"code": 404
}
Переменная error указывает на то, что произошла ошибка.
message — Описание возникшей ошибки.
title — заголовок ошибки.
code — код ошибки.
Для работы с API необходима аутентификация. Аутентификация осуществляется по токену. Данный токен автоматически генерируется при создании приложения в Личном Кабинете сервиса «ПартПостер» (Поле Ключ доступа к API).
Авторизационный токен передается не в GET-запросе к API, а в http-заголовке Authorization.
Пример curl:
curl --header 'Authorization: Bearer gsZ_vbPr383hkVo7aqo6IyLJxSD4zxxsu' http://api.partposter.ru/v1/parcels/index/
Пример PHP:
<?php
$accessToken = 'gsZ_vbPr383hkVo7aqo6IyLJxSD4zxxsu';
$curl = curl_init('http://api.partposter.ru/v1/parcels/index/');
curl_setopt($curl, CURLOPT_HTTPHEADER, ['Authorization: Bearer '.$accessToken]);
curl_exec($curl);
?>
В системе «ПартПостер» используется несколько типов отправлений:
| Тип | Описание |
|---|---|
| ptLetter | Письмо простое |
| ptLetter1c | Письмо 1 класса |
| ptWrapper | Бандероль простая |
| ptWrapper1c | Бандероль 1 класса |
| ptParcel | Посылка обыкновенная |
Типы уведомлений о вручении:
| Тип | Описание |
|---|---|
| ntNone | Без уведомления |
| ntSimple | Простое уведомление |
| ntRegistered | Заказное уведомление |
В системе используются следующие типы причин возврата:
| Значение | Описание |
|---|---|
| 1 | Истёк срок хранения |
| 2 | Повреждена упаковка |
| 3 | Отказ адресата |
| 4 | Адрес не существует |
| 5 | Иные обстоятельства |
GET http://partposter.api/v1/parcels/index/
Данный метод позволяет получать, осуществлять поиск и фильтрацию загруженных отправлений, а также сортировать результаты вывода.
Для поиска посылок существуют фильтры по следующим параметрам: archive, comment, cpi, id, n_type, order_email, order_fullname, order_id, order_phone, owner, p_type, payment, post_address, post_city, post_index, post_region, remote_id, value, weight.
GET http://partposter.api/v1/parcels/index/?order_fullname=Иванов&order_email=ivanov@ya.ru
Также, предусмотрен дополнительный парамерт filter, при помощи которого осуществляется поиск в следующих полях одновременно: cpi, comment, order_fullname, order_email, order_phone, post_index, post_address, post_city, post_region, remote_id.
GET http://partposter.api/v1/parcels/index/?filter=Иванов
Также, для получения определенных значений выводимых посылок существуют параметры fields и extrafields, работа которых описана в разделе «Просмотр посылки».
Для сортировки списка значений применяется параметр sort:
GET http://partposter.api/v1/parcels/index/?filter=Иванов&sort=-date
Обратите внимание, что для сортировки в обратном порядке перед полем сортировки необходимо ставить минус «-».
POST http://partposter.api/v1/parcels/create/
POST http://partposter.api/v1/parcels/list/
GET http://partposter.api/v1/parcels/view/24
Данный метод позволяет вывести список полей сохраненного отправления, где 24 — это ID посылки.
По-умолчанию выводятся следующие поля:
| Параметр | Тип | Описание |
|---|---|---|
| id | Целое число | Идентификатор отправления в системе «ПартПостер» |
| autoCpi | Булево | При создании отправления данный параметр отвечает за автоматическое создания ШПИ |
| cpi | Строка | Штрих-полосной идентификатор (ШПИ) |
| p_type | Константа | Тип отправления. (см. Типы отправлений) |
| n_type | Константа | Тип уведомления. (см. Типы уведомлений) |
| order_id | Целое число | Идентификатор посылки на удаленном сайте |
| weight | Целое число | Вес посылки в граммах |
| value | Число с пл. запятой | Оценочная стоимость (ОЦ) |
| payment | Число с пл. запятой | Сумма наложенного платежа |
| comment | Строка | Комментарий |
| date | Дата/время | Дата и время создания отправления в формате [YYYY-MM-DD HH:MM:SS] |
| order_fullname | Строка | Полное имя получателя |
| order_email | Строка | Email получателя |
| order_phone | Строка | Телефон получателя |
| post_index | Строка | Почтовый индекс получателя |
| post_address | Строка | Адрес получателя |
| post_city | Строка | город получателя |
| post_region | Строка | Область получателя |
| remote_id | Строка | Идентификатор отправления на удаленном сайте в произвольном формате |
| opis | Булево | Флаг состояния описи вложения |
| sms | Целое число | Флаг о необходимости уведомления получателя по SMS |
| shipping_cost | Число с пл. запятой | Стоимость доставки |
| index | Строка | Почтовый индекс получателя |
Ограничить список полей можно при помощи дополнительного параметра fields. Список необходимых полей указывается через запятую. Пример:
GET http://partposter.api/v1/parcels/view/24?fields=id,n_type,cpi
Помимо основных, для объекта «посылка» существуют дополнительные поля
| Параметр | Тип | Описание |
|---|---|---|
| archive | Булево | Флаг о нахождение посылки в архиве |
| return | Булево | Флаг о возврате посылки |
| return_reason | Константа | Причина возврата (см. Причины возврата) |
| return_price | Число с пл. запятой | Стоимость возврата |
| return_weight | Число с пл. запятой | Вес при возврате в граммах |
| return_date | Дата/Время | Дата/время возврата в формате [YYYY-MM-DD HH:MM:SS] |
| sent | Булево | Флаг об отправке посылки |
| sent_date | Дата/Время | Дата/время отправки в формате [YYYY-MM-DD HH:MM:SS] |
| paid | Булево | Флаг о получении оплаты посылки |
| paid_total | Число с пл. запятой | Общая сумма оплаты |
| paid_sum | Число с пл. запятой | Полученная сумма оплаты |
| paid_tariff | Число с пл. запятой | Тариф оплаты |
| paid_date | Дата/Время | Дата/время оплаты в формате [YYYY-MM-DD HH:MM:SS] |
Ограничение списка выводимых дополнительных посей осуществляется при помощи дополнительного параметра expand. Список необходимых полей указывается через запятую.
GET http://partposter.api/v1/parcels/view/24?expand=archive,sent,paid
PATCH http://partposter.api/v1/parcels/24
DELETE http://partposter.api/v1/parcels/24
POST http://partposter.api/v1/calc/tariff/
Данный метод позволяет рассчитать стоимость доставки отправления согласно тарифов «Почты России».
Расчет осуществляется от индекса почтового отделения отправителя, указанного в настройках системы.
Параметры запроса:
| Параметр | Тип | Описание |
|---|---|---|
| index | Строка | Почтовый индекс получателя |
| p_type | Константа | Тип отправления. (см. Типы отправлений) |
| n_type | Константа | Тип уведомления. (см. Типы уведомлений) |
| weight | Целое число | Вес отправления в граммах |
| value | Число с пл. запятой | Оценочная стоимость (ОЦ) отправления |
| payment | Число с пл. запятой | Наложенный платеж |
| sms_count | Целое число | Общее количество SMS-уведомлений |
POST http://partposter.api/v1/calc/formula/
Данный метод позволяет рассчитать стоимость доставки отправления согласно формуле расчета стоимости доставки, указанной в системе «ПартПостер».
Расчет осуществляется от индекса почтового отделения отправителя, указанного в настройках системы.
Параметры запроса аналогичны параметрам расчета почтового тарифа (см. Расчет почтового тарифа).
POST http://partposter.api/v1/calc/index/
Этот метод позволяет рассчитать почтовый тариф от произвольного индекса отправителя до индекса получателя.
Параметры запроса аналогичны параметрам расчета почтового тарифа (см. Расчет почтового тарифа).
В дополнение к параметрам запроса добавляется следующий параметр:
| Параметр | Тип | Описание |
|---|---|---|
| index_from | Строка | Почтовый индекс отправителя |
Скачать библиотеку: partposter.zip
Для вашего удобства мы создали специальную библиотеку на PHP для работы с сервисом «ПартПостер». В качестве инструмента для выполнения HTTP-запросов в нашей библиотеке используется Httpful, которую можно скачать по адресу: httpful.phar в виде php-архива.
Пример создания посылки при помощи библиотеки partposter.php:
<?php
require_once('./partposter.php');
$parcelId = 1024; // Внутренний ID посылки на удаленном сайте
$parcelFullname = "Иванов Иван Иванович"; // Имя клиента
$parcelEmail = "ivanych@mail.ru"; // Email клиента
$parcelPhone = "+79112381755"; // Телефон клиента
$parcelIndex = "166566"; // Почтовый индекс клиента
$parcelCity = "г. Москва"; // Город клиента
$parcelRegion = "Московская обл."; // Область
$parcelAddress = "3-я улица строителей, д. 25, кв. 12"; // Адрес клиента
$parcelComment = "Заказ №".$parcelId." (".$parcelFullname.")"; // Комментарий к посылке
$parcelOrdernum = "Заказ 1024"; // Удаленный номер заказа
$parcelType = \Partposter\ptWrapper1c; // Бандероль 1 класса
$notifyType = \Partposter\ntNone; // Тип уведомления: Без уведомления
$parcelCpi = "19660198357270"; // Прямое указание ШПИ
$parcelValue = 2000; // ОЦ: 2000 рублей
$parcelPayment = 2000; // Наложенный платеж: 2000 рублей
$shippingCost = 350; // Стоимость доставки: 350 рублей
$parcelWeight = 450; // Вес посылки: 450 граммов
$pparcel = new \Partposter\Parcel();
if (empty($parcelCpi)) {
// Если не указано $parcelCpi, тогда ШПИ будет назначен системой автоматически
$pparcel->setAutoCpi(true);
} else {
// Иначе указать ШПИ, при этом данный ШПИ будет изъят из доступных диапазонов ШПИ системы
$pparcel->setCpi($parcelCpi);
}
$pparcel->setPType($parcelType)
->setNType($notifyType)
->setOrderId($parcelId)
->setWeight($parcelWeight)
->setValue($parcelValue)
->setPayment($parcelPayment)
->setComment($parcelComment)
->setDate(date("Y-m-d H:i:s", time()))
->setOrderFullname($parcelFullname)
->setOrderEmail($parcelEmail)
->setOrderPhone($parcelPhone)
->setPostIndex($parcelIndex)
->setPostAddress($parcelAddress)
->setPostCity($parcelCity)
->setPostRegion($parcelRegion)
->setRemoteId($parcelOrdernum)
->setOpis(TRUE)
->setSMS(FALSE)
->setShippingCost($shippingCost)
->setArchive(FALSE)
->setReturn(FALSE);
// Добавляем опись товаров: Наименование, количество, цена
$pparcel->listItemsAdd("Наименование товара 1", 1, 250);
$pparcel->listItemsAdd("Наименование товара 2", 2, 150);
$pparcel->listItemsAdd("Наименование товара 3", 3, 50);
$partposter = new \Partposter\Partposter();
try {
$newParcel = $partposter->parcelsCreate($pparcel);
if (!$newParcel) {
$error = $partposter->getError();
echo "Ошибка создания посылки: ".($pparcel->getComment())." — ".($error["message"])."<br>";
} else {
echo "Посылка: «".$pparcel->getComment()."» успешно создана…<br>";
}
} catch (Exception $e) {
echo 'Ошибка: '.$e->getMessage()."<br>";
}
?>
WebHook — это механизм получения уведомлений об определенных событиях с объектами «ПартПостер»
Например, при отметке партии отправлений как «Отправленная» все входящие в партию посылки отмечаются как отправленные, проставляется дата отправки.
При импортировании почтового реестра, если система находит ШПИ посылки в реестре, то такая посылка отмечается как «Оплаченная», проставляется дата и суммы оплаты согласно реестра.
{
"tokenHash": "8d38abd5180b71cd24b0fea974c521bc",
"event": "Sent",
"class": "Parcels",
"object": {
"id": 192,
"autoCpi": false,
"cpi": "19660198354316",
"p_type": "ptWrapper1c",
"n_type": "ntNone",
…
},
}
В переменной tokenHash передается md5-hash сумма от ключа API, указанного в настройках системы.
Переменная class указывает на объект, к которому относится событие WebHook.
В переменной object находится непосредственно объект WebHook.
Переменная event указывает на событие WebHook.
Для класса Parcels существуют следующие события:
| Событие | Описание |
|---|---|
| Remove | Посылка-вложение убрана из объединяющей посылки |
| Create | Создано новое отправление |
| Return | Зарегистрирован возврат отправления |
| Update | Изменение отправления |
| Delete | Удаление отправления |
| Sent | Отправление отправлено |
| Paid | Получена оплата посылки |
Сервер, принимающий Webhook в случае успеха должен возвратить ответ с http-кодом 200. В случае получения другого кода ответа, «ПартПостер» откладывает отправку WebHook на 1 час. Если повторная попытка не удалась, отправка WebHook будет отложена на сутки. После этого WebHook будет удален из очереди, если так и не будет получен положительный ответ.