Работа с пользовательскими статусами в 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 цветов

 

#D0CA02 #E2AC54 #DF8956 #DC5F59
#85C5E0 #3A9FC9 #B384E2 #D361B8
#8EA3E2 #A69196 #929594 #686A69
#7ABF24 #86AA60 #509897 #249641 
    • 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. Выбранные пермалинки положить в параметры запроса!

     

    Итого

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

     

     

    Полезная статья?
    Остались вопросы?
    Отправь тикет в техподдержку!
    Недавно просмотренные статьи