Найти заказы заказчика и получить их детали

Стенд по умолчанию — test. Только чтение. Порядок работы для агента.

Используйте сценарий, когда заказчик описывает условия поиска своими словами и хочет узнать текущее состояние заказов. Для запроса «что изменилось с последней проверки» откройте Получать изменения заказов заказчика.

Перед началомПеред началом

Нужен действующий токен API с доступом к нужным организациям с ролью заказчика. Храните токен, реальные запросы и ответы в локальном клиенте. Используйте карточки методов для проверки области доступа, фильтров, сортировки, лимитов, форматов и правил обработки данных.

Для поиска по одной организации проверьте активный профиль заказчика по сценарию Проверить доступ к API для заказчика. Для чтения заказов нужно отдельное право view_all_orders в этой организации.

Порядок вызововПорядок вызовов

Методы поиска и деталей возвращают JSON. Если клиент передал байты, разберите ответ перед чтением data.

1. Откройте POST /api/orders/v0/transferOrder/getOrderIdsForCustomer и сопоставьте условия пользователя с фильтрами, которые влияют на выдачу.
2. Если нужен поиск по адресу или месту, а проверенных координат нет, вызовите POST /api/geocoder/v2. При неоднозначном результате уточните адрес. Для любой точки погрузки заполните data.filter.loadPoint полями lat, long и radiusM. Скопируйте долготу из lon геокодера. Для первой точки маршрута используйте orderWayFirstLoadingWayPoint.
3. Вызовите метод поиска из первого шага. Для одной организации укажите её идентификатор в data.filter.forwarderIDs. Если ни одна переданная организация недоступна, поиск может сохранить исходную область токена. Если data.orderIds отсутствует или не является массивом, остановитесь и проверьте ответ. При data.orderIds: [] завершите поиск без запроса деталей. Пустой список не подтверждает права в выбранной организации.
4. Вызовите POST /api/orders/v0/transferOrder/getFlatForCustomer, только если выбрали хотя бы один нужный непустой идентификатор из data.orderIds. Уберите повторы и передайте выбранные идентификаторы в data.exactOrderIds. Для одной организации также укажите data.forwarderIDs. Проверьте data.orders[].forwarder.forwarderId каждой возвращённой карточки. Если поле отсутствует или значение отличается от выбранной организации, остановитесь и сообщите, что область результата не подтверждена.
5. Возвращайте только данные, необходимые для задачи. Например, для краткого результата достаточно статуса и количества подходящих заказов. Соблюдайте правила работы с замаскированными и чувствительными полями из карточки метода.

Если запрос не дал ожидаемого результатаЕсли запрос не дал ожидаемого результата

• Если API отклонил фильтр или он не влияет на выдачу, сверьте его с карточкой метода и исправьте запрос.
• При ошибке авторизации проверьте доступ к API. Сохраните исходную роль и область организаций.
• Если геокодер не нашёл подходящего адреса, уточните место у заказчика. Вывод о заказах можно сделать после поиска.
• Повторяйте запрос только после временных ошибок, указанных в карточке метода.