API без магии: как приложение узнаёт, где курьер

Вы заказали пиццу. Через минуту приложение пишет: «Ресторан готовит заказ». Потом появляется курьер на карте, а таймер обещает доставку через 14 минут. Выглядит так, будто приложение знает вообще всё. Но ресторан, курьер, карта и уведомления обычно живут в разных системах. Им надо как-то обмениваться данными — для этого и существует API.

API — это способ, которым программы разговаривают друг с другом по понятным правилам. Одна программа спрашивает: «Какой статус у заказа?» Другая отвечает: «Курьер назначен» или «Заказ доставлен». В словаре MDN API называют интерфейсом для взаимодействия программ — формулировка техническая, но суть именно в этом.

Представьте окно выдачи в кафе. Вы не заходите на кухню, не ищете сыр и не объясняете повару, как включать печь. Вы называете заказ, а в ответ получаете пакет или статус «ещё готовится». API — такое же окно выдачи, только для сервисов.

Один заказ — несколько систем

В 19:00 вы заказали роллы через приложение ресторана: выбрали блюда, указали адрес, оплатили. Для вас это одна кнопка. Внутри может начаться небольшая цифровая эстафета.

Приложение передаёт заказ в систему ресторана. Та подтверждает, что заказ принят, и может отправить его в платформу доставки. Платформа назначает курьера, а его рабочее приложение получает задание: куда ехать, что забрать и кому отвезти. Когда что-то меняется, информация возвращается к ресторану — и вы видите новый экран.

СкопироватьВы нажали «Заказать»
        ↓
Приложение ресторана → система ресторана → платформа доставки
                                              ↓
                                     приложение курьера
                                              ↓
Платформа доставки → статус заказа → система ресторана
                                              ↓
                         Приложение показывает статус и трекинг

Это частый, но не обязательный путь. Маленькая кофейня может назначать курьера вручную. У крупной сети бывает своя логистика. Где-то карту вообще не покажут. Главное другое: адрес, состав заказа и его состояние переходят между системами без ручного переписывания.

Без API менеджер копировал бы адрес в другой кабинет, звонил курьеру и потом вручную менял статус. А вы писали бы в поддержку: «Ну что там?» Каждые семь минут. Вери-вери неудобно.

Что именно видит клиент

Экран доставки кажется одной фичей, но внутри там разные данные.

Статус заказа отвечает на вопрос «что происходит?»: принят, готовится, курьер назначен, в пути, доставлен. Сервис доставки может передать технический статус, а приложение ресторана переведёт его на человеческий язык. Вместо `courier_assigned` вы увидите «Курьер уже едет за заказом».

Трекинг — это экран или ссылка, где можно следить за доставкой. Он может появиться сразу после создания заказа, ещё до того, как курьер взял пакет.

Координаты курьера — отдельные данные о местоположении. Рабочее приложение курьера отправляет их в платформу доставки, а она решает, передавать ли их дальше клиентскому приложению.

Время прибытия — прогноз, а не обещание на крови. На него могут влиять маршрут, пробки, готовность еды, назначение курьера и другие правила конкретного сервиса. Если «12 минут» стали «18», API не обязательно сломался: город просто добавил квест.

Почему webhook не спрашивает одно и то же сто раз

Приложение ресторана может регулярно спрашивать доставку: «Курьер назначен? А сейчас? А теперь?» Такой подход существует, но создаёт лишние запросы.

Webhook работает наоборот: случилось событие — сервис сам отправил уведомление другой системе. Курьер забрал пакет с суши, платформа доставки сообщает об этом ресторану, система обновляет заказ, а вы получаете пуш «Курьер выехал».

Это похоже на звонок в дверь. Вам не нужно каждые пять минут выходить в подъезд и проверять, не принесли ли посылку. Событие произошло — о нём сообщили.

Конкретный набор событий зависит от сервиса. Один передаст только статусы «в пути» и «доставлен». Другой может отдельно прислать ссылку на трекинг или обновление координат. Поэтому вопрос «У вас есть API?» сам по себе слабый. Нужнее спросить: «Какие статусы, сроки и данные получит наш клиент?»

Почему точка на карте прыгает и замирает

Карта обычно показывает не курьера в эту миллисекунду, а последнее местоположение, которое сервис успел получить и обработать. Координаты обновляются с интервалом, а геолокация иногда ошибается.

Поэтому сервис может сглаживать движение точки, чтобы она не телепортировалась через соседние дома. Для клиента это полезнее, чем честный хаос из прыжков туда-сюда. Но превращать карту в секундомер не стоит.

Трекинг нужен для простых выводов: курьер ещё далеко, уже въехал в район или, похоже, ищет ваш подъезд. Если вы стоите в коридоре в тапках и считаете метры до домофона, технология тут уже ни при чём )

Где API встречается кроме доставки

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

Через API сайт может отправлять заявку в CRM, сервис бронирования — проверять свободные даты, а банковское приложение — получать курсы валют. API не делает продукт хорошим автоматически. Можно собрать десять интеграций и оставить клиента со статусом «Обрабатывается» на три дня. Технология передаёт данные, но нормальный процесс не заменяет.

Что спросить перед подключением доставки

Если вы запускаете магазин или приложение, не покупайте «интеграцию под ключ» вслепую. Попросите подрядчика показать полный путь одного заказа: от оплаты до сообщения «Курьер у подъезда».

Уточните, какие статусы вернутся, будет ли трекинг для покупателя, как обновляется прогноз времени и что случится при временной недоступности сервиса доставки. Если статусы приходят автоматически через webhook, спросите, как система обработает повторное уведомление: оно не должно создать два одинаковых пуша.

Проверьте, какие данные уходят партнёру. Для доставки обычно нужны адрес и контакты получателя, но отправлять лишнее не стоит. Ключ API нельзя оставлять в публичном коде сайта или пересылать в обычном чате: это доступ к сервису, а не пароль от Wi‑Fi.

Когда речь заходит о персональных данных, условиях доставки и оплате, не полагайтесь на статью как на юридический совет. Правила и договоры меняются: перед запуском сверьтесь с первоисточником и специалистом.

API связывает сервисы, а не машет волшебной палочкой

API — это обычный разговор между программами. Ресторан передаёт заказ доставке, доставка возвращает статус, приложение показывает вам понятную карточку и карту.

Сегодня откройте трекинг любого активного заказа и найдите четыре вещи: статус, карту, прогноз времени и уведомления. После этого API перестанет быть страшной аббревиатурой — вы увидите его прямо на экране.