Описание API

Введение

Наш магазин предоставляет доступ к своим веб-сервисам посредством HTTP-запросов REST API.
Таким образом, доступ обеспечивается простым интерфейсом управления при отсутствии каких-либо дополнительных прослоек. Вы можете использовать любой подходящий клиент для осуществления запросов к сервисам. В примерах ниже, в качестве демонстрации, используется утилита командной строки cURL.

В процессе работы с API рекомендуется проверять коды ответов от сервисов, а не полученное содержимое, так как содержимое со времением может меняться и дополняться.

Доступ к API

Выполнять запросы к API могут только зарегистрированные на сайте пользователи. Для успешного выполнения необходимы:

  • URL, составленный согласно требованиям к нужному запросу.
  • Ключ доступа к API.

Ключ доступа к API (api_key) находится в вашем Профиле, там же вы можете произвести настройки доступа по IP-адресам, например:

Добавьте IP-адрес сервера своей платформы в список разрешенных и сохраните его. В список можно добавить до 5 адресов.

Если вы все сделали правильно, то в терминале хоста, который занесен в список разрешенных, после выполнения следующей команды:

curl -X GET "http://api.carreta.ru/v1/profile/?api_key=[ваш api_key]"

Вы увидите примерно такой результат (код ответа 200 OK):

{
  "balance": "7.14",
  "city": "city",
  "email": "",
  "name": "name",
  "phone": "+7-987-1234567"
}

Если же что-то пошло не так, то сервис вернет код ответа 401 Unauthorized и текст ошибки:

{
  "error": "Unauthorized."
}

Поддерживаемые запросы к API

API возвращает список найденных по запросу запчастей.

Формат запроса

Запрос осуществляется с помощью метода GET.

http://api.carreta.ru/v1/search/?api_key=<api_key>
[&q=<строка запроса, например: oc47>]

Пример:

curl -X GET "http://api.carreta.ru/v1/search/?q=oc47&api_key=[ваш api_key]"

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK, и возвращает список запчастей в формате JSON. Пример ответа:

