YavaptekeAPI - Часть2 (Заказы и статусы)¶
Процессы работы с заказами¶
С определенной периодичностью опрашивается API для получения информации о новых или измененных заказах. Все полученные с сайта yaVapteke.ru заказы будут приняты и обработаны.
Схема движения заказа со статусамиСхема движения заказа со статусами
- Новый заказ
При получении нового заказа, если присутствуют строки с товаром из наличия, пытается бронировать все товары по этим строкам.
Если заказ со строками только из наличия, возможны следующие варианты:
1. Товары полностью зарезервировались - формируется и возвращается новый статус с кодом 200 Accepted на заголовок.
2. Товары полностью не зарезервировались - формируется и возвращается новый статус с кодом 202 Rejected на заголовок.
3. Товары зарезервировались частично - формируется и возвращается новый статус с кодом 201 PartiallyAccepted на заголовок, а так же возвращаются строки заказа, по которым не хватило количества в наличии
- Сбор (комплектация) заказа
После того как заказ в аптеке был собран (укомплектован), необходимо отправить статус на заголовок 213 Assembled.
- Отмена заказа аптекой
При отмене заказа формируется и возвращается новый статус (с новым уникальным идентификатором) отмены заказа по инициативе аптеки с кодом 202 Rejected. Заказ снимается с резерва.
- Выкуп заказа
Если заказ был полностью выкуплен, то формируется и возвращается статус с кодом 210 Purchased.
- Запрещено менять статус заказа если заказ уже находится в одном из статусов - отменен аптекой(202 Rejected), отменен покупателем(111 CancelledByUser) или выкуплен(210 Purchased). На запрос, содержащий невозможный переход статусов, приходит ответ 500.
- Из статуса Готов к выдаче(213 Assembled) должно быть возможно осуществлять переход только в один из статусов: выкуплен(210 Purchased), отменен аптекой(202 Rejected).
Статусы заказов, формируемые сайтом¶
| Код |
Название |
Описание |
| 100 |
New |
Новый заказ |
| 111 |
CancelledByUser |
Заказ отменен покупателем |
| 112 |
Cancelledadministratively |
Отменен административно |
Статус 112 необходимо обрабатывать аналогично статусу 111.
Статусы заказов, формируемые аптекой¶
| Код |
Название |
Описание |
| 200 |
Accepted |
Заказ принят аптекой. Формируется на заголовок |
| 201 |
PartiallyAccepted |
Заказ частично принят аптекой. Формируется на заголовок |
| 202 |
Rejected |
Отказ со стороны аптеки. Формируется на заголовок |
| 210 |
Purchased |
Заказ выкуплен. Формируется на заголовок |
| 213 |
Assembled |
Заказ собран (укомплектован). Формируется на заголовок |
Статус 201 служит промежуточным для передачи информации о незарезервированном количестве товара. После него обязательно необходима отправка сообщения со статусом 213, после чего статус заказа изменяется на "Готов к выдаче" и покупателю отправляется СМС о готовности.
Получение информации о заказах аптеки¶
Клиенты, которые работают с сайтом yaVapteke, могут получать через API информацию о новых заказах, сформированных на сайте, а также информацию об изменении статусов этих заказов.
GET /v5/stores/{storeId}/orders_exchanger
ОписаниеОписание
Получить информацию по заказам аптеки storeId по протоколу v5
Параметры запросаПараметры запроса
| Имя |
Тип |
Обяз. |
Описание |
| storeId |
GUID |
• |
Идентификатор аптеки по справочнику yaVapteke |
| since |
datetime |
|
Дата, с которой необходимо получить изменения (не включительно) в формате ISO8601 |
| orderId |
GUID |
|
Уникальный код заказа |
| excludeOwn |
bool |
|
Исключать или не исключать собственные изменения, по умолчанию true, т.е. при запросе изменений с какой-либо даты, вы получите в ответ только изменения, созданные сайтом, иначе получите назад и созданные аптекой статусы. |
Если в запросе указать excludeOwn=false, то при запросе изменений с какой-либо даты, вы получите в ответ получите изменения созданные сайтом и созданные аптекой статусы.
Таким образом можно получить всю историю статусов по заказам начиная с указанной даты.
ВНИМАНИЕ! При запросе изменений по заказам, всегда задавайте параметр since следующего запроса равным максимальному значению поля Date объекта запроса Status.
Заголовки запросаЗаголовки запроса
| Имя |
Описание |
| Authorization |
Bearer token |
| Accept |
application/json или application/x-json-full |
Пример запросаПример запроса
GET /v5/stores/638f97ee-2675-11ed-9d91-051517d411ac/orders_exchanger?since=2022-08-25T16:45:42.614983 HTTP/1.1
Host: yavapteke.ru/YavaptekeAPI/
Authorization: Bearer 08da627f-6773-4112-8355-47c94c7ac717
Content-Type: application/json
Cache-Control: no-cache
Успешный ответУспешный ответ
| HTTP cтатус |
Значение |
| 200 |
ОК. Успешный запрос. Тело запроса содержит объект заказов |
Пример ответаПример ответа
{
"headers": [
{
"orderId": "8983235b-cd45-417a-b520-42e364d02e95",
"storeId": "638f97ee-2675-11ed-9d91-051517d411ac",
"issuerId": "638f97ee-2675-11ed-9d91-051517d411ac",
"src": null,
"num": "4014",
"date": "2022-08-25T16:04:58+03:00",
"name": "Виталий",
"mPhone": "+79507537272",
"payType": null,
"payTypeId": null,
"summary": null,
"ae": null,
"unionId": null,
"ts": "2022-08-25T16:10:47+03:00",
"delivery": null,
"deliveryInfo": null,
"srcDesc": null
}
],
"rows": [
{
"rowId": "db55190a-82b8-472a-aebd-9051eb77d8b1",
"orderId": "8983235b-cd45-417a-b520-42e364d02e95",
"storeId": "638f97ee-2675-11ed-9d91-051517d411ac",
"rowType": 0,
"prtId": 6608,
"nnt": null,
"qnt": 1,
"prc": 168,
"prcDsc": null,
"dscUnion": null,
"dtn": null,
"prcLoyal": null,
"prcOptNds": null,
"supInn": null,
"dlvDate": null,
"qntUnrsv": null,
"prcFix": null,
"ts": null,
"mark": null
}
],
"statuses": [
{
"statusId": "08da869b-133d-44b2-8abc-c8da458047d3",
"orderId": "8983235b-cd45-417a-b520-42e364d02e95",
"rowId": null,
"storeId": "638f97ee-2675-11ed-9d91-051517d411ac",
"date": "2022-08-25T16:09:42.709034+03:00",
"status": 100,
"rcDate": "2022-08-25T16:09:42.709034+03:00",
"cmnt": null,
"ts": null
}
]
}
Объект ответаОбъект ответа
| Имя |
Тип |
Описание |
| headers |
Header[] |
Массив заголовков заказов |
| rows |
Row[] |
Массив строк заказов |
| statuses |
Status[] |
Массив статусов заказов |
Объект ответа Header(заголовок)Объект ответа Header(заголовок)
| Имя |
Тип |
Описание |
| orderId |
GUID |
Уникальный код заказа. |
| storeId |
GUID |
Уникальный код аптеки, на которой сделан заказ |
| issuerId |
GUID |
Уникальный код аптеки, которая выдает заказ (для самовывоза) |
| src |
string |
Источник заказа |
| num |
string |
Номер заказа |
| date |
datetime |
Дата заказа в формате ISO8601 с указанием часового пояса |
| name |
string |
Имя покупателя |
| mPhone |
string |
Номер телефона |
| payType |
string |
Тип оплаты |
| payTypeId |
int |
ИД типа оплаты |
| summary |
string |
Дисконтная карта |
| ae |
int |
|
| unionId |
GUID |
ИД совместной покупки |
| ts |
datetime |
Отметка времени, в формате ISO8601. Представляет собой дату и время создания или обновления заголовка сервисом yaVapteke |
| delivery |
bool |
|
| deliveryInfo |
string |
|
| srcDesc |
string |
|
Объект ответа Row(строка заказа)Объект ответа Row(строка заказа)
| Имя |
Тип |
Описание |
| rowId |
GUID |
Уникальный код строки заказа |
| orderId |
GUID |
Уникальный код заказа |
| storeId |
GUID |
Уникальный код аптеки, на которой сделан заказ |
| rowType |
int |
Тип строки (0 - наличие, 1 - предзаказ) |
| prtId |
string |
Уникальный код партии. |
| nnt |
int |
Код товара (Код товара, выгружаемый в прайс-листе в поле CODE) - устарело! |
| qnt |
float |
Количество в заказе |
| prc |
decimal |
Цена товара в момент заказа |
| prcDsc |
decimal |
Цена товара, обещанная покупателю в момент оформления заказа |
| dscUnion |
string |
Признак дисконта |
| dtn |
decimal |
Дотация для единицы товара. |
| prcLoyal |
decimal |
Цена реализации со скидкой |
| prcOptNds |
decimal |
Цена поставки |
| supInn |
string |
ИНН поставщика |
| dlvDate |
datetime |
Дата поставки в формате ISO8601 |
| qntUnrsv |
float |
Количество незарезервированного товара |
| prcFix |
decimal |
Фиксированная цена |
| ts |
datetime |
Отметка времени, в формате ISO8601. Представляет собой дату и время создания или обновления строки сервисом yaVapteke |
| mark |
int |
|
Объект ответа Status(строка статуса)Объект ответа Status(строка статуса)
| Имя |
Тип |
Описание |
| statusId |
GUID |
Уникальный код статуса |
| orderId |
GUID |
Уникальный код заказа |
| rowId |
GUID |
Уникальный код строки заказа (заполняется только если статус на строку) |
| storeId |
GUID |
Уникальный код аптеки |
| date |
datetime |
Дата и время статуса |
| status |
int |
Код статуса |
| rcDate |
datetime |
Дата и время сброса резерва в формате ISO8601. Поле заполняется только для 100 статуса заказа. |
| cmnt |
string |
Комментарий |
| Ts |
datetime |
Отметка времени, в формате ISO8601. Представляет собой дату и время создания или обновления статуса сервисом yaVapteke(в нулевом часовом поясе) |
Если установлен срок хранения заказа на нашей стороне, то в rcDate передается время и дата равное дата заказа + установленные срок хранения заказа. Если срок хранения заказа не установлен, то rcDate = date
Неуспешный ответНеуспешный ответ
| HTTP статус |
Значение |
| 400 |
Bad Request. Полученные службой данные содержат ошибки. Информация об ошибке возвращается в теле ответа. |
| 401 |
Unauthorized. Токен авторизации неверный или истек срок его действия. |
| 403 |
Forbidden. У вас нет прав на выполнение данной операции. |
| 429 |
Too Many Requests. Слишком много запросов с одного IP адреса за промежуток времени. |
| 500 |
Internal Server Error. Ошибка сервиса. Если ошибка повторяется, сообщите, пожалуйста, разработчикам сервиса. |
Отправка информации о заказах¶
Клиенты, которые работают с заказами с сайта yaVapteke.ru, должны передавать информацию об изменениях в заказах, произошедших в аптеке, а также информацию о статусе заказов.
PUT v5/stores/{storeId}/orders_exchanger
ОписаниеОписание
Передать информацию по заказам аптеки storeId по протоколу v5
Параметры запросаПараметры запроса
| Имя |
Тип |
Обяз. |
Описание |
| storeId |
GUID |
• |
Идентификатор аптеки по справочнику yaVapteke |
Заголовки запросаЗаголовки запроса
| Имя |
Описание |
| Authorization |
Bearer token |
| Content-Type |
application/json |
Тело запросаТело запроса
Объект запроса
| Имя |
Тип |
Обяз. |
Описание |
| rows |
Row[] |
|
Массив строк заказов |
| statuses |
Status[] |
|
Массив статусов заказов |
Объект запроса Row(строка заказа)
| Имя |
Тип |
Обяз. |
Описание |
| rowId |
GUID |
• |
Уникальный код строки заказа |
| qntUnrsv |
float |
• |
Количество незарезервированного товара |
Объект запроса Status(статус заказа)
| Имя |
Тип |
Обяз. |
Описание |
| statusId |
GUID |
• |
Уникальный код статуса. Генерируется клиентским ПО |
| orderId |
GUID |
• |
Уникальный код заказа. Берется из обрабатываемого заказа |
| rowId |
GUID |
|
Уникальный код строки заказа (заполняется только если статус на строку). Берется из обрабатываемого заказа |
| storeId |
GUID |
• |
Уникальный код аптеки. Берется из обрабатываемого заказа |
| date |
datetime |
• |
Дата и время создания статуса в формате ISO8601 с указанием часового пояса |
| status |
int |
• |
Код статуса |
| rcDate |
datetime |
|
Дата и время сброса резерва в формате ISO8601 с указанием часового пояса. |
| cmnt |
string |
|
Комментарий |
Пример запросаПример запроса
Пример частичного подтверждения заказа.¶
PUT /v5/stores/638f97ee-2675-11ed-9d91-051517d411ac/orders_exchanger HTTP/1.1
Host: yavapteke.ru/YavaptekeAPI/
Authorization: Bearer 08da627f-6773-4112-8355-47c94c7ac717
Content-Type: application/json
Cache-Control: no-cache
{
"rows": [
{
"rowId": "db55190a-82b8-472a-aebd-9051eb77d8b1",
"qntUnrsv": 1
}
],
"statuses": [
{
"statusId": "08da869b-133d-44b2-8abc-c8da458047d3",
"orderId": "8983235b-cd45-417a-b520-42e364d02e95",
"storeId": "638f97ee-2675-11ed-9d91-051517d411ac",
"date": "2022-08-25T16:09:42.709034+03:00",
"rcDate": "2022-08-25T16:09:42.709034+03:00",
"status": 201
}
]
}
Статус 201 служит промежуточным для передачи информации о незарезервированном количестве товара. После него обязательно необходима отправка сообщения со статусом 213, после чего статус заказа изменяется на "Готов к выдаче" и покупателю отправляется СМС о готовности. В теге "rows" передаются только те строки заказа, по которым существует незарезервированное количество. Например в заказе 3 шт., а в наличии только 2, необходимо отправить "qntUnrsv": 1
Пример полного подтверждения заказа.¶
PUT /v5/stores/638f97ee-2675-11ed-9d91-051517d411ac/orders_exchanger HTTP/1.1
Host: yavapteke.ru/YavaptekeAPI/
Authorization: Bearer 08da627f-6773-4112-8355-47c94c7ac717
Content-Type: application/json
Cache-Control: no-cache
{
"statuses": [
{
"statusId": "08da869b-133d-44b2-8abc-c8da458047d3",
"orderId": "8983235b-cd45-417a-b520-42e364d02e95",
"storeId": "638f97ee-2675-11ed-9d91-051517d411ac",
"date": "2022-08-25T16:09:42.709034+03:00",
"rcDate": "2022-08-25T16:09:42.709034+03:00",
"status": 200
}
]
}
ВНИМАНИЕ! После отправки статуса 200 или 201, даже если заказ подтвержден частично, ОБЯЗАТЕЛЬНО требуется отправка статуса 213.
Только после этого статус заказа в системе измениться на "Готов к выдаче" и покупателю будет отправлено СМС о готовности заказа. (За исключением того случая, когда заказ необходимо отменить полностью, в этом случае отправляется статус 202)
Пример отправки подтверждения готовности заказа.
PUT /v5/stores/638f97ee-2675-11ed-9d91-051517d411ac/orders_exchanger HTTP/1.1
Host: yavapteke.ru/YavaptekeAPI/
Authorization: Bearer 08da627f-6773-4112-8355-47c94c7ac717
Content-Type: application/json
Cache-Control: no-cache
{
"statuses": [
{
"statusId": "08da869b-133d-44b2-8abc-c8da458047d3",
"orderId": "8983235b-cd45-417a-b520-42e364d02e95",
"storeId": "638f97ee-2675-11ed-9d91-051517d411ac",
"date": "2022-08-25T16:10:42.709034+03:00",
"rcDate": "2022-08-25T16:10:42.709034+03:00",
"status": 213
}
]
}
Успешный ответУспешный ответ
| HTTP cтатус |
Значение |
| 201 |
Created. Данные успешно записаны |
Пример ответаПример ответа
Неуспешный ответНеуспешный ответ
| HTTP статус |
Значение |
| 400 |
Bad Request. Полученные службой данные содержат ошибки. Информация об ошибке возвращается в теле ответа. |
| 401 |
Unauthorized. Токен авторизации неверный или истек срок его действия |
| 403 |
Forbidden. У вас нет прав на выполнение данной операции |
| 429 |
Too Many Requests. Слишком много запросов с одного IP адреса за промежуток времени |
| 500 |
Internal Server Error. Ошибка сервиса. Если ошибка повторяется, сообщите, пожалуйста, разработчикам сервиса |