My favorites ▼ | Sign in
Project Home Downloads Wiki Issues Source
Search
for
API_X1  
API для доступа к интерфейсу X1
Updated Feb 24, 2012 by vgrays...@gmail.com

ГдеПосылка.ру - это универсальный сервис для отслеживания посылок, перейти на сайт http://gdeposylka.ru

Обзор

API сервиса http://gdeposylka.ru построено на основе принципов REST. На этой страничке я привел адреса страниц API и какие операции с ними возможны.

Текущая версия API располагается по адресу

http://ws.gdeposylka.ru/x1/

Все запросы к сервису осуществляются путем GET запросов. В каждом запросе обязательно нужно передавать параметр apikey. Получить API-ключ можно на сайте ГдеПосылка.ру в разделе Настройки→Сервис

Пример вызова API

http://ws.gdeposylka.ru/x1/info.version/xml/?apikey=XXXXXXXXX

Сервис может возвращать данные в нескольких форматах

XML - http://ws.gdeposylka.ru/x1/function/xml/

JSON - http://ws.gdeposylka.ru/x1/function/json/

Результат вызова функции serialize() над массивом в PHP - http://ws.gdeposylka.ru/x1/function/php/

Для удобной отладки через браузер можно использовать формат DUMP - http://ws.gdeposylka.ru/x1/function/dump/

По умолчанию данные выводятся в XML

Формат ответа

Сервис всегда отвечает структурой определенного формата ( в выбранном формате вывода) 

<result>
<response>
    <code>200</code>     <!--  Код ответа, описание кодов смотрите ниже -->
    <version>2010.08.12.1</version>  <!-- Дополнительные параметры ответа -->
</response>
<tracks> <!-- Информация о треках -->

</tracks>
</result>

Формат описания информации о треке

<track id="CJ247232572US">
        <code>200</code>  <!-- Код обработки запроса для трека -->
        <status>COMPLETE</status>  <!-- Состояние трека -->
        <destination>RU</destination> <!-- Страна назначения трека -->
        <errstr></errstr> <!-- Если состояние трека ERROR, здесь указывается причина ошибки -->
        <updated>1276746128</updated> <!-- Время последнего обновления трека -->
        <checked>1276746128</checked> <!-- Время последней проверки трека -->
        <info>
            <status>
                <message>Вручение, Санкт-Петербург 245, Вручение адресату</message>
                <date>09.06.2010 00:00</date>  
                <timestamp>1276020000</timestamp> <!-- Поле date в формате unixtimestamp -->
                <ops_id>9813</ops_id>  <!-- Идентификатор почтового отделения -->
                <service_id>EMS_RU</service_id> <!-- Идентификатор почтовой службы -->
                <service_name>Почта России</service_name>
                <operation>Вручение</operation>
                <weight>0.052</weight> <!-- Вес посылки -->

            </status>

            <status>
                <message>Передано таможне, Санкт-Петербург PI-7</message>
                <date>05.06.2010 17:36</date>
                <timestamp>1275737760</timestamp>
                <ops_id>9738</ops_id>
                <service_id>EMS_RU</service_id>
                <service_name>Почта России</service_name>
                <operation>Передано таможне</operation>
            </status>
        </info>
    </track>

Возможные Состояние трека

NORMAL Сервис отслеживает трек
STOPPED Отслеживание трека остановлено
ERROR Произошла ошибка при отслеживании трека
COMPLETE Адресат получил посылку

Возможные значения поля errstr

  • WRGNCNTR - Страна назначения посылки указанная при добавлении трека, не совпадает со страной назначения посылки полученной от почтовых служб. Пожалуйста, укажите правильную страну назначения использую функцию track.country
  • LASTSRV - Сервис не знает, как дальше отслеживать Вашу посылку. Возможно это произошло из-за того, что сервис пока не умеет получать данные с почты страны назначения посылки, либо потому что страна назначения была неверно определена. Пожалуйста, укажите правильную страну назначения
  • NOSRV - Сервис пока не умеет отслеживать указанный Вами номер почтового отслеживания. Попробуйте указать страну назначения посылки использую функцию track.country и сервис будет отслеживать посылку в стране назначения
  • NORPATH - Внутренняя ошибка сервиса. Не удалось определить страну назначения посылки Попробуйте указать страну назначения посылки использую функцию track.country и сервис будет отслеживать посылку в стране назначения

Идентификатор почтовой службы

