Работа с пользовательскими статусами в API

В этой статье мы расскажем Вам, как начать работать с пользовательскими статусами в API.

Итак, в Вашем магазине пока что нет пользовательских статусов. Начнем именно с создания статусов.

Данное API поддерживает xml и json. Сегодня все примеры будут именно в протоколе json

URL

POST admin/custom_statuses.[xml, json]

Тело запроса

{
  "custom_status": {
    "system_status": "new",
    "title": "New (ordered by phone)"
  }
}


Ответ

{
  "color": "#DC5F59",
  "created_at": "2017-01-01T03:00:00+03:00",
  "id": 6,
  "is_default": false,
  "permalink": "new-ordered-by-phone",
  "position": 2,
  "system_status": "new",
  "updated_at": "2017-01-01T03:00:00+03:00",
  "title": "New (ordered by phone)"
}

Поздравляем! Теперь у Вас есть пользовательский статус.

Теперь немного про поля:

• color - это цвет, которым будет отображаться кастомный статус в бэк-офисе.

Кстати говоря цвета можно менять(об этом чуть позже), на выбор дается 16 цветов

• permalink - это уникальное поле этого статуса, по которому происходит любое взаимодействие с ним
• system_status - любой кастомный статус является расширением системного, поэтмоу любой кастомный статус должен иметь поле system_status
• is_default - флаг, показывающий, является ли данный статус статусом по умолчанию. Статус по умолчанию будет выставляться заказу при его создании. Для каждого системного статуса может быть только один пользовательский статус с is_default = true
• position - порядковый номер в бэк-офисе

Редактирование статуса похоже на его создание, отличается только URL

URL

PUT admin/custom_statuses/new_ordered_by_phone.[xml, json]

Тело запроса

{
  "custom_status": {
    "color": "#929594",
  }
}


Ответ

{
  "status": "ok"
}

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

URL

GET admin/custom_statuses[xml, json]


Ответ

[
  { 
    "color": "#DC5F59", 
    "created_at": "2017-01-01T03:00:00+03:00", 
    "id": 6,
    "is_default": false, 
    "permalink": "new-ordered-by-phone",
    "position": 2,
    "system_status": "new",
    "updated_at": "2017-01-01T03:00:00+03:00",
    "title": "New (ordered by phone)" 
  },

  ...
]

ВАЖНО!

Делая такой запрос, если кастомные статусы не перекрывают все системные, то происходит автоматическое создание недостающих статусов

Пользовательские статусы в заказах.

Очевидно, что пользовательские статусы можно выставлять в заказах.

У заказа есть два поля, отвечающих за статусы - fulfillment_status, custom_status, custom_status_permalink.

• fulfillment_status - пермалинк системного статуса
• custom_status_permalink - пермалинк кастомного статуса
• custom_status - объект, сериализующийся по-разному, в зависимости от состояния опции пользовтельских статусов. Если эта опция включена, то нужный статус подтягивается по custom_status_permalink, в обратной ситуации по fulfillment_status

Как было сказано выше у пользовательского статуса есть поле system_status, которое по совместительству является пермалинком системного статуса

Меняя fulfillment_status и custom_status_permalink, поле system_status кастомного статуса должно совпадать с переданным fulfillment_status

Иначе вы получите следующее сообщение об ошибке

{"message": "incompatible fulfillment and custom statuses"}

Меняя отдельно fulfillment_status в custom_status_permalink поставится кастомный статус по умолчанию.

При смене же custom_status_permalink произойдет обратная ситуация и в fulfillment_status поставится системный статус переданного пользовательского статуса.

Если Вы попытаетесь в custom_status_permalink подставить системный статус, то это равносильно передаче поля fulfillment_status.

Описанное выше так же подходит и к созданию заказа.

Фильтрация заказов

Напоследок поговорим о фильтрации заказов по статусам.

URL

GET admin/orders.[xml, json]?custom_status[]=...

Фильтровать можно сразу по нескольким статусам

Пример:

GET admin/orders.json?custom_status[]='status1'&custom_status[]='status2'

В параметры запроса вы можете передавать пермалинки и системных и пользовательских статусов, фильтрация пройдет по разным полям.

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

Все, что нужно - это:

1. Получить список пользовательских статусов
2. Дать пользователю на выбор варианты фильтрации
3. Выбранные пермалинки положить в параметры запроса!

Итого

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