Общие сведения
{
"X-API-VERSION": "v1", # Specify api version
"Authorization": "Bearer {token}", # Use auth token given at POST /authotization
"Content-Type": "application/json",
"Accept": "application/json"
}
- Endpoint prefix: https://api.fastriver.ru/api/partner/ (ex.: POST https://api.rocket-delivery.ru/api/partner/delivery_requests)
- Headers запроса указаны справа
- Формат запроса и ответа JSON API https://jsonapi.org/
Жизненный цикл заявки
Основной флоу работы над заявкой
- Партнёр создаёт заявку
POST delivery_requests
. После создания Fastriver валидирует данные и, если что-то неверно, возвращаем заявку с информацией об ошибках валидации в полеvalidation_errors
- Партнёр обновляет заявку
PATCH delivery_requests/:uuid
пока она не перейдёт в статусvalidated
. Этот значит Fastriver принял заявку в работу и добавили в маршрут, если она уже была согласована - Для проверки доступности доставки в выбранные дату и время используется
GET delivery_requests/:uuid/time_intervals
. Город доставки обязательно должен быть задан до использования метода. Основные сценарии использования метода: обновить дату и адрес у заявки и запросить метод или сделать запрос с указанием в параметрах новой даты и координат доставки. Если в ответе на запрос пустой массив, то стоит попробовать другую дату. При получении одного или нескольких интервалов егоid
записывается в полеtime_interval_id
доставки. Валидация поляtime_interval_id
настраивается под Партнёра: если Партнёр согласовывает доставки самостоятельно и не согласовывает время с клиентом, то поле можно оставить пустым, Fastriver подберёт оптимальный и доступный интервал для доставки самостоятельно - При необходимости загрузки печатных документов для доставки (например.: Договор с клиентом, Согласие на обработку ПДН и тп) Партнёр загружает их через
POST delivery_requests/:uuid/document
- Если согласованием заявки занимается Fastriver, то дальше Fastriver будет обзванивать клиента и как только договоримся о встрече обновим статус
delivery_status
наscheduled
- Если необходимо обновить заявку после того как Fastriver принял её в работу, то Партнёр также обновляет её
PATCH delivery_requests/:uuid
. Можно указывать только те поля, которые надо обновить- Если меняются контактные данные пользователя, то Fastriver просто обновляет их
- Если меняется адрес, дата или время, то Fastriver будет заново согласовывать (опять же, если это на нашей стороне) и ставить доставку в маршрут
- Далее Fastriver осуществляет доставку и отправляем колбэки с происходящими событиями на
callback_url
, указанный в заявке. Альтернативно следить за её статусом можно, запрашивая статусыdelivery_status
иdelivery_request_status
GET delivery_requests/:uuid
. - После того как Fastriver успешно доставил продукт, идентифицировал клиента и перепроверил все документы и фотографии со встречи, Fastriver переводит заявку в статус
executed
- Партнёр скачивает фотографии и проверяет их (поля
photos
,signed_photos
в доставке)- Ecли всё ок, то подтверждает выполнение заявки
PATCH delivery_requests/:uuid/confirm
и процесс завершается - Ecли есть вопросы или замечания, то отклоняет выполнение заявки
PATCH delivery_requests/:uuid/reject
с указанием причины. Fastriver по возможности решаем возникшие вопросы без повторного выезда и вновь переводим заявку в статусexecuted
, Партнёр начинает повторную проверку. Если повторная встреча необходима, Fastriver возвращаем заявку в работу (validated
), согласовываем новую доставку и едем к Клиенту и возвращаемся к п. 8, пока Партнёр не будет удовлетворён проведённой встречей
- Ecли всё ок, то подтверждает выполнение заявки
- Для отмены заявки (например, клиент передумал) Партнёр шлёт
DELETE delivery_requests/:uuid
- доступно до тех пор, пока заявка не исполнена
Список методов
Method | APIver | Slug | Description |
---|---|---|---|
POST |
v1 |
authentications |
Получение временного токена для авторизации |
GET |
v1 |
authentications |
Обновление временного токена |
DELETE |
v1 |
authentications |
Разлогиниться |
GET |
v1 |
delivery_requests |
Список заявок с фильтрами и пагинацией |
GET |
v1 |
delivery_requests/:uuid |
Информация о статусе заявки |
POST |
v1 |
delivery_requests |
Создание заявки |
PATCH |
v1 |
delivery_requests/:uuid |
Обновление данных заявки |
GET |
v1 |
delivery_requests/:uuid/time_intervals |
Временные интервалы по заявке (только свободные) |
GET |
v2 |
delivery_requests/:uuid/time_intervals |
Временные интервалы по заявке (все, с указанием флага доступности) |
GET |
v1 |
delivery_requests/time_intervals |
Проверка доступности доставки и временные интервалы (только свободные) |
GET |
v2 |
delivery_requests/time_intervals |
Проверка доступности доставки и временные интервалы (все, с указанием флага доступности) |
PATCH |
v1 |
delivery_requests/:uuid/confirm |
Подтверждение исполнения заявки |
PATCH |
v1 |
delivery_requests/:uuid/reject |
Отклонение исполнения заявки |
DELETE |
v1 |
delivery_requests/:uuid |
Отмена заявки |
POST |
v1 |
delivery_requests/:uuid/document |
Загрузка печатной формы для доставки |
POST |
v1 |
delivery_requests/:uuid/call_please |
Сообщить, что клиент просит с ним связаться |
POST |
v2 |
delivery_requests/:uuid/transfer_delivery |
Перенести встречу (для Парнёров, доставляющих в собственном приложении) |
POST |
v2 |
delivery_requests/:uuid/complete_delivery |
Завершить встречу (для Парнёров, доставляющих в собственном приложении) |
GET |
v1 |
delivery_requests/:uuid/ delivery_photos/:token |
Скачивание фотографии по заявке |
GET |
v1 |
products |
Список продуктов для доставки |
GET |
v1 |
photo_types |
Список типов фотографий с доставки |
GET |
v1 |
cancel_reasons |
Список причин отмены заявки |
GET |
v1 |
reject_reasons |
Список причин отклонения заявки |
GET |
v1 |
cities |
Список городов доставки |
GET |
v1 |
delivery_request_statuses |
Список статусов заявок на доставку |
GET |
v1 |
delivery_statuses |
Список статусов доставки |
GET |
v1 |
package_documents |
Список загруженных документов по заявкам |
GET |
v1 |
package_documents/:id |
Информация о загруженной печатной форме |
DELETE |
v1 |
package_documents/:id |
Удаление печатной формы по доставке |
Аутентификация
Получение токена
Аутентификация по логину и паролю. Возвращает токен для последующей авторизации запросов и время его действия. Для этого метода Header Authorization игнорируется
Запрос
{
"login": "bot@company.com",
"password": "UKAtyyfGQBGTRb29fQFmDtgSdwS5eL4J"
}
POST authentications
Parameter | Type | Required | Description |
---|---|---|---|
login | String | * | Логин пользователя |
password | String | * | пароль пользователя |
Ответ
{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjozNCwidmFsaWRhdGlvbiI6IjR4V3pvRDg5SGJvN29VRFJ4NlM3VjZaUiIsImV4cGlyYXRpb24iOjE1OTc1MzQ5Mjd9.5OIVKRc4DE-oaArv8GCq6HNotA3G5qqag3cehym9AuY" # token для последующей авторизации запросов
"expires_at": 1597448435 # unix timestamp когда истечёт токен
}
Parameter | Type | Description |
---|---|---|
token | String | Токен для авторизации, подставляется в Headers запрос |
expires_at | Int | unix-timestamp времени действия токена |
Обновление токена
Проверяет аутентификацию и возвращает свежий токен
Запрос
GET authentications
Ответ
{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjozNCwidmFsaWRhdGlvbiI6IjR4V3pvRDg5SGJvN29VRFJ4NlM3VjZaUiIsImV4cGlyYXRpb24iOjE1OTc1MzQ5Mjd9.5OIVKRc4DE-oaArv8GCq6HNotA3G5qqag3cehym9AuY" # token для последующей авторизации запросов
"expires_at": 1597448435 # unix timestamp когда истечёт токен
}
Parameter | Type | Description |
---|---|---|
token | String | Токен для авторизации, подставляется в Headers запрос |
expires_at | Int | unix-timestamp времени действия токена |
Логаут
DELETE authentications
Работа с заявкой
Список заявок
Возвращает информацию по заявкам, соответствующим выбранным фильтрам и пагинации, сортированную по порядку времени созданиязаявки
Запрос
GET delivery_requests?filter[status]=validated&page=2
Parameter | Type | Example | Description |
---|---|---|---|
filter[city] | String | Москва или moscow | Город доставки (см. список городов), если не указано, то все города |
filter[date_gte] | Date | 2022-01-01 | Нижняя граница для плановой/фактической даты доставки включительно, если не указано, то ограничения нет |
filter[date_lte] | Date | 2022-04-01 | Верхняя граница для плановой/фактической даты доставки включительно, если не указано, то ограничения нет |
filter[request_date_gte] | Date | 2022-01-01 | Нижняя граница для даты, указанной в изначальной заявке, включительно, если не указано, то ограничения нет |
filter[request_date_lte] | Date | 2022-04-01 | Верхняя граница для даты, указанной в изначальной заявке, включительно, если не указано, то ограничения нет |
filter[external_id] | String | R123456 | Поиск по ID доставки по системе Партнёра |
filter[status] | String | validated | Статус заявки на доставку (см. статусы заявок) |
filter[delivery_status] | String | completed | Статус доставки (см. статусы доставок) |
filter[demo] | Boolean false | false | Фильтрует заявки по признаку demo |
filter[addressee] | String | Иванов | Поиск по Фамилии для физ. лиц или Названию компании/ИНН для юр. лиц адресату |
filter[product_id] | String | credit_card | Код доставляемого продукта (см. список продуктов) |
filter[created_by_id] | Int | 123 | ID менеджера, создавшего заявку |
pate | Int | 3 | Номер страницы, на 1 странице выводим 20 заявок, общее кол-во заявок выводится в тэге meta ответа |
Ответ
{
"data": [...] # массив заявок
"meta": {
"total": 30
}
}
Сериализация одной заявки в ответе совпадает с ответом GET delivery_requests/:uuid
Просмотр заявки
Возвращает информацию по заявке на доставку и самим доставкам - актуальной и всему архиву, если ездили несколько раз: статус, согласованное время, если согласовываем мы, результаты опроса и скоринга клиента, фотографии со встречи
Запрос
GET delivery_requests/:uuid
Ответ
{
"data": {
"id": "0f6e0d39-1475-43c1-bd3f-681c6c9d1cf4" # Номер заявки
"type": "delivery_request",
"attributes": {
"uuid": "0f6e0d39-1475-43c1-bd3f-681c6c9d1cf4", # Номер заявки
"external_id": "PS112233" # Номер заявки по системе партнёра для удобства сверки
"status": "executed", # Статус заявки
"delivery_status": "completed", # Статус доставки
"destination": { # Данные об адресате по заявке в обфусцированном виде, чтобы защитить ПДн
# информация об адресате
"mobile_phone": "+79260****90", # телефон клиента
"first_name": "З.", # имя клиента
"last_name": "Синий", # фамилия клиента
"patronymic": "Д.", # отчество клиента
"email": "zi*****ba@sezam.sin", # email
"birthday": "10.11.1969", # день рождения
"company_name": "ООО Ромашка", # Название компании или ИП
"inn": "123456789012" # ИНН компании или ИП
},
"delivery_city": "moscow", # город доставки, см. Справочник городов доставки
"address": "ул Сезам, д 75А стр 13, кв 43", # адрес доставки
"date": "20.08.2020", # желаемая дата доставки
"time_interval_id": 2 # желаемый интервал времени доставки
"notes": "бизнес центр, звоните, выйду", # коментарий клиента/Партнёра к доставке
"product": "credit_card_visa", # код продукта к доставке см. Список продуктов
"client_coordination_url": "https://s.fastriver.ru/f92192f9-f803-474f-bd1e-2c3d3f96a749", # ссылка на страницу согласования и просмотра информации о доставки для клиента
"created_at": 1597448435 # unixtimestamp времени создания заявки
"updated_at": 1597448435 # unixtimestamp времени создания заявки
"cancel_reason_code": "duplicate", # код причины отмены заявки
"cancel_reason_comment": "Уже была такая", # комментарий к отмене заявки
"reject_reason_code": "bad_photos", # код причины отклонения заявки
"reject_reason_comment": "Фото паспорта бликует", # коментарий к отклонению заявки
"demo": false, # признак текстовой заявки
"callback_url": "https://example.net/callback", # пусть для отправки колбэков с ивентами по доставке
"precise": false, # признак доставки к точному времени
"created_by_id": 15, # ID пользователя, создавшего заявку
"created_by_name": "Иванов Иван", # ФИО пользователя, создавшего заявку
"marketing_channel": "telegram", # Канал привлечения клиента
"coordination": {
"lat": 58.234935, # Широта точки доставки
"lon": 35.352342 # Долгота точки доставки
},
"validation_errors": {
"address": ["адрес за пределами зоны доставки"],
"mobile_phone": ["обязательно для заполнения"]
},
"package_barcode": "Штрих код конверта"
},
"relationships": {
"active_delivery": { "data": {"id":"f92192f9-f803-474f-bd1e-2c3d3f96a749","type":"active_delivery"} },
"deliveries": {
"data": [
{ "id": "f92192f9-f803-474f-bd1e-2c3d3f96a749", "type": "delivery" },
{ "id": "9dc6827b-ec8d-402a-be6b-239450b887e5", "type": "delivery" },
]
},
"time_interval": { "data": { "id": "2", "type": "time_interval" } }
}
},
"included": [
{
"id":"f92192f9-f803-474f-bd1e-2c3d3f96a749",
"type":"delivery",
"attributes": {
"status":"scheduled",
"date": "21.08.2020", # дата доставки,
"notes":"Molestiae dolores voluptatem ut.",
"scoring": { # Результаты анкеты опросника и оценки клиента, настраиваются индивидуально для партнёра
"drunk": false,
"3rd_party": false,
"comment": "Приятный человек, квартира обставлена богато"
},
"destination": { # итоговая информамция о клиенте, может отличаться от завки, например, во время доставки может смениться телефон клиента
"mobile_phone":"+79260****90",
"first_name": "З.", # имя клиента
"last_name": "Синий", # фамилия клиента
"patronymic": "Д.", # отчество клиента
"email": "zi*****ba@sezam.sin", # email
"birthday":"31.08.2000",
"company_name":"ООО Улица сезам", # наименование компании (при доставке юр. лицу)
"address": "ул Сезам, д 75А стр 13, кв 43", # адрес доставки
"lat": 50.4389573,
"lon": 30.34592
},
"photos": [ # Фотографии со встречи
{
"type": "passport_main", # тип фото, см. Список типов фотографий
"url": "https://expiring.url", # ссылка на полноразмерное фото (5-10Mb)
"medium_url": "https://expiring.url", # ссылка на сжатые фото с минимальной потерей качества (0.5-1Mb)
"thumb_url": "https://expiring.url", # ссылка на сильно сжатые фото для превью (0.1Mb)
"proxy_url": "https://api.fastriver.ru/api/partner/delivery_photos/653aef44-28d4-4c5f-ad99-7e5f4de2d616",
"partner_type": 2, # id типа в системе Партнёра для удобства линковки (число или строка)
"signature": "ae637d8653220c50cf01c823b73581899c7a72ad",
"ip": "74.34.54.23", # ip адрес курьера, откуда загружено фото
"ext": "jpg", # расширение файла с фотографией
"mime_type": "image/jpeg", # MIME-type фотографии
"uploaded_at": 1598889130 # время загрузки фото
}, # ...
],
"agent_info": { # расширенная информация о представителе
"id": 125, # ID представителя по системе Fastriver
"inn": "72309420984", # указывается, если ИНН используется как ID представителя
"external_id": "A123", # ID представителя по системе партнёра
"name": "Иванов Виктор Петрович", # ФИО представителя
"mobile_phone": "+74951183957" # Телефон Fatriver для связи по доставке в городе доставки
},
"city":"moscow", # код города доставки
"created_at": 1598889130, # unix-tmestamp создания доставки
"updated_at": 1598889130, # unix-tmestamp обновления доставки
"completed_at": 1598889130, # unix-tmestamp загрузки фото и завершения доставки
"failure_reason": null, # код причины переноса доставки, заполняется для статуса failed
"failure_comment": null, # комментарий причины переноса доставки, заполняется для статуса failed
"demo": false, # флаг тестовой доставки
"service_time_fact": 135, # фактическое время встречи в секундах
"time_interval_id": 3, # согласованный интервал доставки
"payable": false,
"fact_lat": 30.34592, # фактические координаты встречи, фиксируется по геопозиции приложения при завершении встречи
"fact_lon": 50.4389573, # фактические координаты встречи, фиксируется по геопозиции приложения при завершении встречи
"fact_address": "Адрес, который может отличаться от планового" # фактические адрес встречи, фиксируется по геопозиции приложения при завершении встречи
},
"relationships": {
"time_interval": {
"data": {
"id": "3",
"type": "time_interval"
}
}
}
},
{
"id":"f92192f9-f803-474f-bd1e-2c3d3f96a749",
"type":"delivery",
"attributes": {
"status":"failed",
"date": "20.08.2020", # дата доставки,
"notes":"Molestiae dolores voluptatem ut.",
"scoring": {}, # Результаты анкеты опросника и оценки клиента, настраиваются индивидуально для партнёра
"destination": { # итоговая информамция о клиенте, может отличаться от завки, например, во время доставки может смениться телефон клиента
"mobile_phone":"+79260****90",
"first_name": "З.", # имя клиента
"last_name": "Синий", # фамилия клиента
"patronymic": "Д.", # отчество клиента
"email": "zi*****ba@sezam.sin", # email
"birthday":"31.08.2000",
"company_name":"ООО Улица сезам", # наименование компании (при доставке юр. лицу)
"address": "ул Сезам, д 70А", # адрес доставки
"lat": 50.4389573,
"lon": 30.34592
},
"photos": [],
"agent_info": { # расширенная информация о представителе
"id": 125, # ID представителя по системе Fastriver
"inn": "72309420984", # указывается, если ИНН используется как ID представителя
"external_id": "A123", # ID представителя по системе партнёра
"name": "Иванов Виктор Петрович", # ФИО представителя
"mobile_phone": "+74951183957" # Телефон Fatriver для связи по доставке в городе доставки
},
"city":"moscow", # код города доставки
"created_at": 1598889130, # unix-tmestamp создания доставки
"updated_at": 1598889130, # unix-tmestamp обновления доставки
"completed_at": 1598889130, # unix-tmestamp загрузки фото и завершения доставки
"failure_reason": "transfer_before_meeting", # код причины переноса доставки, заполняется для статуса failed
"failure_comment": "Созвонился с клиентом, говорит сегодня не может, завтра встреча по другому адресу", # комментарий причины переноса доставки, заполняется для статуса failed
"demo": false, # флаг тестовой доставки
"service_time_fact": null, # фактическое время встречи в секундах
"time_interval_id": 3, # согласованный интервал доставки
"payable": false,
"fact_lat": null, # фактические координаты встречи, фиксируется по геопозиции приложения при завершении встречи
"fact_lon": null, # фактические координаты встречи, фиксируется по геопозиции приложения при завершении встречи
"fact_address": null # фактические адрес встречи, фиксируется по геопозиции приложения при завершении встречи
},
"relationships": {
"time_interval": {
"data": {
"id": "4",
"type": "time_interval"
}
}
}
},
{
"id": 2,
"type": "time_interval",
"attributes": {
"id": 2 ,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00"
}
},
{
"id": 3,
"type": "time_interval",
"attributes": {
"id": 2 ,
"from": 840,
"to": 960,
"code": "day",
"name": "15:00-17:00"
}
},
{
"id": 4,
"type": "time_interval",
"attributes": {
"id": 2 ,
"from": 960,
"to": 1080,
"code": "evening",
"name": "17:00-19:00"
}
}
]
}
Информация о заявке
Parameter | Type | Description |
---|---|---|
id | UUID | UUID заявки |
uuid | UUID | UUID заявки |
name | String | Название города по КЛАДР |
external_id | String | Номер заявки по системе партнёра для удобства сверки |
status | String | Статус заявки (см. статусы заявок) |
delivery_status | String | Статус доставки (см. статусы доставок) |
delivery_city | String | Код города (региона) доставки (см. список городов) |
destination | Object | Данные об адресате заявки в обфусцированном виде, чтобы защитить ПДн |
destination[mobile_phone] | String | Телефон клиента |
destination[first_name] | String | Имя клиента |
destination[last_name] | String | Фамилия клиента |
destination[patronymic] | String | Отчество клиента |
destination[email] | String | email клиента |
destination[birthday] | String | День рождения клиента |
destination[company_name] | String | Название компании или ИП |
destination[inn] | String | ИНН компании или ИП |
address | String | Адрес доставки |
date | String | Желаемая дата доставки |
time_interval_id | Int | ID желаемого временного интервала |
notes | String | Комментарий клиента/Партнёра к заявке (например, код домофона, информация как и когда найти Клиента или какие дополнительные документы собрать) |
product | String | Код продукта (см. список продуктов) |
client_coordination_url | String | Cсылка на страницу согласования и просмотра информации о доставки для клиента, можно направить туда клиента после заполнения заявки на сайте Партнёра |
created_at | Int | unix timestamp времени создания заявки |
updated_at | Int | unix timestamp времени обновления заявки |
cancel_reason_code | String | Код причины отмены заявки |
cancel_reason_comment | String | Комментарий к отмене заявки |
reject_reason_code | String | Код причины отклонения заявки |
reject_reason_comment | String | Коментарий к отклонению заявки |
demo | Boolean | Признак тестовой заявки (см. тестирование) |
callback_url | String | URL для отправки колбэков с ивентами по доставке (см. колбэки) |
precise | Boolean | Признак доставки к точному времени. Возможность такой доставки уточняйте у менеджера |
coordination | Object | Координаты точки доставки |
coordination[lat] | Float | Широта точки доставки |
coordination[lon] | Float | Долгота точки доставки |
marketing_channel | String | Канал привлечения клиента |
validation_errors | Object | Информация об ошибках валидации заявки, содержит ошибочное поле и массив сообщений об ошибках в этом поле (см. валидации) |
package_barcode | String | Штрих код конверта |
Информация о доставке
Parameter | Type | Description |
---|---|---|
id | UUID | UUID доставки |
uuid | UUID | UUID доставки |
status | String | Статус доставки (см. статусы доставок) |
notes | String | Комментарий к заявке дополняется информацией от операторов |
date | String | Плановая/фактическая дата доставки |
time_interval_id | Int | ID планового/фактического временного интервала (в зависимости от статуса доставки) |
city | String | Код города доставки (см. список городов) |
demo | Boolean | Признак тестовой заявки (см. тестирование) |
fact_lat | Float | Широта точки проведения встречи по данным GPS представителя |
fact_lon | Float | Долгота точки проведения встречи по данным GPS представителя |
fact_address | String | Фактический адрес встречи по данным GPS представителя |
service_time_fact | Int | Фактическое время встречи (в сек) |
failure_reason | String | Код причины переноса доставки (см. причины переноса) |
failure_comment | String | Комментарий представителя к переносу доставки |
payable | Boolean | Признак оплачиваемости доставки (оплачиваются все успешные встречи и переносы не по вине Fastriver, например, если найдены ошибки в печатных документах, переданных Партнёром, детали уточняйте у менеджера) |
scoring | Object | Ответы на вопросы после встречи (см. вопросы после встречи) |
destination | Object | Данные об адресате заявки в обфусцированном виде, чтобы защитить ПДн. Могут отличаться от заяаки, потому что уточняются при согласовании встречи |
destination[mobile_phone] | String | Телефон клиента |
destination[first_name] | String | Имя клиента |
destination[last_name] | String | Фамилия клиента |
destination[patronymic] | String | Отчество клиента |
destination[email] | String | email клиента |
destination[birthday] | String | День рождения клиента |
destination[company_name] | String | Название компании или ИП |
destination[inn] | String | ИНН компании или ИП |
destination[address] | String | Адрес встречи |
destination[lat] | String | Широта точки встречи |
destination[lon] | String | Долгота точки встречи |
photos | Array | Массив фотографий со встречи |
photos[][type] | String | Тип фотографии (см. типы фотографий) |
photos[][url] | String | Ссылка для скачивания оригинала фото максимального качества (см. хранение фото) |
photos[][thumb_url] | String | Ссылка для скачивания превью фото минимального размера |
photos[][medium_url] | String | Ссылка для скачивания фото небольшого размера обжатого с минимальной потерей качества |
photos[][proxy_url] | String | Ссылка для скачивания оригинала фото из кабинета, а не из S3 |
photos[][ip] | String | ip-адрес устройства представителя, загрузившего фото |
photos[][partner_type] | String | Тип фото по системе Партнёра |
signed_photos | String | Ссылка на скачивание архива с фотографиями, подписанными ЭЦП (см. подпись фото) |
agent_info | Object | Информация о представителе, который провёл встречу |
agent_info[inn] | String | Указывается, если ИНН используется как ID представителя |
agent_info[externa_id] | String | ID представителя в системе Партнёра |
agent_info[name] | String | ФИО представителя |
city | String | Код города доставки |
created_at | Int | unix timestamp времени создания доставки |
updated_at | Int | unix timestamp времени обновления доставки |
completed_at | Int | unix timestamp времени завершения доставки |
failure_reason | String | Код причины переноса доставки, заполняется для статуса failed |
failure_comment | String | Комментарий причины переноса доставки, заполняется для статуса failed |
service_time_fact | Int | Фактическое время встречи в секундах, заполняется для статуса completed |
fact_lat | Float | Факстические координаты встречи, заполняется для статуса completed |
fact_lon | Float | Факстические координаты встречи, заполняется для статуса completed |
fact_address | String | Факстический адрес встречи, заполняется для статуса completed |
demo | Boolean | Флаг тестовой доставки |
Создание заявки
Создание заявки на доставку (можно даже с пустым телом запроса), в ответе вернёт uuid
, который далее используется для просмотра, изменения и управления заявкой. Также в ответе придут ошибки валидации для полей. В случае, если все данные правильные и обязательные поля присутствуют, то заявка перейдёт в статус validated
и Fastriver возьмёт её в работу.
Запрос
POST delivery_requests
{
"data": {
"attributes": {
# информация об адресате
"mobile_phone": "+79261234567", # телефон клиента, обязательно
"additional_phones": ["+79267654321", "+79263334444"], # дополнительные телефоны клиента
"first_name": "Зилибоба", # имя клиента, обязательно
"last_name": "Синий", # фамилия клиента, обязательно
"patronymic": nil, # отчество, обязательно при наличии
"email": "ziliboba@sezam.sin", # email, используется для согласования заявки, обязательно при наличии
"company_name": "ООО Ракета", # обязательно при досставке Юр лицу
"birthday": "10.11.1969", # не обязательно, помогает верифицировать клиента
"documents": [ , # документы клиента для верификации, TBD
{
"type": "rf_passport", # тип документа (пока только Пасспорт РФ)
"series": "4515", # серия документа
"number": "123456", # номер документа
"issued_at": "20.01.2019", # дата выдачи документа
"valid_to": "20.01.2029", # действует до (если применимо, например для загран паспорта РФ)
"issuer": "ОВД Москвы", # кем выдано
"issuer_departner": "123-321", # код подразделения
"registration_address": "Воробьёвы горы, влд. 1", # адрес регистрации
}
],
# информация о доставке
"delivery_city": "Москва", # обязательно, город доставки по нашему справочнику (напр. 'moscow' или 'Москва'), см. Справочник городов доставки
"address": "ул Сезам, д 75А стр 13, кв 43", # обязательно, адрес доставки
"date": "20.08.2020", # дата доставки, указывается, если доставка уже согласована (не обязательно, влияет на стоимость доставки)
"time_interval_id": 2, # желаемый интервал доставки, доступные можно получить методом /time_intervals
"time_interval_name": "10:00-12:00" , # название желаемого интервал доставки, используется вместо time_interval_id, доступные можно получить методом /time_intervals
"precise": true, # указывается, если требуется доставка к конкретному времени, по умолчанию false, влияет на стоимость доставки
"notes": "бизнес центр, звоните, выйду", # коментарий клиента/Партнёра к доставке (не обязательно)
"product": "credit_card_visa", # код продукта к доставке см. Список продуктов (обязательно, влияет на стоимость доставки)
"callback_url": "https://api.nekoe_api/url", # урл партнёра, на который будут отправляться данные post-запросом об изменениях статусов заявки
"external_id": "PS112233", # Номер заявки по системе партнёра, для удобства сверки (обязателен при наличии)
"demo": true, # указывается при отладке API, весь процесс прогоняется по системе как если бы шла реальная заявка с задержками 5 сек на этап, по умолчанию false
"marketing_channel": "telegram", # Канал привлечения клиента
"external_agent_id": "A234274" # ID представителя по системе партнёра
}
}
}
Parameter | Type | Required | Description |
---|---|---|---|
mobile_phone | String | * | Мобильный телефон клиента |
additional_phones | Array | Дополнительные телефоны клиента | |
first_name | String | * | Имя клиента |
last_name | String | * | Фамилия клиента (при отсутствие можно передать Неизвестно ) |
patronymic | String | Отчество клиента (обязательно при наличии) | |
String | Дополнительный канал коммуникации с клиентом для отправки уведомлений о доставке и информации о согласовании встречи | ||
birthday | String | День рождения клиента, не обязательно, помогает верифицировать клиента | |
documents | Array | Документы клиента для верификации (TBD) | |
delivery_city | String | * | город доставки по нашему справочнику (напр. 'moscow' или 'Москва'), (см. список городов). Возможно автоматическое определение по адресу доставки, Fastriver находит зону доставки по координатам адреса и заполняет это поле, но если адреса нет или он вне зоны доставки, то поле останется пустым |
address | String | Да, если партнёр согласовывает доставки сам | Адрес доставки |
date | Date | Да, если партнёр согласовывает доставки сам | Дата доставки |
time_interval_id | Int | Да, если партнёр согласовывает доставки сам | Временной интервал встречи |
time_interval_name | String | Да, если партнёр согласовывает доставки сам | Название временного интервала встречи, если не указано time_interval_id |
precise | Boolean | Признак доставки к точному времени. Возможность такой доставки уточняйте у менеджера. По умолчанию false | |
notes | String | Комментарий клиента/Партнёра к заявке (например, код домофона, информация как и когда найти Клиента или какие дополнительные документы собрать) | |
product | String | * | Код доставляемого продукта (см. список продуктов) |
company_name | String | Да для Юр. лиц | Название компании при открытии счёта для юридического лица |
inn | String | Да для Юр. лиц | ИНН компании при открытии счёта для юридического лица |
external_id | String | Крайне желателен | ID заявки по системе Партнёра (крайне желателен) |
callback_url | String | URL для отправки колбэков с ивентами по доставке (см. колбэки) | |
demo | Boolean | Признак тестовой заявки (см. тестирование). По умолчанию false | |
marketing_channel | String | Канал привлечения клиента | |
external_agent_id | String | Для Партнёров, которые ведут доставку полностью в своём ПО, указывается ID представителя для синхронизации данных по заявкам в систему Fastriver |
Ответ
Ответ как при GET delivery_requests/:uuid
Обновление заявки
Обновление данных заявки. Пока заявка находится в статусе created
будет всегда возвращаться http код 200 и после обновления будет запускаться процесс валидации заявки, при успешном его прохождении она будет переведена в статус validated
. После этого при невалидных изменениях данных заявки будет возвращаться http код 422 с пояснением об ошибке в теле ответа
Данные адресата (ФИО, телефон и проч.) можно менять пока доставка не находится в финальном статусе. Данные об адресе и/или дате доставки можно менять за день до её проведения.
Запрос
PATCH delivery_requests/:uuid
Структура запроса повторяет POST delivery_requests
. Возможно отправлять информацию отдельно по каждому полю, по несколько полей или все данные заявки целиком
Ответ
Ответ как при GET delivery_requests/:uuid
Отмена заявки
Отмена заявки. Возможна до момента первой доставки. Если отмена невозможна придёт ответ 422 с указанием ошибки
Запрос
DELETE delivery_requests/:uuid
{
"data": {
"attributes": {
"cancel_reason_code": "client_refused", см. Список причин отмены заявки
"cancel_reason_comment": "Клиент передумал" # Тут текстовый комментарий, если надо что-то уточнить
}
}
}
Parameter | Type | Required | Description |
---|---|---|---|
cancel_reason_code | String | * | Код причины отмены заявки (см. причины отмены заявки) |
cancel_reason_comment | String | Комментарий к отмене заявки, если надо что-то уточнить/сообщить |
Ответ
Ответ как при GET delivery_requests/:uuid
[v1] Поиск временных интервалов по заявке {#time-intervals-v1}
Получение доступных интервалов по заявке. Для этого необходимо заполнить продукт, город, точку доставки и дату. Если они уже сохранены в заявке, то запрос можно отправлять без параметров. Указание в параметрах точки или даты проверит доступность интервалов в другом месте и/или в другое время без изменения данных заявки (удобно, если заявка уже в работе и доставка согласована, чтобы не потерять предыдущий временной слот). id доступного интервала используется в поле time_interval_id доставки
Запрос
GET delivery_requests/:uuid/time_intervals
{
"date": "2021-02-01", # дата для проверки интервалов, необязательно, если уже указана в заявке
"lat": 12.32423434, # широта места доставки, необязательно, если адрес уже указан в заявке
"lon": 12.32423434 # долгота места доставки, необязательно, если адрес уже указан в заявке
}
Parameter | Type | Description |
---|---|---|
date | Date | Дата для проверки интервалов, необязательно, если уже указана в заявке |
lat | Float | Щирота места доставки, необязательно, если адрес уже указан в заявке |
lon | Float | Долгота места доставки, необязательно, если адрес уже указан в заявке |
Ответ
{
"data":[
{
"id": 1,
"type": "time_interval",
"attributes": {
"id": 1 ,
"from": 600,
"to": 720,
"code": "morning",
"name": "10:00-12:00"
}
},
{
"id": 2,
"type": "time_interval",
"attributes": {
"id": 1 ,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00"
}
}
]
}
Parameter | Type | Description |
---|---|---|
id | Int | ID временного интервала |
from | Int | Начало временного интервала (в минутах от 00 часов, 600 - это 10:00) |
to | Int | Конец временного интервала (в минутах от 00 часов, 720 - это 12:00) |
code | String | Код временного интервала латиницец |
name | String | Название интервала в формате HH:MM-HH:MM |
[v2] Поиск временных интервалов по заявке
Получение доступных интервалов по заявке. Для этого необходимо заполнить продукт, город, точку доставки и дату. Если они уже сохранены в заявке, то запрос можно отправлять без параметров. Указание в параметрах точки или даты проверит доступность интервалов в другом месте и/или в другое время без изменения данных заявки (удобно, если заявка уже в работе и доставка согласована, чтобы не потерять предыдущий временной слот). id доступного интервала используется в поле time_interval_id доставки. В отличие от v1 вернёт все возможные интервалы в городе с указанием флага доступности
Запрос
GET delivery_requests/:uuid/time_intervals
{
"date": "2021-02-01", # дата для проверки интервалов, необязательно, если уже указана в заявке
"lat": 12.32423434, # широта места доставки, необязательно, если адрес уже указан в заявке
"lon": 12.32423434 # долгота места доставки, необязательно, если адрес уже указан в заявке
}
Parameter | Type | Description |
---|---|---|
date | Date | Дата для проверки интервалов, необязательно, если уже указана в заявке |
lat | Float | Щирота места доставки, необязательно, если адрес уже указан в заявке |
lon | Float | Долгота места доставки, необязательно, если адрес уже указан в заявке |
Ответ
{
"data":[
{
"id": 1,
"type": "time_interval",
"attributes": {
"id": 1 ,
"from": 600,
"to": 720,
"code": "morning",
"name": "10:00-12:00",
"available": false
}
},
{
"id": 2,
"type": "time_interval",
"attributes": {
"id": 1 ,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00",
"available": true
}
}
]
}
Parameter | Type | Description |
---|---|---|
id | Int | ID временного интервала |
from | Int | Начало временного интервала (в минутах от 00 часов, 600 - это 10:00) |
to | Int | Конец временного интервала (в минутах от 00 часов, 720 - это 12:00) |
code | String | Код временного интервала латиницец |
name | String | Название интервала в формате HH:MM-HH:MM |
available | Boolean | Флаг доступности |
[v1] Поиск доступности доставки
Получение доступных интервалов без заявки. Запрос отвечает на несколько вопросов. Доступна ли вообще доставка по указанному адресу/координатам (если недоступна будет ответ с кодом 422 "Адрес находится вне зоны доставки"")? Если доступна, то на какие ближайшие дни в какие временные интервалы она возможна?
В версии v1 в ответе указывают только доступные интервалы
id
доступного интервала используется в поле time_interval_id
при создании заявки или name
доступного интервала используется в поле time_interval_name
при создании заявки.
При одновременном запрос с теми же координатами для второго запроса будет ответ 429 (Запрос слотов по этим координатам уже в обработке
)
Запрос
GET delivery_requests/time_intervals
{
"date": "2021-02-01", # дата начала проверки интервалов, необязательно, по умолчанию дата выполнения запроса
"check_days": 4, # количество дней вместе с датой проверки, до куда будет проверяться доступность доставки (максимум 7, по умолчанию 1, то есть только запрашиваемая дата)
"lat": 12.32423434, # широта места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
"lon": 12.32423434, # долгота места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
"address": "г. Пушкин, ул Пушкина, д 5", # адрес места доставки, обязательно, если не указаны координаты
"product": "product_code", # код доставляемого продукта, необязательно, по умолчанию берём продукт с минимальным временем встречи
}
Parameter | Type | Required | Description |
---|---|---|---|
date | Date | Дата начала проверки интервалов, необязательно (по умолчанию дата выполнения запроса) | |
check_days | Int | Количество дней вместе с датой проверки, до куда будет проверяться доступность доставки (максимум 7, по умолчанию 1, то есть только запрашиваемая дата) | |
lat | Float | Если нет address | Широта места доставки, обязательно, если не указан адрес (имеет приоритет над адресом) |
lon | Float | Если нет address | Долгота места доставки, обязательно, если не указан адрес (имеет приоритет над адресом) |
address | String | Если нет lat+lon | Адрес места доставки, обязательно, если не указаны координаты |
product | String | Код доставляемого продукта, необязательно, по умолчанию берём продукт с минимальным временем встречи |
Ответ
{
"data":[
{
"id": "2021-02-01",
"type": "delivery_date",
"attributes": {
"date": "2021-02-01",
"time_intervals": [
{
"id": 2,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00"
}
]
}
},
{
"id": "2021-02-02",
"type": "delivery_date",
"attributes": {
"date": "2021-02-02",
"time_intervals": [
{
"id": 1,
"from": 600,
"to": 720,
"code": "morning",
"name": "10:00-12:00"
},
{
"id": 2,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00"
}
]
}
},
]
}
Parameter | Type | Description |
---|---|---|
id | Date | Потенциальная дата доставки |
time_intervals | Array | Варианты интервалов для доставки |
time_intervals[id] | Int | ID временного интервала |
time_intervals[from] | Int | Начало временного интервала (в минутах от 00 часов, 600 - это 10:00) |
time_intervals[to] | Int | Конец временного интервала (в минутах от 00 часов, 720 - это 12:00) |
time_intervals[code] | String | Код временного интервала латиницец |
time_intervals[name] | String | Название интервала в формате HH:MM-HH:MM |
[v2] Поиск доступности доставки
Получение доступных интервалов без заявки. Запрос отвечает на несколько вопросов. Доступна ли вообще доставка по указанному адресу/координатам (если недоступна будет ответ с кодом 422 "Адрес находится вне зоны доставки"")? Если доступна, то на какие ближайшие дни в какие временные интервалы она возможна?
В версии v2 в ответе есть все возможные интервалы, доступность отмечена флагом available
id доступного интервала используется в поле time_interval_id при создании заявки.
При одновременном запрос с теми же координатами для второго запроса будет ответ 429 (Запрос слотов по этим координатам уже в обработке
)
Запрос
GET delivery_requests/time_intervals
{
"date": "2021-02-01", # дата начала проверки интервалов, необязательно, по умолчанию дата выполнения запроса
"check_days": 4, # количество дней вместе с датой проверки, до куда будет проверяться доступность доставки (максимум 7, по умолчанию 1, то есть только запрашиваемая дата)
"lat": 12.32423434, # широта места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
"lon": 12.32423434, # долгота места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
"address": "г. Пушкин, ул Пушкина, д 5", # адрес места доставки, обязательно, если не указаны координаты
"product": "product_code", # код доставляемого продукта, необязательно, по умолчанию берём продукт с минимальным временем встречи
}
Parameter | Type | Required | Description |
---|---|---|---|
date | Date | Дата начала проверки интервалов, необязательно (по умолчанию дата выполнения запроса) | |
check_days | Int | Количество дней вместе с датой проверки, до куда будет проверяться доступность доставки (максимум 7, по умолчанию 1, то есть только запрашиваемая дата) | |
lat | Float | Если нет address | Широта места доставки, обязательно, если не указан адрес (имеет приоритет над адресом) |
lon | Float | Если нет address | Долгота места доставки, обязательно, если не указан адрес (имеет приоритет над адресом) |
address | String | Если нет lat+lon | Адрес места доставки, обязательно, если не указаны координаты |
product | String | Код доставляемого продукта, необязательно, по умолчанию берём продукт с минимальным временем встречи |
Ответ
{
"data":[
{
"id": "2021-02-01",
"type": "delivery_date",
"attributes": {
"date": "2021-02-01",
"time_intervals": [
{
"id": 1,
"from": 600,
"to": 720,
"code": "morning",
"name": "10:00-12:00",
"available": false
},
{
"id": 2,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00",
"available": true
}
]
}
},
{
"id": "2021-02-02",
"type": "delivery_date",
"attributes": {
"date": "2021-02-02",
"time_intervals": [
{
"id": 1,
"from": 600,
"to": 720,
"code": "morning",
"name": "10:00-12:00",
"available": true
},
{
"id": 2,
"from": 720,
"to": 840,
"code": "afternoon",
"name": "12:00-14:00",
"available": true
}
]
}
},
]
}
Parameter | Type | Description |
---|---|---|
id | Date | Потенциальная дата доставки |
time_intervals | Array | Варианты интервалов для доставки |
time_intervals[id] | Int | ID временного интервала |
time_intervals[from] | Int | Начало временного интервала (в минутах от 00 часов, 600 - это 10:00) |
time_intervals[to] | Int | Конец временного интервала (в минутах от 00 часов, 720 - это 12:00) |
time_intervals[code] | String | Код временного интервала латиницец |
time_intervals[name] | String | Название интервала в формате HH:MM-HH:MM |
time_intervals[available] | Boolean | Флаг доступности |
Подтверждение заявки
Подтверждение исполнения заявки. Когда Партнёр получил фотографии со встречи, бумажные оригиналы документов или подтверждающие встречу материалы, необходимо отправить этот запрос, чтобы завершить работу по заявке. Выполненные заявки автоматически подтверждаются спустя 7 дней, если не были указаны замечания и исполнения заявки не было отклонено
Запрос
PATCH delivery_requests/:uuid/confirm
Ответ
Ответ как при GET delivery_requests/:uuid
Отклонение заявки
Отклонение исполнения заявки. Если у Партнёра есть замечания по фотографиям, документам или другим материалам встречи, он может отклонить выполнение заявки с указанием причины и комментарием с подробным описанием действий по устранению замечаний
Звпрос
PATCH delivery_requests/:uuid/reject
{
"data": {
"attributes": {
"reject_reason_code": "bad_printed_documents", # см. [Список причин отказа](https://www.notion.so/API-Public-4cd549f1a226476da87f92c7fe0c39d1)
"reject_reason_comment": "На странице 12 основной Оферты неразборчиво написана фамилия клиента", # максимально подробный комментарий Партнёра, ясно описывающий что необходимо поправить по заявке
}
}
}
Parameter | Type | Required | Description |
---|---|---|---|
reject_reason_code | String | * | Код причины отклонения заявки (см. причины отклонения заявки) |
reject_reason_comment | String | * | Максимально подробный комментарий Партнёра, ясно описывающий, что необходимо поправить по заявке |
Ответ
Ответ как при GET delivery_requests/:uuid
Перезвонить клиенту
Сообщить представителю (в день встречи) или операторам (в другой день), чтобы связались с клиентом.
Запрос
POST delivery_requests/:uuid/call_please
Ответ
В случае, если статус заявки не позволяет выполнить запрос: HTTP Status 405 Method Not Allowed
Успешное выполнение: HTTP Status 200
Перенос доставки *
Для Партнёров, представители которых проводят встречу не в приложении Fastriver Когда представитель Партнёра переносит встречу в приложении Партнёра, Партнёр шлёт запрос о переносе доставки, чтобы отразить результат встречи в системе Fastriver
Запрос
POST delivery_requests/:uuid/transfer_delivery
{
"reason": "transfer_before_meeting",
"comment": "Уехал в отпуск до сентября",
"next_date": "2022-09-01",
"address": "Бульвар Капуцинов, д 10"
}
Parameter | Type | Required | Description |
---|---|---|---|
reason | String | * | Код причины переноса доставки |
comment | String | Комментарий представителя о причине переноса, помогает согласовать новую встречу и разобраться в ситуации Клиента | |
next_date | Date | Указывается, когда представитель смог связаться с клиентом и договориться о проведении следующей встречи (например, клиент говорит "я сегодня уехал по работе, давайте завтра", и представитель указывает завтрашнюю дату) | |
address | String | Указывается, когда представитель смог связаться с клиентом и договориться об адресе проведения следующей встречи |
Ответ
Ответ как при GET delivery_requests/:uuid
Завершение доставки *
Для Партнёров, представители которых проводят встречу не в приложении Fastriver Когда представитель Партнёра завершает встречу в приложении Партнёра, Партнёр шлёт запрос о завершении доставки, чтобы отразить результат встречи в системе Fastriver
Запрос
POST delivery_requests/:uuid/complete_delivery
{
"lat": 33.333,
"lon": 55.555
}
Parameter | Type | Required | Description |
---|---|---|---|
lat | Float | Широта фактического места встречи | |
lon | Float | Долгото фактического места встречи |
Ответ
Ответ как при GET delivery_requests/:uuid
Валидации
Заявка на доставку валидируется каждый раз при обновлении. Пока ошибки остаются она остаётся в статусе Черновик
Parameter | Required | Валидация |
---|---|---|
last_name | * | Русские буквы и дефис |
first_name | * | Русские буквы и дефис |
patronymic | Русские буквы и дефис | |
mobile_phone | * | Формат +7 и 10 цифр телефона |
Проверяется формат email | ||
birthday | Должна быть дата в прошлом | |
delivery_city | * | Код города, должен быть включен для Партнёра, для настройки обращайтесь к менеджеру |
product | * | Код продукта, должен быть включен для Партнёра, для настройки обращайтесь к менеджеру |
address | Да, если Партнёр согласовывает заявку сам | Должен быть распаршен dadata, координаты однозначно определены |
date | Да, если Партнёр согласовывает сам | Не должна быть в прошлом, для день-в-день доставки проверяется, чтобы время обновления не превышало отсечки в городе (например, "в Казани день-в-день доставки принимаются до 15:00 местного времени") |
time_interval_id | Да, если Партнёр согласовывает сам | Проверяем наличие этого слота в городе для Партнёра |
external_id | Да, если имеется | |
callback_url | Должен начинаться с https | |
company_name | ||
inn | Валидируем контрольное число https://ru.wikipedia.org/wiki/Контрольноечисло#НомераИНН | |
marketing_channel |
Документы для доставки
Список документов
Список загруженных Печатных форм по заявкам.
Запрос
GET package_documents?filter[delivery_request_uuid]=0f6e0d39-1475-43c1-bd3f-681c6c9d1cf4
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
filter[delivery_request_uuid] | UUID | * | UUID заявки на доставку |
Ответ
{
"data": [
{
"id": "191",
"type": "document",
"attributes": {
"id": 191,
"url": "https://example.net/1.pdf",
"thumb_url": "https://example.net/1.png",
"created_at": 1606996120,
"updated_at": 1606996120
}
},
{
"id": "192",
"type": "document",
"attributes": {
"id": 192,
"url": "https://example.net/2.pdf",
"thumb_url": "https://example.net/2.png",
"created_at": 1606996121,
"updated_at": 1606996121
}
},
...
],
"meta": {
"total": 2
}
}
Parameter | Type | Description |
---|---|---|
id | Int | ID документа |
url | String | Ссылка для скачивания PDF версии документа (docx и другие типы будут конвертироваться в PDF для унификации печати) |
thumb_url | String | Ссылка для скачивани JPG preview документа |
original_url | String | Ссылка для скачивани оригинального файла документа |
created_at | Int | unix-timestamp времени создания документа |
updated_at | Int | unix-timestamp времени обновления документа |
Просмотр документа
Просмотре информации о документе по id
Запрос
GET package_documents/:id
Ответ
{
"data": {
"id": "191",
"type": "document",
"attributes": {
"id": 191,
"url": "https://example.net/1.pdf",
"thumb_url": "https://example.net/1.png",
"created_at": 1606996120,
"updated_at": 1606996120
}
}
}
Parameter | Type | Description |
---|---|---|
id | Int | ID документа |
url | String | Ссылка для скачивания PDF версии документа (docx и другие типы будут конвертироваться в PDF для унификации печати) |
thumb_url | String | Ссылка для скачивани JPG preview документа |
original_url | String | Ссылка для скачивани оригинального файла документа |
created_at | Int | unix-timestamp времени создания документа |
updated_at | Int | unix-timestamp времени обновления документа |
Загрузка документа
Загрузка документа для печати и доставки клиенту на подпись. Доступно для заявки в статусе validated
. Принимаются документы в форматах: pdf, docx (jpg, png, tiff - по запросу, в разработке)
Запрос
POST delivery_requests/:uuid/document
{
"file": File
"external_id": "PS112233" # Номер документа по системе партнёра, для удобства сверки (обязателен при наличии)
}
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
file | Multipart data | * | Тело файла для загрузки | |
external_id | String | Номер документа по системе партнёра для удобства сверки |
Ответ
{
"data": {
"id": "191",
"type": "document",
"attributes": {
"id": 191,
"url": "https://example.net/1.pdf",
"thumb_url": "https://example.net/1.png",
"created_at": 1606996120,
"updated_at": 1606996120
}
}
}
Parameter | Type | Description |
---|---|---|
id | Int | ID документа |
url | String | Ссылка для скачивания PDF версии документа (docx и другие типы будут конвертироваться в PDF для унификации печати) |
thumb_url | String | Ссылка для скачивани JPG preview документа |
original_url | String | Ссылка для скачивани оригинального файла документа |
created_at | Int | unix-timestamp времени создания документа |
updated_at | Int | unix-timestamp времени обновления документа |
Удаление документа
DELETE package_documents/:id
Фотографии по доставке
Просмотр фотографии
Получение фотографии по id
Запрос
GET delivery_requests/:delivery_request_uuid/delivery_photos/:photo_id
Parameter | Type | Description |
---|---|---|
version_kind | String | не указано - оригинальная фотография;medium - фото небольшого размера, обжатого с минимальной потерей качества;thumb - превью фото минимального размера |
Ответ
Бинарные данные фотографии
Справочники
Продукты
Список продуктов Партнёра, доступных для доставки. Код продукта необходимо использовать при создании заявки на доставку. Как правило мы используем коды/ID продуктов по системе Партнёра, если они существуют
Запрос
GET products
Ответ
{
"data": [
{
"id": "credit_card_visa",
"type": "product",
"attributes": {
"name": "Кредитка VISA" ,
"code": "credit_card_visa",
"description": "Кредитка VISA для резидентов РФ"
}
},
{
"id": "debit_card_visa",
"type": "product",
"attributes": {
"name": "Дебетовая карта VISA" ,
"code": "debit_card_visa",
"description": "Дебетовая карта VISA для резидентов РФ"
}
},
...
],
"meta": {
"total": 10
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код/ID продукта |
code | String | Код/ID продукта |
name | String | Короткое название продукта |
description | String | Описание продукта |
Города
Список городов, в которых осуществляется доставка для Партнёра. Для проверки возможности доставки используется фильтрация по координатам точки доставки
Запрос
GET cities?filter[lat]=60.013964&filter[lon]=30.009201
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
lat | Float | Широта предполагаемой точки доставки | ||
lon | Float | Долгота предполагаемой точки доставки |
Ответ
{
"data": [
{
"id": "moscow",
"type": "city",
"attributes": {
"name": "Москва"
}
},
{
"id": "piter",
"type": "city",
"attributes": {
"name": "Санкт-Петербург"
}
},
...
],
"meta": {
"total": 29
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код/ID города |
name | String | Название города по КЛАДР |
Типы фото
Список типов фотографий со встречи
Запрос
GET photo_types
Ответ
{
"data": [
{
"id": "pasp_main",
"type": "photo_type",
"attributes": {
"name": "Главный разворот паспорта",
"partner_id": 2 // id типа в системе Партнёра для удобства линковки
}
},
{
"id": "pasp_reg",
"type": "photo_type",
"attributes": {
"name": "Страница с регистрацией",
"partner_id": 3
}
},
{
"id": "temp_reg",
"type": "photo_type",
"attributes": {
"name": "Временная регистрация",
"partner_id": 4
}
},
{
"id": "any_doc",
"type": "photo_type",
"attributes": {
"name": "Другое",
"partner_id": 99
}
},
],
"meta": {
"total": 4
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код/ID типа фото |
code | String | Код/ID типа фото |
name | String | Название типа фото |
partner_id | String/Int | id типа в системе Партнёра для удобства линковки, тип поля будет аналогичен типу в системе Партнёра |
Причины отмены заявки
Список причин для отмены заявки. Код причины используется при отмене заявки
Запрос
GET cancel_reasons
Ответ
{
"data": [
{
"id": "client_refused",
"type": "cancel_reason",
"attributes": {
"name": "Клиент отказался от доставки"
}
},
{
"id": "partner_declined",
"type": "cancel_reason",
"attributes": {
"name": "Отказали в выдаче продукта"
}
},
{
"id": "mistake",
"type": "cancel_reason",
"attributes": {
"name": "Заявку завели по ошибке"
}
},
{
"id": "other",
"type": "cancel_reason",
"attributes": {
"name": "Другое"
}
},
],
"meta": {
"total": 4
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код причины |
name | String | Название причины |
Причины отклонения заявки
Список причин для отклонения заявки. Код причины используется, когда есть замечания по исполнению заявки
Запрос
GET reject_reasons
Ответ
{
"data": [
{
"id": "bad_printed_documents",
"type": "reject_reason",
"attributes": {
"name": "Ошибка в бумажных документах"
}
},
{
"id": "missing_printed_documents",
"type": "reject_reason",
"attributes": {
"name": "Отсутствует одна или несколько страниц в бумажных документах"
}
},
{
"id": "bad_photos",
"type": "reject_reason",
"attributes": {
"name": "Замечания по фотографиям со встречи"
}
},
{
"id": "other",
"type": "reject_reason",
"attributes": {
"name": "Другое"
}
},
],
"meta": {
"total": 4
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код причины |
name | String | Название причины |
Причины переноса доставки
Список причин для переноса заявки
Запрос
GET failure_reasons
Ответ
{
"data": [
{
"id": "decline_on_call",
"type": "failure_reasons",
"attributes": {
"code": "decline_on_call",
"name": "Звонили заранее, продукт не нужен"
}
},
{
"id": "forgot_documents",
"type": "failure_reasons",
"attributes": {
"code": "forgot_documents",
"name": "Забыл документы на встречу"
}
},
{
"id": "no_time_for_meeting",
"type": "failure_reasons",
"attributes": {
"code": "no_time_for_meeting",
"name": "Не успеваю"
}
},
{
"id": "unknown",
"type": "failure_reasons",
"attributes": {
"code": "unknown",
"name": "Другое"
}
},
],
"meta": {
"total": 4
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код причины |
name | String | Название причины |
Статусы заявки
Список статусов заявки
Code | Name | Финальный | Описание |
---|---|---|---|
created |
Новая | No | Новая заявка зарегистрирована в системе, далее данные проходят валидацию и, если всё ок, то заявка переходит в статус validated. Заявка не поступит в работу до тех пор, пока не пройдёт все проверки |
validated |
Создана | No | Заявка прошла валидацию и идёт процесс согласования доставки и непосредственно доставки (за ним следить по статусу delivery_status) |
executed |
Исполнена | No | Доставка доставлена, фотографии со встречи загружены и проверены, подписанные документы доставлены Партнёру |
rejected |
Отклонена | No | Исполнение заявки не принято Партнёром и указаны замечания для исправления (см. PATCH delivery_requests/:uuid/reject ) |
canceled |
Отменена | Yes | Заявка отменена. Возможно только из статусов new и created (см. DELETE delivery_requests/:uuid ) |
confirmed |
Подтверждена | Yes | Исполнение заявки подтверждено Партнёром (см. PATCH delivery_requests/:uuid/confirm ) |
Запрос
GET delivery_request_statuses
Ответ
{
"data": [
{
"id": "created",
"type": "delivery_request_status",
"attributes": {
"name": "Создана"
}
},
{
"id": "validated",
"type": "delivery_request_status",
"attributes": {
"name": "Корректна"
}
},
{
"id": "executed",
"type": "delivery_request_status",
"attributes": {
"name": "Исполнена"
}
},
{
"id": "rejected",
"type": "delivery_request_status",
"attributes": {
"name": "Отклонена"
}
},
{
"id": "canceled",
"type": "delivery_request_status",
"attributes": {
"name": "Отменена"
}
},
{
"id": "confirmed",
"type": "delivery_request_status",
"attributes": {
"name": "Подтверждена"
}
}
],
"meta": {
"total": 6
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код причины |
name | String | Название причины |
Статусы доставки
Список статусов доставки
Code | Name | Финальный | Описание |
---|---|---|---|
pending |
В ожидании | No | Создана. ожидает согласования |
reserved |
Зарезервирована | No | Время доставки зарезервировано на 30 мин, ожидает подтверждения клиентом |
scheduled |
Запланирована | No | Время доставки согласовано с клиентом, доставка добавлена в маршрутный лист курьеру |
failed |
Не состоялась | Yes | Доставка сорвалась, например, клиент не отвечает или забыл паспорт, и нужна повторная доставка |
canceled |
Отменена | Yes | Доставка отменена, ехать к клиенту не нужно |
completed |
Доставлено | Yes | Доставка завершена, карта/документы переданы клиенту, сделаны нужные фотографии |
Запрос
GET delivery_statuses
Ответ
{
"data":[
{
"id": "pending",
"type": "delivery_status",
"attributes": {
"name": "В ожидании"
}
},
{
"id": "reserved",
"type": "delivery_status",
"attributes": {
"name": "Зарезервирована"
}
},
{
"id": "scheduled",
"type": "delivery_status",
"attributes": {
"name": "Запланирована"
}
},
{
"id": "canceled",
"type": "delivery_status",
"attributes": {
"name": "Отменена"
}
},
{
"id": "failed",
"type": "delivery_status",
"attributes": {
"name": "Не состоялась"
}
},
{
"id": "completed",
"type": "delivery_status",
"attributes": {
"name": "Доставлена"
}
}
],
"meta": {
"total": 6
}
}
Parameter | Type | Description |
---|---|---|
id | String | Код причины |
name | String | Название причины |
Колбэки
При изменении статусов заявки и доставки, также при возникновении определённых событий (напр. "не дозвонились") Fastriver имеет возможность уведомлять партнёра по API. Для инициации этого процесса необходимо указать в заявке поле callback_url. Множество отправляемых событий настраивается и может быть ограничено
callback_url (string) - поле в request_data заявки (например: 'https://url.url'), поле может быть пустым. Если callback_url не прописан, то отправка сообщения не производится
События отправляются post-запросом на callback_url заявки. Отправка считается успешной при получении кода http 200 в ответ. Если отправка не удалась, Fastriver пытается отправить ещё 10 раз через увеличивающиеся интервалы.
Только событие
{
"data": {
"id": "e4085f48-053d-41a2-9c7e-5eed624074ed",
"type": "external_callback",
"attributes": {
"external_id": "1-WF43GREWK",
"event": "complete",
"comment": "Доставили",
"created_at": 1623265246,
"delivery_request_status": "executed", // статус заявки
"delivery_status": "completed", // статус доставки
"date": "2022-07-12",
"address": "г Москва, ул Вятская, д 27 стр 1",
"coords": {
"lat": 55.7377144,
"lon": 37.82652
}
},
"relationships": {
"time_interval": {
"data": {
"id": 95,
"type": "time_interval"
}
}
}
},
"included": [
{
"id": 95,
"type": "time_interval",
"attributes": {
"id": 95,
"from": 1305,
"to": 1334,
"code": "short_2145_2215",
"name": "21:45-22:15"
}
}
]
}
Включая заявку и доставки
{
"data": {
"id":"e7d030d7-3421-4622-a690-f7f3514f2fe3",
"type":"external_callback",
"attributes": {
"event":"completed",
"comment":null,
"external_id":null,
"created_at":1677580513,
"delivery_status":"scheduled",
"delivery_request_status":"validated",
"date":"2021-12-23",
"address":"г Москва, ул 3-я Рыбинская, д 18 стр 22",
"coords":{
"lat":55.7896513,
"lon":37.6593023
}
},
"relationships": {
"time_interval": {
"data": {
"id":"9",
"type":"time_interval"
}
},
"delivery_request": {
"data": {
"id":"e7d030d7-3421-4622-a690-f7f3514f2fe3",
"type":"delivery_request"
}
}
}
},
"included":
[
{
"id":"9",
"type":"time_interval",
"attributes":
{
"id":9,
"from":600,
"to":1139,
"code":"all_day_short",
"name":"10:00-19:00"
}
},
{
"id":"0c8aee67-2611-44a5-9acf-1cbd25823f2b",
"type":"delivery",
"attributes":
{
"status":"scheduled",
"notes":null,
"scoring":{},
"date":"2021-12-23",
"failure_reason":null,
"failure_comment":null,
"demo":false,
"service_time_fact":null,
"time_interval_id":9,
"payable":false,
"cost":0,
"begins_at":1022,
"fact_lat":null,
"fact_lon":null,
"fact_address":null,
"repeat":true,
"destination":
{
"mobile_phone":"+7 (91****91",
"first_name":"М.",
"last_name":"Ефремова",
"patronymic":"Б.",
"email":"e***e@schinner-gleason.info",
"birthday":null,
"company_name":null,
"address":"г Москва, ул 3-я Рыбинская, д 18 стр 22",
"lat":55.7896513,
"lon":37.6593023
},
"photos":[],
"signed_photos":null,
"agent":null,
"agent_info":null,
"city":"moscow",
"created_at":1674125556,
"updated_at":1674125556,
"completed_at":null
}
},
{
"id":"e7d030d7-3421-4622-a690-f7f3514f2fe3",
"type":"delivery_request",
"attributes":
{
"uuid":"e7d030d7-3421-4622-a690-f7f3514f2fe3",
"external_id":null,
"status":"validated",
"delivery_city":null,
"date":null,
"time":null,
"time_interval_id":null,
"notes":null,
"product":null,
"validation_errors":{},
"process_errors":{},
"cancel_reason_code":null,
"cancel_reason_comment":null,
"reject_reason_code":null,
"reject_reason_comment":null,
"demo":false,
"callback_url":null,
"marketing_channel":null,
"precise":false,
"unread_comments_count":0,
"destination":
{
"mobile_phone":null,
"first_name":null,
"last_name":null,
"patronymic":null,
"email":null,
"birthday":null,
"company_name":null,
"inn":null
},
"created_by_id":null,
"created_by_name":null,
"zone_weight":null,
"address":null,
"coordination":
{
"lat":null,
"lon":null
},
"client_coordination_url":null,
"delivery_status":"scheduled",
"created_at":1674125556,
"updated_at":1677582451,
"package_barcode": "ШК"
},
"relationships":
{
"active_delivery":
{
"data":
{
"id":"0c8aee67-2611-44a5-9acf-1cbd25823f2b",
"type":"delivery"
}
},
"deliveries":
{
"data":
[
{
"id":"0c8aee67-2611-44a5-9acf-1cbd25823f2b",
"type":"delivery"
}
]
}
}
}
]
}
Parameter | Type | Description |
---|---|---|
id | UUID | UUID заявки на доставку |
external_id | String | Dнешний id заявки по системе Партнёра (если указан) |
event | String | Событие, которое вызывает отправку колбэка |
delivery_request_status | String | Cтатус заявки |
delivery_status | String | Cтатус доставки |
comment | String | Комментарий к событию, например, более подродная информация о причинах отмены или переноса доставки |
created_at | Int | unix-timestamp времения события |
date | Date | Планируемая/фактическая дата доставки (изменяется при пересогласовании доставки) |
address | String | Планируемый/фактический адрес доставки (изменяется при пересогласовании доставки) |
coords | Object | Координаты адреса доставки |
time_interval | TimeInterval | Информация о планируемом/фактическом интервале доставки (изменяется при пересогласовании доставки) |
Список событий
Event | Delivery request status | Delivery status | Описание |
---|---|---|---|
accept_delivery |
validated |
pending или scheduled |
Отправляется при успешном заведении заявки, когда она прошла все валидации |
transfer |
validated |
pending |
Отправляется при переносе доставки по заявке. Возможные причины: клиент просит перенести/не смогли связаться |
schedule |
validated |
scheduled |
Отправляется при согласовании доставки с клиентом. Если изначально Партнёр сам согласовывает доставки, то отправляется только при повторных согласованиях после переноса |
agent_selected |
validated |
scheduled |
Доставка закреплена за представителем. Отправляется утром в день доставки, до этого момента Фастривер регулярно перекидывает доставки между маршрутами, чтобы в итоге построить оптимальные пути |
meeting_started |
validated |
scheduled |
Отправляется, когда представитель приезал к Клиенту и начал встречу |
delivered |
validated |
completed |
Встреча проведена, документы подписаны, сфотографированы и отправлены в Фастривер. Далее они будут проходить внутреннюю проверку |
complete |
executed |
completed |
Завершение доставки. Фотографии проверены на соблюдение полноты данных и стандарта качества Партнёра |
repeat |
validated |
pending |
Отправляется, если мы приняли замечания по отклонённой заявке и необходима повторная встреча |
lose |
validated |
pending |
Перенос по инициативе представителя (не успел/не может доставить) |
fix |
executed |
completed |
Отправляется, если мы смогли исправить замечания по отклонённой заявке без дополнительной встречи |
decline_on_meeting |
executed |
failed |
Отказ на встрече. При очной встрече после ознакомления с документами клиент отказался от продукта |
wants_new_terms |
executed |
failed |
Просит другие условия или продукт. При очной встрече после ознакомления с документами клиент попросил другие условия или продукт |
error_documents |
executed |
failed |
Ошибка в документах. При очной встрече с клиентом оказалось, что в печатных документах допущена ошибка и необходима повторная встреча. Для новой встречи надо будет завести новую заявку |
no_contact |
validated |
pending |
Событие отправляется при неудачной попытке связаться с клиентом. Обычно мы звоним в течение трёх дней |
no_contact_at_all |
canceled |
canceled |
Событие отправляется при отмене заявки по причину недозвона до клиента продолжительное время |
decline_on_call |
canceled |
canceled |
Клиент отказался от доставки при предварительном звонке, встречи не было |
out_of_area |
canceled |
canceled |
Отправляется, если не доставляем по адресу заявки |
partner_refuse |
canceled |
canceled |
Партнёр попросил отказал клиенту в выдаче продукта. Представитель к клиенту не выезжал |
mistake |
canceled |
canceled |
Отправляется, если заявка заведена по ошибке |
already_delivered |
canceled |
canceled |
Отправляется, если заявка уже доставлена кем-то другим или клиент получил продукт в отделении |
another_person |
canceled |
canceled |
Отправляется, если на встречу/звонке человек, не совпадающий, с указанным в документах/информации по заявке |
duplicate |
canceled |
canceled |
Заявка дублирует информацию другой заявки |
no_passport |
canceled |
canceled |
Клиент не имеет/отказывается предоставлять паспорт |
no_registration |
canceled |
canceled |
Клиент не имеет регистрации |
no_photo |
canceled |
canceled |
Клиент отказывается от фотографирования |
Ошибки
HTTP коды
Http Code | Значение |
---|---|
200 | Успешный запрос |
401 | Ошибка аутентификации, неверный или истёкший токен |
403 | Ошибка авторизации, ресурс недоступен пользователю |
404 | Ресурс не найден |
405 | Состояние ресурса не позволяет выполнить запрос |
422 | Ошибка в параметрах запроса, невозможно исполнить запрос |
429 | Одновременный запрос с теми же параметрами |
500 | Внутренняя ошибка сервера |
Ответ с ошибкой
{
"error": "Пояснение о причинах возникновения ошибки"
}
При ответе коде ответа отличного от 200 в теле ответа будет более подробная информация об ошибке