Документация API¶
Авторизация в yaVapteke REST API¶
YaVapteke API поддерживает авторизацию на основе JWT токенов.
Для обращения к любому из ресурсов yaVapteke API требуется наличие JWT токена в заголовке Authorization HTTP запроса, с типом Bearer. При отсутствии токена API вернет 401 статус (Unauthorized), этот же статус вернется в случае, если время действия токена закончилось (токен выдается на определенное время). В обоих случаях нужно запросить новый токен.
Схема работы APIСхема работы API
Порядок выполнения авторизации на сервисах API 1. Получаем токен на сервере авторизации
2. Полученный токен (берется из поля access_token ответа авторизации) используется для запросов к API.
3. При получении от API статуса 401 (Unauthorized), т.е. по истечении срока годности токена, токен запрашивается повторно
Процессы работы с заказами¶
С определенной периодичностью опрашивается API для получения информации о новых или измененных заказах. Все полученные с сайта yaVapteke.ru заказы будут приняты и обработаны.
Схема движения заказа со статусамиСхема движения заказа со статусами
- Новый заказ
При получении нового заказа, если присутствуют строки с товаром из наличия, пытается бронировать все товары по этим строкам.
Если заказ со строками только из наличия, возможны следующие варианты:
1. Товары полностью зарезервировались - формируется и возвращается новый статус с кодом 200 на заголовок.
2. Товары полностью не зарезервировались - формируется и возвращается новый статус с кодом 202 на заголовок.
3. Товары зарезервировались частично - формируется и возвращается новый статус с кодом 201 на заголовок, а так же возвращаются строки заказа, по которым не хватило количества в наличии
- Сбор (комплектация) заказа
После того как заказ в аптеке был собран (укомплектован), необходимо отправить статус на заголовок 213.
- Отмена заказа аптекой
При отмене заказа формируется и возвращается новый статус (с новым уникальным идентификатором) отмены заказа по инициативе аптеки с кодом 212. Заказ снимается с резерва.
- Выкуп заказа
Если заказ был полностью выкуплен, то формируется и возвращается статус с кодом 210.
Статусы заказов, формируемые сайтом¶
Код |
Название |
Описание |
100 |
New |
Новый заказ |
Статусы заказов, формируемые аптекой¶
Код |
Название |
Описание |
200 |
Accepted |
Заказ принят аптекой. Формируется на заголовок |
201 |
PartiallyAccepted |
Заказ частично принят аптекой. Формируется на заголовок |
202 |
Rejected |
Отказ со стороны аптеки. Формируется на заголовок |
210 |
Purchased |
Заказ выкуплен. Формируется на заголовок |
213 |
Assembled |
Заказ собран (укомплектован). Формируется на заголовок |
Статус 201 служит промежуточным для передачи информации о незарезервированном количестве товара. После него обязательно необходима отправка сообщения со статусом 213, после чего статус заказа изменяется на "Готов к выдаче" и покупателю отправляется СМС о готовности.
Получение токена¶
Для выполнения запросов к API, необходимо получить JWT токен по адресу https://yavapteke.ru/YavaptekeAPI/connect/token
POST /connect/token
ОписаниеОписание
Получение авторизационного токена
Параметры запросаПараметры запросаПараметры этого запроса передаются в теле запроса, см. пример запроса
Имя |
Обяз. |
Описание |
client_id |
• |
Идентификатор клиента |
secret |
• |
Пароль клиента, полученный |
grant_type |
|
Тип авторизации. В данном случае всегда client_credentials |
Заголовки запросаЗаголовки запроса
Имя |
Описание |
Content-Type |
Должно иметь значение application/x-www-form-urlencoded |
Пример запросаПример запроса
HTTP
POST /connect/token HTTP/1.1
Host: yaVapteke.ru/YavaptekeAPI/
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache
client_id=3f37b142-e371-461e-924c-a913ff878534&client_secret=Pas$w0Rd
C# (RestSharp)
var client = new RestClient(" https://yavapteke.ru/YavaptekeAPI/connect/token");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("client_id", " 3f37b142-e371-461e-924c-a913ff878534");
request.AddParameter("client_secret", "Pas$w0Rd");
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
CURL
curl --location --request POST 'https://yavapteke.ru/YavaptekeAPI/connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id= 3f37b142-e371-461e-924c-a913ff878534' --data-urlencode 'client_secret=Pas$w0Rd'
Успешный ответУспешный ответ
HTTP cтатус |
Значение |
200 |
ОК. Запрос к сервису авторизации прошел успешно, в теле ответа содержится JSON с информацией о выданном токене. |
Пример ответаПример ответа
{
"access_token": "08da627f-6773-4112-8355-47c94c7ac717",
"expires_in": 3600,
"token_type": "Bearer"
}
Неуспешный ответНеуспешный ответ
HTTP статус |
Значение |
400 |
Полученные службой данные содержат ошибки. Информация об ошибке возвращается в теле ответа. |
500 |
Ошибка сервиса. Если ошибка повторяется, сообщите, пожалуйста, разработчикам сервиса |
Получение информации о заказах аптеки¶
Клиенты, которые работают с сайтом 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": null,
"nnt": 6608,
"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, 108 ,104 статусов заказа |
cmnt |
string |
Комментарий |
Ts |
datetime |
Отметка времени, в формате ISO8601. Представляет собой дату и время создания или обновления статуса сервисом yaVapteke(в нулевом часовом поясе) |
Неуспешный ответНеуспешный ответ
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 с указанием часового пояса. Поле заполняется только для 204 статуса заказа |
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. Ошибка сервиса. Если ошибка повторяется, сообщите, пожалуйста, разработчикам сервиса |