Личный кабинет позволяет: анализировать информацию об отправленном и полученном грузе; контролировать расходование средств на перевозки; формировать заявки на забор груза. Получить доступ

Описание API

На этой странице описаны способы использования функций личного кабинета клиента «ПЭК» сторонними сайтами или приложениями. Информация предназначена для разработчиков. Все возникающие вопросы по работе с API личного кабинета можно направлять по адресу: support@pecom.ru

Аутентификация

  • Для начала работы с API вам необходимо присвоить Ключ доступа. Данное действие вы можете осуществить на странице «Регистрационные данные» в разделе «Ключи API». Полученный ключ будет являться вашим паролем для доступа к API.
  • Для разных приложений (например, веб-сайт и 1С:Предприятие) рекомендуется использовать разные ключи (для сбора статистики, простоты отзыва ключа в случае его компроментации)
  • Аутентификация осуществляется c помощью Basic-аутентификации, в качестве логина необходимо использовать имя пользователя личного кабинета клиента «ПЭК», в качестве пароля — любой из активных ключей доступа.

Авторизация

  • Доступ к API обеспечивается для двух групп пользователей (анонимный доступ не поддерживается):
    • «Зарегистрированные пользователи» — все пользователи личного кабинета клиента «ПЭК» (для регистрации посетите соответствующую страницу)
    • «Сторонние неперсонифицированные приложения»
  • В документации на каждый метод указано, каким группам пользователей доступен вызов того или иного метода

История изменений

16.06.2017
  • Для метода /preregistration/submit/ добавлено необязательное поле:
    • cargos[].services.delivery.carryingDistance  — метры переноски груза
  • Для метода /cargopickup/submit/ добавлено необязательное поле:
    • services.carryingDistance  — метры переноски груза
21.03.2017
  • Изменена структура ответа метода/branches/all/ получения списка филиалов и городов: добавлен массив объектов divisions, массив warehouses перемещен на уровень ниже.
20.03.2017
03.02.2017
  • Для метода /preregistration/submit/ добавлены необязательные поля:
    • cargos[].common.volume  — объём груза
    • cargos[].common.height  — высота груза
    • cargos[].common.width  — ширина груза
    • cargos[].common.length  — длина груза
    • cargos[].common.clientPriority  — приоритет

Показать более ранние записи

Структура URL

  • API представляет собой набор методов, объединённых в группы
  • Обращение к методам API осуществляется путём отправки запроса методом POST на URL метода, который формируется следующим образом: https://kabinet.pecom.ru/api/v1/<группа>/<метод>/
  • URL https://kabinet.pecom.ru/api/v1/ является базовым и далее в документации не указывается

Список групп и методов

  • /auth/ — авторизация
    • /createkey/ — создание ключа учетной записи пользователя для сторонних приложений
    • /profiledata/ — отображение информации, хранящейся в профиле пользователя
  • /branches/ — информация о филиалах и городах
    • /all/ — список всех филиалов и городов
    • /findbytitle/ — поиск городов и филиалов по названию
    • /findbyid/ — поиск городов и филиалов по коду
  • /cargos — операции с грузами
    • /status/ — статус груза
    • /basicstatus/ — базовая информация о статусе груза
    • /details/ — детальная информация о грузе, фотографии
    • /list/ — список отправок\получений за период
  • /cargopickup/ — заявки на забор и авиаперевозку
    • /submit/ — отправка заявки
    • /status/ — получение статуса заявки на забор
  • /cargopickupnetwork/ — сетевые заявки
  • /preregistration/ — предварительное оформление
    • /submit/ — отправка заявки
  • /accountingdocuments/ — бухгалтерские документы
    • /list/ — получение списка
  • /notification/ — уведомления
    • /cargosubscribe/ — подписка на уведомления по грузу
  • /receivers/ — список получателей
    • /add/ — добавление получателя в справочник
    • /list/ — просмотр списка получателей
    • /delete/ — удаление получателя из справочника
    • /update/ — изменение получателя в справочнике
  • /calculator/ — калькуляторы стоимости услуг
    • /calculateprice/ — расчет стоимости и сроков перевозки
    • /maxdimension/ — вычисление максимального габарита
  • /netshop/ — прямые паллетные перевозки
  • /cargocontent/ — справочник наименований груза
    • /all/ — список наименований груза
  • /clientpackingkind/ — справочник упаковок клиента
    • /all/ — список упаковок клиента
  • /requests/ — операции со всеми видами заявок
    • /requestcancellation/ — аннулирование ранее созданных заявок на основании кодов грузов