{
  "objects": [
    {
      "_": "DqYXihjdqSPM4OKLl9uE6piTekMMfMSYhkNNgDbhOzVDDWD+JdDi28ZxGbbDkXBvUw7Yu6q69MiKBaDSnYdY6imQkzWYQFw=",
      "code": "OC47",
      "desc": "",
      "is_cross": false,
      "maker": "KNECHT/MAHLE",
      "min_qty": 1,
      "name": "\u0424\u0438\u043b\u044c\u0442\u0440 \u043c\u0430\u0441\u043b\u044f\u043d\u044b\u0439",
      "period_max": 7,
      "period_min": 7,
      "price": "152.02",
      "qty": "500",
      "stat": 97,
    },
    ...
}
Поле Тип Описание
code string Код запчасти
maker string Производитель
name string Наименование
desc text Описание
is_cross bool Является ли запчасть заменой
price string (decimal) Цена, рублей
period_min int Минимальный срок поставки, дней
period_max int Максимальный срок поставки, дней
min_qty int Минимальное количество к заказу, штук
qty string Количество в наличии, штук
stat int Вероятность поставки, % (если статистики нет, то null)
_ string Подпись позиции (используется при создании заказа)

Создание заказа

API создает заказ.

Формат запроса

Запрос осуществляется с помощью отправки JSON данных методом POST.

http://api.carreta.ru/v1/order/?api_key=<api_key>
[&test=<on - создает тестовый заказ>]

Пример:

curl -X POST -H "Content-Type: application/json" -d '{"_": "DqYXihjdqSPM4OKLl9uE6J+Te0AMfMSYhkNNgDbhOTJDDGP+JdDi28ZxGbbDkXBvUw7Yu6q69MiKBaDSnYdY6imfljWcQFw=","code": "OC47","maker": "KNECHT/MAHLE","min_qty": 1,"name": "\u0424\u0438\u043b\u044c\u0442\u0440 \u043c\u0430\u0441\u043b\u044f\u043d\u044b\u0439","period_max": 7,"period_min": 7,"price": "175.11","qty": "300","order_qty": 10}' "http://api.carreta.ru/v1/order/?api_key=[ваш api_key]"

Поля объекта JSON в теле запроса должны соответствовать полям из ответа поисковой выдачи. Пример с минимально необходимым набором полей представлен ниже:

{
  "_": "DqYXihjdqSPM4OKLl9uE6piTekMMfMSYhkNNgDbhOzVDDWD+JdDi28ZxGbbDkXBvUw7Yu6q69MiKBaDSnYdY6imQkzWYQFw=",
  "code": "OC47",
  "maker": "KNECHT/MAHLE",
  "name": "\u0424\u0438\u043b\u044c\u0442\u0440 \u043c\u0430\u0441\u043b\u044f\u043d\u044b\u0439",
  "price": "152.02",
  "period_min": 7,
  "period_max": 7,
  "min_qty": 1,
  "qty": "500",
  "order_qty": 1,

  // Необязательные поля
  "client_comment": "Ваш комментарий или внутренний номер заказа, до 50 символов"
}

Обратите внимание, что в запрос добавлено поле order_qty, значением которого является количество к заказу. Это значение проходит несколько проверок:

  • Значение order_qty не должно превышать значения qty
    • Если значение qty указано со знаком <, то order_qty должен быть строго меньше значения qty.
      Например: если qty = "<10", то order_qty может быть в пределах [1..9]
    • Если значение qty указано со знаком >, то order_qty может иметь любое значение.
      Например: если qty = ">50", то order_qty может быть в пределах [1..10000]
    • Если значение qty является числовым, то order_qty должен быть не более значения qty.
      Например: если qty = "10", то order_qty может быть в пределах [1..10]
    • Если значение qty содержит слово "Есть", то order_qty может иметь любое значение.
      Например: если qty = "Есть", то order_qty может быть в пределах [1..10000]
  • Значение order_qty должно быть кратным значению min_qty.
    Например: если min_qty = 2, то order_qty может быть равен 2, или 4, или 8, и т.д.

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

Если запрос был обработан без ошибок, API отвечает кодом 201 Created. Если при валидации данных произошла ошибка, API отвечает кодом 400 Bad Request.

Получение списка заказов

API возвращает список заказов.

Формат запроса

Запрос осуществляется с помощью метода GET.

http://api.carreta.ru/v1/order/?api_key=<api_key>
[&page=<номер страницы>]
[&client_comment=<ваш комментарий к заказу>]

С параметрами по умолчанию возвращаются последние 100 заказов. Получить остальные заказы можно указав параметр page.

Если указан параметр client_comment, то возвращаются заказы в комментарий к которым входит переданная подстрока (регистронезависимо). Таким образом, вы можете выполнять фильтрацию заказов.

Пример:

curl -X GET "http://api.carreta.ru/v1/order/?api_key=[ваш api_key]"

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK, и возвращает список заказов в формате JSON. Пример ответа:

{
  "objects": [
    {
      "code": "AC108",
      "comment": "",
      "client_comment": "",
      "created": "2014-10-23T16:18:31.315072",
      "id": 189330,
      "maker": "KITTO",
      "name": "\u0424\u0438\u043b\u044c\u0442\u0440 \u0441\u0430\u043b\u043e\u043d\u043d\u044b\u0439(\u0443\u0433\u043e\u043b\u044c\u043d\u044b\u0439)",
      "number": "A111342-1",
      "order_qty": 1,
      "period_max": 9,
      "period_min": 7,
      "price": "212.86",
      "status": 7,
      "status_display": "\u0412\u044b\u0434\u0430\u043d",
      "total": "212.86"
    },
    ...
  ]
}
Поле Тип Описание
id int ID
number string Номер заказа
status int Статус
status_display string Описание статуса
comment string Комментарий
client_comment string Ваш комментарий к заказу
created time Время создания
code string Код запчасти
maker string Производитель
name string Наименование
price string (decimal) Цена, рублей
period_min int Минимальный срок поставки, дней
period_max int Максимальный срок поставки, дней
order_qty int Количество, штук
total string (decimal) Сумма, рублей

Получение информации по заказу

API возвращает информацию по заказу.

Формат запроса

Запрос осуществляется с помощью метода GET.

http://api.carreta.ru/v1/order/<id>/?api_key=<api_key>

Пример:

curl -X GET "http://api.carreta.ru/v1/order/[id]/?api_key=[ваш api_key]"

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK и возвращает информацию по заказу в формате JSON. Пример ответа:

{
  "code": "AC108",
  "comment": "",
  "client_comment": "",
  "created": "2014-10-23T16:18:31.315072",
  "id": 189330,
  "maker": "KITTO",
  "name": "\u0424\u0438\u043b\u044c\u0442\u0440 \u0441\u0430\u043b\u043e\u043d\u043d\u044b\u0439(\u0443\u0433\u043e\u043b\u044c\u043d\u044b\u0439)",
  "number": "A111342-1",
  "order_qty": 1,
  "period_max": 9,
  "period_min": 7,
  "price": "212.86",
  "status": 7,
  "status_display": "\u0412\u044b\u0434\u0430\u043d",
  "total": "212.86"
}

Описания полей идентичны описаниям из раздела Получение списка заказов.

Получение истории действий по заказу

API возвращает историю действий по заказу.

Формат запроса

Запрос осуществляется с помощью метода GET.

http://api.carreta.ru/v1/order/<id>/history/?api_key=<api_key>

Пример:

curl -X GET "http://api.carreta.ru/v1/order/[id]/history/?api_key=[ваш api_key]"

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK и возвращает историю действий по заказу в формате JSON. Пример ответа:

{
  "objects": [
    {
      "comment": "\u0421\u043e\u0437\u0434\u0430\u043d \u0441\u043e \u0441\u0442\u0430\u0442\u0443\u0441\u043e\u043c \"\u0425\u043e\u043b\u0434\" \u043d\u0430 \u0441\u0443\u043c\u043c\u0443 212.86 \u0440\u0443\u0431.",
      "created": "2014-10-23T16:18:31.316768"
    },
    ...
  ]
}
Поле Тип Описание
comment string Описание действия
created time Время создания действия

Получение информации профиля

API возвращает информацию профиля.

Формат запроса

Запрос осуществляется с помощью метода GET.

http://api.carreta.ru/v1/profile/?api_key=<api_key>

Пример:

curl -X GET "http://api.carreta.ru/v1/profile/?api_key=[ваш api_key]"

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

Если запрос был обработан без ошибок, API отвечает кодом 200 OK и возвращает информацию профиля в формате JSON. Пример ответа:

{
  "balance": "7.14",
  "city": "city",
  "email": "",
  "name": "name",
  "phone": "+7-987-1234567"
}
Поле Тип Описание
balance string (decimal) Баланс, рублей
city string Город
email string Email
name string ФИО
phone string Телефон

Обратная связь

Со всеми вопросами и пожеланиями вы можете обращаться на info@carreta.ru

Если у вас что-то не получается, обязательно прикладывайте команду запроса через cURL и ответ, это поможет нам максимально быстро локализовать проблему.