Техническая документация

Блинчик — Courier API

Версия 1.0.0 Спецификация OpenAPI 3.0 Базовый URL https://blaravel.cicada.kz/api Авторизация Bearer / Sanctum

Контракт REST API курьерского приложения «Блинчик». Отдельный гвард courier (Laravel Sanctum). Регистрация выполняется по коду подтверждения в WhatsApp; доступ к заказам открывается только после подтверждения курьера администратором. Все ответы в формате JSON, денежные значения — в тенге (целые числа).

1АвторизацияРегистрация, вход, профиль, токен устройства

1.1 POST /courier/register/send-code Публичный
Шаг 1 регистрации — выслать код в WhatsApp
Тело запроса (обязательно)
ПолеТипНаличиеОписание
phonestringобязательно пример: +7 707 123 45 67
Ответы
200Код отправлен
409Курьер с таким номером уже есть
422Ошибка валидации
502WhatsApp-шлюз недоступен
1.2 POST /courier/register Публичный
Шаг 2 регистрации — проверить код и создать курьера (status=pending)
Тело запроса (обязательно)
ПолеТипНаличиеОписание
phonestringобязательно пример: +7 707 123 45 67
namestringобязательно пример: Асхат
codestringобязательно пример: 4821
car_numberstringопционально пример: 777 ABC 02
passwordstringопциональноОпционально — чтобы потом входить по паролю
fcm_tokenstringопционально
platformandroid | iosопционально
Ответы
200Заявка создана, выдан токен (но заказы недоступны до подтверждения)
409Дубликат телефона
422Неверный код / валидация
1.3 POST /courier/login/send-code Публичный
Выслать код для входа (если у курьера не задан пароль)
Тело запроса (обязательно)
ПолеТипНаличиеОписание
phonestringобязательно
Ответы
200Код отправлен
404Курьер не найден
1.4 POST /courier/login Публичный
Вход по телефону + пароль ИЛИ код WhatsApp
Тело запроса (обязательно)
ПолеТипНаличиеОписание
phonestringобязательно
passwordstringопциональноЕсли у курьера задан пароль
codestringопциональноЕсли входит по коду
fcm_tokenstringопционально
platformandroid | iosопционально
Ответы
200Успешный вход
401Неверный пароль/код
404Курьер не найден
1.5 GET /courier/me Требует токен
Профиль + статус модерации
Ответы
200Профиль
401Не авторизован
1.6 POST /courier/device-token Требует токен
Сохранить/обновить FCM-токен устройства
Тело запроса (обязательно)
ПолеТипНаличиеОписание
fcm_tokenstringобязательно
platformandroid | iosопционально
Ответы
200Сохранено
1.7 POST /courier/logout Требует токен
Выход (удаляет токен устройства и access-токен)
Тело запроса
ПолеТипНаличиеОписание
fcm_tokenstringопционально
Ответы
200Выход выполнен

2СменаСмена курьера и инкассация

2.1 POST /courier/shift/start Требует токен
Выйти на смену (стать онлайн)
Ответы
200Смена открыта
403Курьер не подтверждён / заблокирован
2.2 POST /courier/shift/end Требует токен
Завершить смену (офлайн + фиксация итогов)
Ответы
200Смена закрыта
2.3 GET /courier/shift/summary Требует токен
Сводка смены (экран «Смена и инкассация»)
Ответы
200Сводка

3ЗаказыЛента заказов и развоз

3.1 GET /courier/orders/available Требует токен
Лента «Доступные» — заказы на доставку, ещё не взятые
Ответы
200Список
403Не подтверждён
3.2 GET /courier/orders/my Требует токен
Мои активные заказы (взятые, не закрытые)
Ответы
200Список
3.3 POST /courier/orders/{id}/take Требует токен
Взять заказ (атомарно — двое не заберут один)
Параметры пути
ПолеТипНаличиеОписание
idintegerпуть
Ответы
200Заказ взят
409Заказ уже взят другим
3.4 POST /courier/orders/{id}/status Требует токен
Сменить статус развоза

Допустимые переходы: accepted→picked_up→on_way→delivered; отмена (canceled) доступна до вручения. На on_way/delivered/canceled клиенту уходит пуш.

Параметры пути
ПолеТипНаличиеОписание
idintegerпуть
Тело запроса (обязательно)
ПолеТипНаличиеОписание
statuspicked_up | on_way | delivered | canceledобязательно
Ответы
200Статус обновлён
404Заказ не найден/не ваш
422Недопустимый переход
3.5 POST /courier/orders/{id}/cash Требует токен
Подтвердить приём наличных (для инкассации)
Параметры пути
ПолеТипНаличиеОписание
idintegerпуть
Тело запроса
ПолеТипНаличиеОписание
amountintegerопциональноЕсли не передан — берётся сумма заказа
Ответы
200Наличные зафиксированы
3.6 POST /courier/location Требует токен
Обновить координаты курьера (когда в пути)
Тело запроса (обязательно)
ПолеТипНаличиеОписание
latnumber (float)обязательно пример: 42.3151
lonnumber (float)обязательно пример: 69.5871
Ответы
200Принято
Модели данных
M1SimpleOk
ПолеТипНаличиеОписание
successbooleanопционально пример: True
messagestringопционально
M2Error
ПолеТипНаличиеОписание
successbooleanопционально пример: False
messagestringопционально пример: Текст ошибки
statusstringопциональноДля 403 — статус модерации (pending/blocked)
M3Courier
ПолеТипНаличиеОписание
idintegerопционально пример: 12
namestringопционально пример: Асхат
phonestringопционально пример: 77071234567
avatarstringопционально
car_numberstringопционально пример: 777 ABC 02
statuspending | approved | blockedопционально пример: approved
is_onlinebooleanопционально пример: True
M4Shift
ПолеТипНаличиеОписание
idintegerопционально
started_atstring (date-time)опционально
ended_atstring (date-time)опционально
is_onlinebooleanопционально
M5ShiftSummary
ПолеТипНаличиеОписание
orders_countintegerопциональноДоставлено за смену пример: 7
cash_totalintegerопциональноСобрано наличными (к сдаче), ₸ пример: 18400
is_onlinebooleanопционально
M6OrderCard
ПолеТипНаличиеОписание
idintegerопционально пример: 827
delivery_addressstringопционально пример: мкр Нурсат, д. 12, кв. 34
latstringопционально пример: 42.3151
lonstringопционально пример: 69.5871
priceintegerопционально пример: 4200
delivery_priceintegerопционально пример: 700
payment_typestringопционально пример: cash
payment_statusstringопционально пример: pending
is_cashbooleanопционально пример: True
enterprise_idintegerопционально пример: 1
courier_statusstringопционально
special_instructionstringопционально пример: Домофон 34, 3 этаж
created_atstring (date-time)опционально
M7OrderFullнаследует OrderCard
ПолеТипНаличиеОписание
phonestringопционально пример: 77011112233
cash_collectedbooleanопционально пример: False
cash_amountintegerопционально
itemsobject[]опционально