№31009| Новий формат адреси для доставки / Flexible Delivery

Пошуковий центр

Новий формат адреси для доставки або "Flexible Delivery"

Інструкція по налаштуванню і експлуатації

Під новим форматом адреси мається на увазі відхід від використання довідників вулиць в Syrve і початок використання сервісу Places від Google Cloud. Ця стаття описує те, як це налаштувати і як користуватись. Почнемо.

ВАЖЛИВО!

Якщо у клієнта є чейн - то все про що піде мова нижче, треба робити в Чейні!

Підготовка і налаштування

1.1) Замовити ліцензію

Address_CITY (Office) (21071702)

ВАЖЛИВО: ліцензії замовляються

в чейн (якщо він є), 1 шт
в кожен РМС по кількості робочих місць (фронтів) та / або по кількості операторів КЦ

Після замовлення та появи ліцензій - оновити список ліцензій і перезайти в програму

1.2) Пересвідчитися, що на фронті з'явився плагін "Resto.Front.Api.ExternalAddressService.V9Preview5"
Якщо його немає: можна взяти з ФТП Syrve або звідси: https://t.me/c/1176093380/165414

2) Встановити галку "Використовувати новий формат адреси"
Якщо ліцензії наявні, то і в РМС, і в чейні, з'явиться можливість проставити цю галку
Для чейну це робиться тут:

Для Standalone RMS (РМС не в складі чейну) це робиться тут:

3) Перейменувати місто за замовчуванням
Т.я. новий функціонал ніяк не відміняє старий, розробка зробила таким чином, що при роботі з новим функціоналом завжди підставляється вулиця за замовчуванням, тобто ---------, а вона належить по замовчуванню місту Москва, тож необхідно перейменувати його з міста країни 404 на якесь з основних міст клієнта

4) Змінити шаблон накладної доставки
Новий функціонал використовує зовсім інші елементи шаблону чеку, ніж стандартний, тому щоб в накладній не відображалось --------- і місто за замовчуванням, треба внести правки в шаблон. В подальшому ця зміна буде врахована в нашому стандартному шаблоні накладної доставки, а поки що клієнту робимо правки ручками
Шукаємо в нашому шаблоні ось такі рядки

І заміняємо їх на ось такі

if (!delivery.IsSelfService) 
{
    if (!string.IsNullOrWhiteSpace(address.Line1)) 
    {
        <f2><center>@address.Line1</center></f2>
    }
    else 
    {
        if (!string.IsNullOrWhiteSpace(address.Building)) 
        {
            <f2><center>@address.City</center></f2>
	    <f2><center>@string.Format("{0} {1}/{2}", address.Street, address.House, address.Building)</center></f2>
        }
        else 
        {
            <f2><center>@address.City</center></f2>
            <f2><center>@string.Format("{0}, {1}", address.Street, address.House)</center></f2>
        }
    }
}

Результат відпрацювання нижче на скріншотах.
Зліва - звичайний функціонал. З права - новий функціонал

5) Запустити фронт і оновити плагіни через Updater
На цьому кроці після того як фронт видасть повідомлення про те що плагіни успішно встановлені - перезапускаємо фронт і пересвідчуємось, що в папці Plugins з'явився плагін з назвою Resto.Front.Api.ExternalAddressService.V8

Створення проєкту та ключа API на платформі Google Cloud

1) Переходимо в кабінет Google Cloud та входимо під своїм обліковим записом Google (або спочатку створюємо новий обліковий запис, а потім заходимо в кабінет)

2) Створюємо новий проєкт

3) Називаємо проєкт і клікаємо Створити (організацію для проєкту вибирати не обов'язково)

Для того щоб все працювало, нам потрібно включити для проєкту 2 API. Для цього робимо наступне:

4) В боковому меню заходимо в APIs & Services -> Library

Нас цікавлять дві конкретні API в бібліотеці:
Places API (new) - для того щоб шукати адреси за їх неповним описом
Geocoding API - для того щоб шукати адреси по геолокації

5) В рядочку пошуку шукаємо їх назви та натискаємо кнопку Enable

І на останок, нам потрібно створити API ключ для проєкту

6) В боковому меню заходимо в APIs & Services -> Credentials

7) Натискаємо на кнопку + Create credentials і з запропонованих варіантів вибираємо API key