EMS_CH Почта Швейцарии
EMS_CN Почта Китая
EMS_GB Почта Великобритании
EMS_HK Почта Гонконга
EMS_KZ Почта РК
EMS_RU Почта России
EMS_SG Почта Сингапура
EMS_UA Почта Украины
EMS_US Почта США

Также сервис ГдеПосылка добавлят несколько типов поясняющих статусов. Поле идентификатора у таких статусов равен значению GP, а поле operation поясняет какого рода сообщение было добавленно 

            <status>
                <message>Посылка добавлена на сайт</message>
                <date>29.05.2010 19:45</date>
                <timestamp></timestamp>
                <ops_id></ops_id>
                <service_id>GP</service_id>
                <service_name>ГдеПосылка.ру</service_name>
                <operation>GP: Added on site</operation>
            </status>

Значения поля operation

GP: Added on site Посылка добавлена на сайт
GP: Stop Tracking Отслеживание посылки остановлено

Формат описания информации о местоположении пунктов обработки

Функция geo.points может использоваться для преобразования ops_id в географические координаты. Ответ предоставлеяется в следующем виде 

<ops id="9726">
        <status>VERIFIED</status> <!-- Статус Геокодирование -->
        <x>114.109497</x>
        <y>22.396428</y>
        <name>Гонконг</name>
        <country>HK</country>
        <accuracy>1</accuracy> <!-- Уровень детализации --> 
    </ops>

Подробнее про уровень детализации

Возможные статусы Геокодирования

NORMAL Геокодирование не производилось. Сервис производит геокодирование 1 раз в 15 минут.
ERROR Сервис не смог выполнить преобразование
VERIFIED Геокодирование успешно выполнено

Коды ошибок

Каждый ответ, а также каждая запись о треке содержит код обработки запроса.

Код Описание

2xx Коды при успешном выполнении запроса
200 ОК
201 Попытка добавить трек который уже существует, сервис просто игнорирует такой трек

3xx Временные ошибки
300 Внутренняя ошибка сервиса
302 Таймаут при обработке трека
303 Трек обрабатывается в настойщий момент, данные будут доступны позже
304 Слишком много треков в запросе

4xx Постоянные ошибки
400 Неизвестная комманда
401 Неправильный API Key
402 Неправильный формат номера отслеживания
403 Неизвестный номер трека
404 Не хватает некоторых обязательныx параметров
405 Попытка выполнить не корректное действие над треком
406 При добавлении трека обязателен параметр country
407 Не правильный формат номера телефона
408 Не достаточно средств на счету для выполнения операции

Функции

tracks.list Выводит все треки принадлежащие пользовател

Параметры

area Какой раздел выводить. Может принимать значения main или archive

Пример 

http://ws.gdeposylka.ru/x1/tracks.list/xml?apikey=XXXXXXX&area=main

<?xml version="1.0" encoding="UTF-8" ?>
<result>
<response>
    <code>200</code>
</response>
<tracks>
    <track id="XXXXXXX">
        <description>Новая сумка</description> <!-- Описание посылки -->
        <origin>UPU</origin>  <!-- Какой почтовой системе принадлежит трек -->
        <date>09.02.2011 00:00</date> <-- Дата последнего статуса -->
        <message>Завершено таможенное оформление посылки</message> <!-- последний статус -->
        <destination>UA</destination> <!-- Страна назначения -->
        <updated>1296180906</updated> <!-- Время добавления последнего статуса -->
        <checked>1296181092</checked> <!-- Время последней проверки -->
        <errcode></errcode> <!-- Код ошибки --> 
        <added>1296180801</added> <!-- Время добавления посылки в сервис-->
        <weight></weight> <!-- Вес посылки --> 
    </track>
</tracks>
<geo>
</geo>
</result>

track.add добавляет трек в систему

Параметры

id Номер трека (обязателен)
descr Описание трека (не обязателен)
country Страна назначения трека ( см комментарий)
async Синхронный/Асинхронный запрос - по умолчанию Асинхронный

При синхронном запросе, сервер не дает ответа до тех пор пока не получит данные о треке с серверов почтовых служб. Максимально время ответа составляет 1 минуту, если за это время не удалось получить информацию, то возвращается ошибка.

При асинхронном запросе, сервер ставит задание в очередь. Статус трека можно получить через метод track.status

Некоторые почтовые службы, например США, не указывают в какую страну отправлена посылка. В этом случае, сервер вернет ошибку, и параметр country становится обязательным.

Код страны назначения - это двухбуквенная комбинация обозначающая страну согласно ISO 3166-1-alpha-2

Пример 