Техническая поддержка

Поддержка оказывается с помощью обращений пользователей личного кабинета клиента «ПЭК» (требуется авторизация).

Используемый протокол

Общее описание

  • Запрос должен осуществляться по протоколу HTTPS с обязательной проверкой сертификата сервера клиентом. Для проверки можно использовать файл сертификатов из комплекта PHP SDK.
  • Формат передачи входящих и исходящих данных — JSON, кодировка — UTF-8
  • Входящие параметры должны передаваться прямо в теле POST запроса в виде строки в формате JSON
  • При осуществлении запросов необходимо устанавливать следующие HTTP-заголовки:
    Content-Type: application/json;charset=utf-8
    Accept: application/json
  • Поддерживается gzip-сжатие ответов API (к сожалению, стандарт для сжатия содержимого HTTP-запросов не утверждён). Использование компрессии уменьшает объем ответов в несколько раз. Для включения сжатия необходимо устанавливать следующий HTTP-заголовок:
    Accept-Encoding: gzip
  • Все поля JSON-объекта в запросе являются обязательными, если не указано обратное

Типы данных JSON-объектов

Используются стандартные типы данных JSON и следующие типы:

  • Для передачи двоичных данных используется кодирование в Base64 и помещение результата в строку. Этот тип данных обозначается в документации следующим образом:
    [Binary]
  • Для указания филиала или города, относящегося к филиалу используется тип, обозначенный в документации следующим образом:
    [City]
    Для филиала указывается его наименование в виде строки:
    {
      demoCity: "Курск"
    }
    Для городов, относящихся к филиалам значение указывается в формате: <Наименование города>, <Наименование филиала>, например:
    {
      demoCity: "Пристань, Курск"
    }
    Регистр указания наименований городов может быть любым. Список филиалов и городов доступен в результате вызова метода /branches/all/.

    Определены следующие специальные значения полей этого типа: значение Москва эквивалентно указанию филиала Москва Восток

  • Значения даты и даты + времени передаются как строки в формате ISO 8601 в следующих определённых стандартом форматах:

    Дата:
    {
      demoDateField: "2011-03-10"
    }
    Поля этого типа в описании методов помечаются следующим образом:
    [Date]
    Дата и время:
    {
      demoDateField: "2011-03-10T09:24:24"
    }
    Используется московское время (MSK), если не указано обратное.

    Поля этого типа в описании методов помечаются следующим образом:
    [DateTime]
  • Значения времени в пределах суток передаются как строки в формате ISO 8601 в следующих определённых стандартом форматах:

    Время:
    {
      demoTimeField: "18:15"
    }
    Время с секундами:
    {
      demoTimeFieldWithSeconds: "18:15:12"
    }
    Используется московское время (MSK), если не указано обратное.

    Поля этого типа в описании методов помечаются следующим образом:
    [Time]

Обработка ошибок

  • В случае, если указан неверный URL метода, возвращается страница ошибки с кодом состояния 404. Содержимое страницы можно игнорировать, проверяя наличие ошибки только по коду
  • В случае возникновения ошибки нарушения прав доступа к методу, возвращается страница с кодом состояния 403. Содержимое страницы также можно игнорировать.
  • Если возникает логическая ошибка (не указаны необходимые параметры, неверный формат входных данных и т.п.) возвращается ответ с кодом 200 и описанием ошибки в формате JSON:
    {
       "error": {           
           "title": "Соообщение об ошибке",    
           "message": "Детальное описание ошибки"
        }
    }
    В зависимости от типа ошибки могут быть добавлены дополнительные поля, но поля, указанные в примере выше возвращаются всегда.
  • При возникновении непредусмотренной ошибки, код состояния устанавливается равным 500, а в теле ответа выводится сообщение об ошибке в формате описанном выше.

Примеры использования API

Необходимые компоненты

Использование API возможно для большинства платформ и языков программирования и не требуется наличие каких-либо специфических библиотек на клиентской стороне. Необходимые программные компоненты:

  • Компонент (библиотека) для приёма и отправки HTTP-запросов с поддержкой протокола HTTPS и Basic-аутентификации (необходимо)
  • Компонент (библиотека) для сериализации\десериализации данных из\в формат JSON (опционально)
  • Компонент (библиотека) для кодирования\декодирования Base64 (опционально, необходимо только для работы с бинарными данными)

Использование утилит командной строки