8) В завершення скопіюйте створений ключ для того щоб використати його в наступному блоці цієї статті (ключ з'явиться на екрані через пару секунд після виконання попереднього пункту)

Використання API ключа через Postman

Після того як у нас є робочий апі ключ, ми можемо виконати запит для пошуку місця згідно ключових слів, але для початку нам треба правильно виставити всі параметри. Нижче наведено список параметрів і скріншоти з Постмана, як це зробити

Варіант 1: Пошук по ключовим словам
Сам запит:
1) Тип запиту - POST
2) Ендпоінт - https://places.googleapis.com/v1/places:searchText

Вкладка Headers
1) Вказати в стовпчику Key: X-Goog-Api-Key і відповідно в стовпчику Value: той АПІ ключ, який ми створили в Google Cloud
2) Вказати в стовпчику Key: X-Goog-FieldMask і відповідно в стовпчику Value: варіант повернення інформації в запиті
Якщо вказати * - повернеться абсолютно все
Якщо вказати places.FormattedAddress - повернеться адреса в форматі: вулиця, дім, місто, країна, індекс
Якщо вказати places.shortFormattedAddress - повернеться адреса в форматі: вулиця, дім, місто (раджу задля успіху подальших налаштувань використовувати саме цей варіант)

На скріншоті показаний приклад, де додані всі 3 варіанти записів, але галкою відмічати треба тільки ОДИН З НИХ!

Вкладка Body
Запит, як і наші запити через АПІ Транспорт, передається в форматі JSON
В тілі запиту ми маємо передати всього 2 параметри
1) "languageCode": "uk" - для того щоб вся інформація поверталась українською
2) "textQuery": "текст пошуку" - власне, сюди вводити те що ми шукаємо

Вкладка Scripts
Цей крок необхідний для того, щоб автоматизувати створення замовлення через наш запит delivery/create
1) Створіть нову ГЛОБАЛЬНУ змінну і назвіть її як хочете (в прикладі - це line1)

2) Переключіться на Post-response (скрипти після отримання відповіді на запит) і вставте туди ось такий скрипт:

pm.globals.set("Змінна, яку ви створили. Лапки не прибирати", pm.response.json().places[0].shortFormattedAddress);

На виході, якщо робили через рекомендовані мною налаштування з статті, отримаємо ось такий респонс

На цьому етапі, те що ми отримали в респонсі, уже записалось в нашу нову змінну

Варіант 2: Зворотнє геокодування
Сам запит:
1) Тип запиту - GET
2) Ендпоінт - https://maps.googleapis.com/maps/api/geocode/json

Вкладка Params
Туди нам треба додати наступні поля і задати їм наступні значення:
latlng - сюди ввести широту і довготу, яку ми шукаємо, без пробілу після чи перед комою (приклад - 50.428379,30.5978736)
language - uk - щоб результат запиту повертався українською
result_type - street_address
location_type - ROOFTOP
key - наш ключ АПІ

Вкладка Scripts
Цей крок необхідний для того, щоб автоматизувати створення замовлення через наш запит delivery/create
Переключіться на Post-response (скрипти після отримання відповіді на запит) і вставте туди ось такий скрипт:

const addressComponents = pm.response.json().results[0].address_components;
let line1 = addressComponents.find(component => component.types.includes('route')).long_name;
line1 += ', ' + addressComponents.find(component => component.types.includes('street_number')).long_name;
line1 += ', ' + addressComponents.find(component => component.types.includes('locality')).long_name;

pm.globals.set("line1", line1);

На виході, коли ми отримаємо у відповідь гору тексту, постман сам розпарсить все що треба і запише в нашу змінну результат в нормальному форматі

Залишилось тільки виконати запит на створення доставки, тільки змінити в ньому пару рядків, а саме блок deliveryPoint

В звичайному запиті на створення доставки кур'єром, він виглядає приблизно ось так

        "deliveryPoint": {
            "address": {
                "street": {
                    "city": "Львів",
                    "id": "d4af4b11-c135-40c1-b6d6-99d8c1e332f9"
                },
                "house": "77"
            }
         },

При використанні нового функціоналу, нам треба передавати його ось так

        "deliveryPoint": {
            "address": {
                "line1":"{{Змінна, яку ви створили. Фігурні дужки не прибирати}}",
                "type":"city"
            }
        },

На цьому все, користуйтесь на здоров'я ;)

FAQ або питання, що часто задають