API SHIP как создать коннектор для отправки заказов в Shippo

Задача

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

Готового модуля именно под нужного перевозчика в Shopify App Store не было. Нанимать разработчика под одну интеграцию с чужим API невыгодно: типовая ручная разработка такого коннектора занимает 2–5 дней, а дальше требует поддержки при каждом изменении API перевозчика.

Ключевое требование обойтись без бэкенд-разработки и без риска, что интеграция молча сломается при следующем обновлении API курьера.

Как работает интеграция

API SHIP закрывает эту задачу без единой строчки кода со стороны магазина. Вместо технического задания и недель разработки платформа сама читает документацию API перевозчика и строит рабочий коннектор.

Структурированный ввод API

Есть три способа передать API Shippo в систему:

• вставить curl-команду из документации она разбирается парсером curlconverter, а ключи и токены автоматически вырезаются из запроса до того, как что-либо попадёт в ИИ;
• заполнить форму вручную: базовый URL, заголовок авторизации, пример запроса и ответа;
• вставить ссылку на страницу документации или сырой текст если это JS-рендерящаяся страница, она предварительно загружается через Jina AI Reader с оценкой качества извлечённого текста.

ИИ-генерация коннектора

Google Gemini 2.5 Flash получает разобранную спецификацию и строгую JSON-схему ответа и генерирует цепочку запросов, сопоставление входящих и исходящих полей и условную логику. Результат сразу проходит 6 детерминированных проверок: совпадение домена эндпоинта с базовым URL, наличие сопоставления для каждой переменной вида {{var}}, отсутствие «точечных» путей в переменных, наличие заголовка авторизации во внешних шагах, отсутствие самоссылающихся переменных и то, что учётные данные не попали в сопоставление полей. Если проверки находят ошибки, уверенность коннектора снижается, и такой черновик уходит на ручную проверку, а не сразу в прод.

Визуальный мастер

Дальше менеджер магазина открывает визуальный мастер на Shopify Polaris: сопоставляет поля адреса и веса заказа с форматом Shippo, при необходимости перетаскивает шаги местами, смотрит Raw Payload Preview как именно будет выглядеть реальный запрос и добавляет ключ API перевозчика на отдельном зашифрованном шаге.

Что реализовали

Виджет в карточке заказа

Через Admin Block Extension коннектор появился прямо на странице заказа в Shopify Admin:

• список доступных коннекторов доставки для этого заказа;
• двухшаговый флоу «Получить тарифы» → выбор тарифа → «Создать отправление»;
• статус выполнения обновляется в реальном времени;
• после успеха трек-номер и ссылка на PDF-этикетку сохраняются в заказе и остаются на месте после перезагрузки страницы;
• если данные заказа не подгрузились за 3 секунды, виджет откатывается на ручную форму адреса, чтобы менеджер не оставался заблокированным.

Автоматическая отправка при оплате

Отдельно включили режим auto-ship: по вебхуку orders/paid отправление создаётся автоматически с параметрами упаковки по умолчанию, без участия менеджера. Это закрыло типовые заказы одного веса и габарита, оставив ручной флоу только для нестандартных посылок.

Обработка ошибок и мониторинг

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

Технические особенности

Асинхронное выполнение

Тяжёлые операции — вызов ИИ, обработка вебхуков, выполнение коннектора, cron-задачи уходят в очереди Redis + BullMQ, а не выполняются в потоке запроса. Это не даёт генерации коннектора или созданию отправления замедлить сайт или витрину магазина.

Безопасность

Учётные данные Shippo хранятся зашифрованными AES-256-CBC, ключ шифрования выводится через scrypt KDF с уникальной солью на каждую запись это исключает атаку по радужным таблицам. Персональные данные маскируются по паттерну email/телефон/токен/ключ перед логированием и перед отправкой в ИИ. Все внешние HTTP-шаги коннектора выполняются с ручной обработкой редиректов и блокировкой редиректов на приватные IP-адреса защита от SSRF при обращении к произвольному API перевозчика.

Защита от дублей вебхуков

Shopify может присылать один и тот же вебхук повторно. Каждый входящий вебхук дедуплицируется по заголовку X-Shopify-Webhook-Id это исключает повторное создание отправления и задвоенные накладные при ретраях.

Ограничения, которые мы учли

Как и любая интеграция с внешним API, коннектор ограничен возможностями самого перевозчика и лимитами Shopify. Запросы к Shopify Admin API идут с учётом Leaky Bucket в среднем 2 запроса в секунду, до 40 в момент всплеска. Если API Shippo меняется переименовано поле, изменился эндпоинт, выполнение помечается как FAILED, а система самовосстановления предлагает готовое исправление, но применяет его человек: автоматического принятия правок нет.

Результат

Вместо нескольких дней разработки под конкретного перевозчика магазин получил рабочий коннектор за один день: документация API → черновик коннектора от ИИ → проверка и донастройка полей в визуальном мастере → тестовая отправка. Дальше создание накладной свелось к двум кликам в карточке заказа, а часть заказов уходит в отправку автоматически по факту оплаты.

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