В простейшем случае нет необходимости в программировании, достаточно использовать утилиты командной строки. В данном примере используется Windows-версия cURL с поддержкой SSL (HTTPS):
curl.exe ^
--verbose ^
--cacert cacert-kabinet_pecom_ru.pem ^
--basic ^
--user user:FA21831AB83DB72D3261FA80BA309DBF6B2D7ADC ^
--request POST -d @curl-input.txt ^
--header "Content-Type: application/json; charset=utf-8" ^
--compressed ^
--output curl-output.txt ^
https://kabinet.pecom.ru/api/v1/cargos/status/

Символ ^ используется для объединения строк. Файл cacert-kabinet_pecom_ru.pem содержит сертификаты и доступен в комплекте PHP SDK.

Содержимое запроса берётся из файла curl-input.txt (кодировка UTF-8), описание формата параметров доступно на соответствующей странице:

{
   "cargoCodes": [ 
      "МВПТЗВА-2/2903",
      "МВПЗЗЮН-3/2903",
      "ОКМВБУТ-3/0103"
   ]
}
Результат будет записан в файл curl-output.txt.

Обработка для 1С:Предприятия 8.1

В архиве, доступном для скачивания представлена внешняя обработка, позволяющая:

  • получить статус одного или нескольких грузов
  • оформить заявку на забор груза
  • оформить заявку на предварительное оформление

В форме обработки необходимо указать логин личного кабинета, ключ и параметры для запроса.

Скачать версию для платформы 8.1 (.zip, 42Кб)

Скачать версию для платформы 8.3 (.zip, 100Кб)

Скачать инструкцию по работе с внешней обработкой

Минимальный пример для .NET

В результате выполнения кода, приведённого ниже, будет осуществлён запрос статусов грузов и выведен результат в виде строки. Пример представляет собой консольное приложение на C#, целевая версия платформы — .NET Framework 3.5 и выше.

using System;
using System.IO;
using System.Net;
using System.Text;
using System.Web.Script.Serialization;

namespace PecomApiDemo
{
  class Program
  {
    static void Main(string[] args)
    {
      var login = "user";
      var key = "11111111111111111122222222222222";

      /*
       * Создание объекта запроса
       */
      var httpRequest = (HttpWebRequest)WebRequest.Create("https://kabinet.pecom.ru/api/v1/cargos/status/");

      /*
       * Настройка параметров запроса
       */
      // Кодировка и тип содержимого
      httpRequest.ContentType = "application/json; charset=utf-8";

      // Тип запроса
      httpRequest.Method = WebRequestMethods.Http.Post;

      // Включение поддержки сжатия
      httpRequest.AutomaticDecompression = DecompressionMethods.GZip | DecompressionMethods.Deflate;

      /* 
       * У реализации BASIC-авторизации в .NET есть особенности:
       * http://blog.cracca.com/2008/02/welcome.html
       * http://devproj20.blogspot.com/2008/02/assigning-basic-authorization-http.html               
       * Из-за этого необходимо указать заголовок вручную
       */
      byte[] credentialBuffer = new UTF8Encoding().GetBytes(login + ":" + key);
      httpRequest.Headers["Authorization"] = "Basic " + Convert.ToBase64String(credentialBuffer);

      try
      {
        /*
         * Подготовка содержимого запроса
         */
        using (var sw = new StreamWriter(httpRequest.GetRequestStream()))
        {
          /*           
           * Для сериализации/десериализации из/в JSON удобно использовать Json.NET
           * http://james.newtonking.com/projects/json-net.aspx (или в виде NuGet-пакета)
           * Эта библиотека поддерживает преобразование дат в ISO 8601
           * Стандартные классы JavaScriptSerializer и DataContractSerializer 
           * эту возможность не поддерживают
           */
          var serializer = new JavaScriptSerializer();
          var jsonData = new
          {
            cargoCodes = new string[] {
              "XXXXXXX-11/2222",
              "XXXXXXX-11/3333",
              "XXXXXXX-11/4444"
            }
          };
          string json = serializer.Serialize(jsonData);
          sw.Write(json);
        }

        /*
         * Выполнение запроса
         */
        var httpResponse = (HttpWebResponse)httpRequest.GetResponse();

        /*
         * Получение результата запроса
         */
        using (var sr = new StreamReader(httpResponse.GetResponseStream()))
        {
          var responseText = sr.ReadToEnd();
          Console.WriteLine(responseText);
        }
      }
      catch (WebException ex)
      {
        using (StreamReader sr = new StreamReader(ex.Response.GetResponseStream()))
        {
          var responseText = sr.ReadToEnd();
          Console.WriteLine(responseText);
        }
      }
    }
  }
}

