NAV
shell

Общие сведения

{
  "X-API-VERSION": "v1", # Specify api version
  "Authorization": "Bearer {token}", # Use auth token given at POST /authotization
  "Content-Type": "application/json",
  "Accept": "application/json"
}
  1. Endpoint prefix: https://api.fastriver.ru/api/partner/ (ex.: POST https://api.rocket-delivery.ru/api/partner/delivery_requests)
  2. Headers запроса указаны справа
  3. Формат запроса и ответа JSON API https://jsonapi.org/

Жизненный цикл заявки

alt text

Основной флоу работы над заявкой

  1. Партнёр создаёт заявку POST delivery_requests. После создания Fastriver валидирует данные и, если что-то неверно, возвращаем заявку с информацией об ошибках валидации в поле validation_errors
  2. Партнёр обновляет заявку PATCH delivery_requests/:uuid пока она не перейдёт в статус validated. Этот значит Fastriver принял заявку в работу и добавили в маршрут, если она уже была согласована
  3. Для проверки доступности доставки в выбранные дату и время используется GET delivery_requests/:uuid/time_intervals. Город доставки обязательно должен быть задан до использования метода. Основные сценарии использования метода: обновить дату и адрес у заявки и запросить метод или сделать запрос с указанием в параметрах новой даты и координат доставки. Если в ответе на запрос пустой массив, то стоит попробовать другую дату. При получении одного или нескольких интервалов его id записывается в поле time_interval_id доставки. Валидация поля time_interval_id настраивается под Партнёра: если Партнёр согласовывает доставки самостоятельно и не согласовывает время с клиентом, то поле можно оставить пустым, Fastriver подберёт оптимальный и доступный интервал для доставки самостоятельно
  4. При необходимости загрузки печатных документов для доставки (например.: Договор с клиентом, Согласие на обработку ПДН и тп) Партнёр загружает их через POST delivery_requests/:uuid/document
  5. Если согласованием заявки занимается Fastriver, то дальше Fastriver будет обзванивать клиента и как только договоримся о встрече обновим статус delivery_status на scheduled
  6. Если необходимо обновить заявку после того как Fastriver принял её в работу, то Партнёр также обновляет её PATCH delivery_requests/:uuid. Можно указывать только те поля, которые надо обновить
    1. Если меняются контактные данные пользователя, то Fastriver просто обновляет их
    2. Если меняется адрес, дата или время, то Fastriver будет заново согласовывать (опять же, если это на нашей стороне) и ставить доставку в маршрут
  7. Далее Fastriver осуществляет доставку и отправляем колбэки с происходящими событиями на callback_url, указанный в заявке. Альтернативно следить за её статусом можно, запрашивая статусы delivery_status и delivery_request_status GET delivery_requests/:uuid.
  8. После того как Fastriver успешно доставил продукт, идентифицировал клиента и перепроверил все документы и фотографии со встречи, Fastriver переводит заявку в статус executed
  9. Партнёр скачивает фотографии и проверяет их (поля photos, signed_photos в доставке)
    1. Ecли всё ок, то подтверждает выполнение заявки PATCH delivery_requests/:uuid/confirm и процесс завершается
    2. Ecли есть вопросы или замечания, то отклоняет выполнение заявки PATCH delivery_requests/:uuid/reject с указанием причины. Fastriver по возможности решаем возникшие вопросы без повторного выезда и вновь переводим заявку в статус executed, Партнёр начинает повторную проверку. Если повторная встреча необходима, Fastriver возвращаем заявку в работу (validated), согласовываем новую доставку и едем к Клиенту и возвращаемся к п. 8, пока Партнёр не будет удовлетворён проведённой встречей
  10. Для отмены заявки (например, клиент передумал) Партнёр шлёт 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 Отчество клиента (обязательно при наличии)
email 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 при создании заявки

Запрос

GET delivery_requests/time_intervals

{
  "date": "2021-02-01", # дата начала проверки интервалов, необязательно, по умолчанию дата выполнения запроса
  "check_days": 4, # количество дней вместе с датой проверки, до куда будет проверяться доступность доставки (максимум 7, по умолчанию 1, то есть только запрашиваемая дата)
  "lat": 12.32423434, # широта места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
  "lon": 12.32423434, # долгота места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
  "address": "г. Пушкин", # адрес места доставки, обязательно, если не указаны координаты
  "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 при создании заявки

Запрос

GET delivery_requests/time_intervals

{
  "date": "2021-02-01", # дата начала проверки интервалов, необязательно, по умолчанию дата выполнения запроса
  "check_days": 4, # количество дней вместе с датой проверки, до куда будет проверяться доступность доставки (максимум 7, по умолчанию 1, то есть только запрашиваемая дата)
  "lat": 12.32423434, # широта места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
  "lon": 12.32423434, # долгота места доставки, обязательно, если не указан адрес (имеет приоритет над адресом)
  "address": "г. Пушкин", # адрес места доставки, обязательно, если не указаны координаты
  "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 Проверяется формат 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 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_photo canceled canceled Клиент отказывается от фотографирования

Ошибки

HTTP коды

Http Code Значение
200 Успешный запрос
401 Ошибка аутентификации, неверный или истёкший токен
403 Ошибка авторизации, ресурс недоступен пользователю
404 Ресурс не найден
405 Состояние ресурса не позволяет выполнить запрос
422 Ошибка в параметрах запроса, невозможно исполнить запрос
500 Внутренняя ошибка сервера

Ответ с ошибкой

{
  "error": "Пояснение о причинах возникновения ошибки"
}

При ответе коде ответа отличного от 200 в теле ответа будет более подробная информация об ошибке