http://ws.gdeposylka.ru/x1/track.add/xml/?apikey=XXXXXX&id=CJ247232572US&country=RU

<?xml version="1.0" encoding="UTF-8" ?>
<result>
<response>
    <code>200</code>
</response>
<tracks>
    <track id="CJ247232572US">
        <code>201</code>
    </track>
</tracks>
</result>

track.status Информация о треке

Параметры

id Номер трека (обязателен) , возможно указать несколько треков (до 50) через ;

Пример 

http://ws.gdeposylka.ru/x1/track.status/xml/?apikey=XXXXXx&id=CJ247232572US;RT12345678HK

<result>
<response>
    <code>200</code>
</response>
<tracks>
    <track id="CJ247232572US">
        <code>200</code>
        <status>COMPLETE</status>
        <destination>RU</destination>

        <errstr></errstr>
        <updated>1276746128</updated>
        <checked>1276746128</checked>
        <info>
            <status>
                <message>Вручение, Санкт-Петербург 245, Вручение адресату</message>
                <date>09.06.2010 00:00</date>

                <timestamp>1276020000</timestamp>
                <ops_id>9813</ops_id>
                <service_id>EMS_RU</service_id>
                <service_name>Почта России</service_name>
                <operation>Вручение</operation>
            </status>

track.country Изменить страну наздачения посылки

Параметры

id Номер трека (обязателен)
country Двухбуквенный индекс страны (RU,UA,KZ,UZ...)

Примечание

Операция возможна только с треками которые имею статус NORMAL или ERROR. Трек со статусом ERROR переводится в состояние NORMAL.

Пример 

http://ws.gdeposylka.ru/x1/track.country/xml/?apikey=XXXXXx&id=CJ247232572US&country=RU

<result>
<response>
    <code>200</code>
</response>
<tracks>
    <track id="CJ247232572US">
        <code>200</code>
    </track>
</tracks>
</result>

track.sms Включить SMS уведомление для трека

Параметры

id Номер трека (обязателен)
phone Номер телефона в международном формате (обязателен)
descr Краткое описание трека (максимально 80 знаков)
greeting Текст который отправится на мобильный телефон при сразу после добавления трека

Примечание

Операция возможна только с треками которые имею статус NORMAL или ERROR. Трек со статусом ERROR переводится в состояние NORMAL.

Пример 

http://ws.gdeposylka.ru/x1/track.sms/xml/?apikey=XXXXXx&id=CJ247232572US&phone=+34051418961&descr=Vash_novii_telefon&greeting=Servis_nachal_otslejivat_posylky

<result>
<response>
    <code>200</code>
</response>
<tracks>
    <track id="CJ247232572US">
        <code>200</code>
    </track>
</tracks>
</result>

Внимание - При успешном выполнении данной функции с Вашего баланса будет списана сумма в размере 10 кредитов. SMS сообщения будут приходить при каждой смене статуса, до тех пор пока получатель не получить посылку.

track.resume Возобновить отслеживание трека

Параметры

id Номер трека (обязателен)

Примечание

Операция возможна только с треками которые имею статус STOPPED

Пример 

http://ws.gdeposylka.ru/x1/track.resume/xml/?apikey=XXXXXx&id=CJ247232572US

<result>
<response>
    <code>200</code>
</response>
<tracks>
    <track id="CJ247232572US">
        <code>200</code>
    </track>
</tracks>
</result>

geo.points Получить географические координаты почтового отделения

Параметры

ops Номер почтового пункта (обязателен) , возможно указать несколько номеров (до 250) через ;

Пример 

http://ws.gdeposylka.ru/x1/geo.points/xml/?apikey=XXXX&ops=9819;9726;9727

<result>
<response>
    <code>200</code>
</response>
<tracks>
</tracks>
<geo>
    <ops id="9726">
        <status>VERIFIED</status>
        <x>114.109497</x>
        <y>22.396428</y>
        <name>Гонконг</name>
        <country>HK</country>
        <accuracy>1</accuracy>
    </ops>
    <ops id="9727">
        <status>VERIFIED</status>
        <x>37.617633</x>
        <y>55.755786</y>
        <name>город Москва, Россия</name>
        <country>RU</country>
        <accuracy>4</accuracy>
    </ops>

    <ops id="9819">
        <status>VERIFIED</status>
        <x>32.066667</x>
        <y>49.433333</y>
        <name>Черкассы, Черкасская область, Украина</name>
        <country>UA</country>
        <accuracy>4</accuracy>
    </ops>
</geo>
</result>

► Sign in to add a comment
Powered by Google Project Hosting