Post2Go для бизнеса

Обзор API

Начало работы

Сервис Post2Go предоставляет доступ к данным об отслеживании посылок с помощью API, реализованного протоколом JSON-RPC 2. Сам протокол знать не обязательно, мы опишем его ниже.

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

Точка доступа к API

Все запросы к API делаеются к точке доступа, расположенной по адресу http://api.post2go.ru/v2/jsonrpc.

Каждый запрос обязательно должен содержать следующие заголовки:

X-Authorization-Token: ВАШ_API_КЛЮЧ
Content-Type: application/json

Тело запроса

Тело запроса всегда должно иметь указанный вид:

{
    "jsonrpc": "2.0",
    "method": "methodName",
    "params": { },
    "id": 1
}

• Параметр jsonrpc обязателен и его значение всегда должно быть 2.0;
• Параметр method обязателен, в него должно быть записано название запрашиваемого метода;
• Параметр params обязателен, если у метода нет параметров — нужно передать пустой объект { } как в примере;
• Параметр id обязателен, он позволяет идентифицировать ответ API. Если вам это не нужно, то просто передавайте в нём любую строку или число.

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

Ответ API в случае успеха выглядит следующим образом:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [ ]
}

• Параметр jsonrpc передаётся всегда и его значение всегда 2.0;
• В параметр id копируется значение id полученное в запросе;
• Параметр result передаётся всегда, но может содержать значения null, [ ] или { }. Его значение всегда зависит от метода.

Если параметр result отсутствует, значит произошла ошибка. Ответ в случае ошибки выглядит так:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 401,
        "message": "Invalid or expired X-Authorization-Token"
    },
    "id": null
}

• Параметр jsonrpc передаётся всегда и его значение всегда 2.0;
• В параметр id копируется значение id полученное в запросе, кроме случаев когда произошла глобальная ошибка;
• Параметр error всегда содержит объект ошибки с кодом и сообщением. Расшифровку возможных кодов смотрите ниже.

Внимание! Проверяйте тип ошибки по коду, а не по тексту. Текст может меняться со временем, либо зависеть от поступившенго запроса, а код является фиксированным.

Возможные ошибки

Не передан X-Authorization-Token в заголовках запроса:

{
    "jsonrpc": "2.0",
    "error":{
        "code": 401,
        "message": "X-Authorization-Token is required and must be a string"
    },
    "id": null
}

X-Authorization-Token передан, но является неверным:

{
    "jsonrpc": "2.0",
    "error":{
        "code": 401,
        "message": "Invalid or expired X-Authorization-Token"
    },
    "id": null
}

Синтаксическая ошибка при разборе запроса, передан неправильный JSON:

{
    "jsonrpc": "2.0",
    "error":{
        "code": -32700,
        "message": "Parse error"
    },
    "id": null
}

Передан неправильный запрос, например не указан один из обязательных параметров:

{
    "jsonrpc": "2.0",
    "error":{
        "code": -32600,
        "message": "Invalid request"
    },
    "id": null
}

Запрошенный метод не существует или не доступен:

{
    "jsonrpc": "2.0",
    "error":{
        "code": -32601,
        "message": "Requested method does not exist"
    },
    "id": null
}

Один из переданных параметров не соответствует требованиям:

{
    "jsonrpc": "2.0",
    "error":{
        "code": -32602,
        "message": "Invalid parameter"
    },
    "id": null
}

Произошла внутренняя ошибка сервера:

{
    "jsonrpc": "2.0",
    "error":{
        "code": -32603,
        "message": "Internal error"
    },
    "id": null
}

Запрошенный объект не найден:

{
    "jsonrpc": "2.0",
    "error":{
        "code": 404,
        "message": "Nothing found"
    },
    "id": null
}

Попытка получить информацию о треке до постановки на отслеживание:

{
    "jsonrpc": "2.0",
    "error":{
        "code": 403,
        "message": "Access denied. You should addTracking to access this operation."
    },
    "id": null
}