Минимальный пример на PHP

В результате выполнения кода, приведённого ниже, будет осуществлён запрос статусов грузов и выведен результат в виде десериализированного PHP-объекта. Важно отметить, что в примере осуществляется проверка сертификата сервера с помощью файла сертификатов из комплекта PHP SDK

Внимание:

Пример кода приведён для иллюстрации, в случае использования PHP для доступа к API, рекомендуется использовать PHP SDK

/*

Минимальный пример работы с API Личного кабинета клиента «ПЭК» для PHP
	
Требования:
  - PHP 5.2 и выше
  - Необходимые PHP-расширения:
     - curl (http://php.net/manual/ru/book.curl.php)
     - json (http://php.net/manual/ru/book.json.php)

*/

// Инициализация HTTP-клиента
$ch = curl_init();

// Настройки HTTP-клиента
curl_setopt_array($ch, array(
	CURLOPT_RETURNTRANSFER => TRUE,
	CURLOPT_POST => TRUE,
	CURLOPT_SSL_VERIFYPEER => TRUE,
	CURLOPT_SSL_VERIFYHOST => 2,
	CURLOPT_CAINFO => dirname(__FILE__) . '/cacert-kabinet_pecom_ru.pem',
	CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
	CURLOPT_ENCODING => 'gzip',
	CURLOPT_USERPWD => 'user:FA218354B83DB72D3261FA80BA309D5454ADC',
	CURLOPT_HTTPHEADER => array(
		'Content-Type: application/json; charset=utf-8'	
	)
));

// Данные для запроса
$request_data = array(
	'cargoCodes' => array(
		'МВПТЗВА-2/2903',
		'МВПЗЗЮН-3/2903',
		'ОКМВБУТ-3/0103'
	));

// Параметры конкретного запроса к API	
curl_setopt_array($ch, array( 
	CURLOPT_URL => 'https://kabinet.pecom.ru/api/v1/cargos/status/',
	CURLOPT_POSTFIELDS => json_encode($request_data),
));

// Выполнение запроса
$result = curl_exec($ch);

// Проверка на наличие ошибки
if (curl_errno($ch))
{
	// Вывод сообщения об ошибке
	echo 'Ошибка: ' . curl_error($ch);
}
else
{
	// Вывод результата в виде строки
	var_dump($result);

	// Вывод результатов в виде объекта
	$result_json = json_decode($result);
	var_dump($result_json);		
}

// Освобождение ресурсов
curl_close($ch); 

PHP SDK

PHP SDK представляет собой класс, созданный чтобы упростить осуществление запросов к API из PHP-приложений и сайтов.

Состав архива:

  • cacert-kabinet_pecom_ru.pem — файл сертификатов
  • example.php — пример использования
  • pecom_kabinet.php — файл класса, реализующего SDK
  • README — описание, история изменений

Скачать версию 1.2 от 10.07.2012 (.zip, 135Кб)

Пример использования

// Подключение файла с классом
require_once('pecom_kabinet.php');

// Создание экземпляра класса
$sdk = new PecomKabinet('user', 'FA218354B83DB72D3261FA80BA309D5454ADC');

// Вызов метода
$result = $sdk->call('cargos', 'status', 
	array('cargoCodes' => array(
		'МВПТЗВА-2/2903',
		'МВПЗЗЮН-3/2903',
		'ОКМВБУТ-3/0103'
	)
));
	
// Вывод результата
var_dump($result);
	
// Освобождение ресурсов
$sdk->close();

Подключение через proxy-сервер

// Подключение файла с классом
require_once('pecom_kabinet.php');

// Создание экземпляра класса
$sdk = new PecomKabinet('user', 'FA218354B83DB72D3261FA80BA309D5454ADC', array(
		// Параметры proxy-серерва
		CURLOPT_PROXY => '127.0.0.1',
		CURLOPT_PROXYPORT => 8888,
		CURLOPT_PROXYTYPE => 'HTTP'
));

// Вызов метода
$result = $sdk->call('cargos', 'status', 
	array('cargoCodes' => array(
		'МВПТЗВА-2/2903',
		'МВПЗЗЮН-3/2903',
		'ОКМВБУТ-3/0103'
	)
));
	
// Вывод результата
var_dump($result);
	
// Освобождение ресурсов
$sdk->close();
Онлайн-чат

Список филиалов