«Нужно связать учётную систему со складом» — начало разговора. Чтобы оценить работу и принять результат, опишите одну операцию: кто её запускает, какие данные передаются, что должно измениться и как проверить исключение. Тогда исполнитель оценивает конкретный обмен, а заказчик понимает, за какой результат отвечает каждая сторона.
Этот материал помогает подготовить такой бриф. Здесь нет обещания готового коннектора: доступные методы, версия, настройки и права проверяются для выбранных систем и кабинетов. Все названия ERP-A, WMS-B и идентификаторы в примере вымышлены.
Рабочие файлы: пустой бриф интеграции и заполненный учебный пример. Их можно открыть в текстовом редакторе, скопировать в документ и дополнить вместе с техническим исполнителем. В примере заполнены требования; выполненные испытания не изображены.
Начните с результата сотрудника
Возьмите реальную повторяющуюся операцию и опишите её без названия будущей функции. Например: «Менеджер переносит подтверждённый заказ из учётной системы в задание на подбор. Нужно получить один черновик с правильными владельцем, складом и составом, который менеджер проверит по внешнему номеру».
В этой формулировке уже есть исполнитель, источник, выход и способ сверки. Сразу обозначьте, чего событие делать не должно. В учебном примере создание черновика не резервирует товар, не списывает остаток, не выпускает документы и не отправляет сообщения клиенту. Эти действия — отдельный объём, если они нужны бизнесу.
Таблицу можно прокрутить по горизонтали.
| В брифе | Пример полезного ответа |
|---|---|
| Что происходит сейчас | Менеджер повторно вводит состав подтверждённого заказа |
| Что запускает обмен | Заказ перешёл в согласованное состояние «готов к передаче» |
| Что получается | Один черновик задания для заданного клиента и склада |
| Как человек проверяет результат | Сравнивает внешний номер, вариант товара, единицу и количество |
| Что остаётся ручным | Допуск задания в работу и разбор изменений после начала подбора |
Если задача возникает редко, согласованный файл и понятная проверка могут быть достаточным решением. Если ошибки вызваны разными названиями товара или отсутствием ответственного, сначала уточните справочник и процесс. Автоматизация повторит неоднозначность быстрее, но не разрешит её сама.
Отделите существующую возможность от будущей работы
Для каждой части обмена назначьте один из четырёх статусов. Не ставьте общий «интеграция есть» на основании одной успешной выгрузки.
Таблицу можно прокрутить по горизонтали.
| Статус | Что должно быть известно |
|---|---|
| Работает и проверено | Конкретная операция, версии систем, кабинет, условия и сохранённый результат испытания |
| Нужна настройка | Подтверждённый штатный механизм и перечень настроек, после которых ещё предстоит приёмка |
| Нужна разработка | Проверенные технические возможности сторон, согласованный объём и критерии результата |
| Неизвестно | Какого доказательства не хватает, кто и каким действием его получит |
Наличие API означает, что у системы описан способ программного взаимодействия. Из этого не следует, что уже настроены нужные поля, повторы, права и восстановление. OpenAPI, например, описывает операции, схемы и ответы HTTP API; сам документ не является протоколом приёмки конкретного обмена. OpenAPI 3.1.1.
Для доработки внутри одной WMS логика та же: укажите экран, действие, роль сотрудника, исходный объект и ожидаемое изменение. Если новая кнопка создаёт счёт или меняет остаток, включите эти последствия в приёмку.
Назначьте источник истины для каждого объекта
«Главная система» слишком широкая формулировка. Учётная система может управлять заказом, а WMS — физическим выполнением. После начала подбора изменение количества в источнике не должно молча переписать факт работы склада.
Зафиксируйте владельца товара, кабинет, физический склад и область уникальности идентификаторов. Один и тот же артикул у двух клиентов ещё не означает общий товар. Номер заказа без указания источника тоже может совпасть.
Таблицу можно прокрутить по горизонтали.
| Объект в учебном обмене | Кто управляет | Ограничение |
|---|---|---|
| Состав и ревизия заказа | ERP-A до начала работы | Изменение после начала подбора требует отдельного решения |
| Задание на подбор | WMS-B | Импорт создаёт черновик; выпуск в работу подтверждается отдельно |
| Физический остаток | Складской процесс WMS-B | Импорт заказа сам по себе его не меняет |
| Сопоставление товаров | Назначенный владелец справочника | Неизвестный вариант отправляется на разбор, а не подменяется похожим |
Проверьте, не пишет ли в ту же область ещё один обмен. Если два источника меняют одно поле, определите правило конфликта до включения. Для разового переноса подготовьте отдельный срез и сверку: постоянная синхронизация и миграция решают разные задачи.
Опишите событие и словарь полей
Минимальный контракт связывает событие с бизнес-объектом и объясняет смысл каждого поля. В учебном примере внешний заказ — DEMO-001042, событие — EVT-017, ревизия заказа — 3, клиент — TEST-A, склад — TEST-WH-1.
Ключ заказа составлен из источника, клиента и внешнего номера. Ключ доставки — из источника, клиента и идентификатора события. Это проект правил примера, а не универсальные названия полей API. У исполнителя нужно проверить, существуют ли такие идентификаторы у реального источника.
Таблицу можно прокрутить по горизонтали.
| Поле | Что уточнить до разработки |
|---|---|
| Артикул и вариант | Как отличить цвет/размер и кому принадлежит товар |
| Количество | Штуки, комплекты или короба; допустимые значения и округление |
| Внешний номер | Строка или число; нужно ли сохранять ведущие нули |
| Ревизия | Кто увеличивает её и можно ли сравнивать две версии одного объекта |
| Время | Время события и получения отдельно; часовой пояс каждого значения |
| Статус | Что именно произошло и какие действия теперь разрешены |
| Ошибка | Какой объект не обработан, кто исправляет и где виден результат |
Укажите поведение для пустого и неизвестного значения. «Подставить ноль» может означать удаление остатка; «выбрать первый найденный SKU» — товар другого владельца. Если значение нельзя интерпретировать однозначно, в брифе должно быть состояние разбора и ответственный.
Разберите повтор, тайм-аут и позднее событие
Потерянный ответ не доказывает, что запись не состоялась. Сервер мог сохранить объект, а клиент — не получить подтверждение. В таком случае безусловный повтор способен создать второй документ или повторно изменить количество. RFC 9110 ограничивает автоматический повтор неидемпотентных запросов; Microsoft отдельно разбирает ситуацию успешного выполнения с потерянным ответом. Здесь «идемпотентность» означает, что согласованный повтор не создаёт дополнительного бизнес-эффекта. RFC 9110, §9.2.2, Microsoft: Retry pattern.
Для заказчика важны вопросы: как найти результат по прежнему ключу, какие повторы безопасны, сколько времени хранится защита от дублей и кто разбирает неопределённость. Надпись «есть повтор запросов» этих ответов не заменяет.
Таблицу можно прокрутить по горизонтали.
| Ситуация | Требование учебного примера |
|---|---|
| То же событие, те же данные | Вернуть прежний результат; второй черновик не создавать |
| Тот же ID, другое количество | Показать конфликт; не переписывать принятое событие |
| Новый ID, тот же заказ и ревизия | Сравнить значимые поля: одинаковые — повтор, изменённые — конфликт |
| Ревизия 2 пришла после 3 | Не откатывать состав; сохранить причину пропуска |
| Ответ потерян | Сначала найти результат по ключу; не менять ID для обхода проверки |
| Часть пакета принята | Сверить каждый результат; успешные строки не выполнять повторно |
Различайте два способа восстановления отклонённого события. Обычная повторная доставка возвращает сохранённый статус. Если исправлено внешнее сопоставление, а содержимое прежнее, ответственный запускает отдельную повторную обработку незавершённой записи с тем же ключом и защитой от параллельного исполнения. Если изменено само содержимое, создаётся новое событие с новой ревизией, а первоначальная запись сохраняется. Это правило нужно закрепить в контракте реального обмена и проверить восстановлением отклонённой строки без повторного выполнения принятой.
В документации Stripe есть конкретный пример поставщика, который предупреждает о повторных доставках и отсутствии гарантии порядка событий. Это не правило всех API и не заявление о коннекторе Stripe в Skirbo. Для своей системы проверьте её собственный контракт. Stripe: webhooks.
Ошибки доступа, неизвестный товар и временная недоступность требуют разных действий. Предел попыток, задержки, допустимую нагрузку и обработку Retry-After согласуют по документации выбранного API. Если источник не даёт сравнимой ревизии, нельзя молча заменить её временем на компьютере: способ получения актуального состояния нужно определить отдельно.
Превратите приёмку в наблюдаемые проверки
Записывайте ожидаемый результат до испытания. Рядом оставляйте место для факта, ссылки на доказательство и вывода. Если тест не выполнялся, так и пишите. Учебный файл содержит заполненные ожидания и статус «не проверено»; это помогает не выдать план испытаний за результат.
Минимальная приёмка обмена из примера проверяет:
- Обычное событие создаёт один черновик с тремя единицами правильного варианта, владельцем и складом. Остаток не изменён.
- Повтор того же события оставляет один черновик и три единицы.
- Конфликт содержимого сохраняет исходный результат и даёт понятную ошибку.
- После потери ответа можно найти сохранённый результат без второго задания.
- Запрос из другой области клиента не читает и не меняет чужой объект.
- Поздняя старая ревизия не возвращает устаревший состав.
- Частичный пакет даёт проверяемый результат каждой строки согласно согласованному контракту.
- После остановки и восстановления очередь сводится без пропущенных и повторно выполненных действий.
- Новая ревизия обновляет тот же черновик до начала подбора, а отмена сохраняет его историю. Остаток при этом не меняется.
- После начала подбора изменение или отмена создаёт понятное исключение для ответственного и не стирает выполненную работу.
Сверка нужна на стороне получателя: номер объекта, состав, состояние и журнал. Ответ API о приёме может подтверждать только постановку в очередь. Завершение операции, рабочий выпуск и приёмка сотрудником — отдельные факты.
Согласуйте остановку и следующий шаг
Назначьте трёх ответственных: владельца процесса, технического исполнителя и принимающего результат. Укажите допустимую тестовую среду, обезличенные примеры, условия ограниченного запуска и то, что останется ручным. Стоимость, сроки и условия сопровождения обсуждаются после уточнения объёма; шаблон их не обещает.
Остановка обмена запрещает новые действия, но не отменяет уже созданные задания, резервы и документы. Составьте реестр открытых объектов и порядок сверки. Если действие физически выполнено или документ уже ушёл другой стороне, возврат версии программы сам по себе его не отменит.
Бриф готов к оценке, когда исполнитель понимает обычный путь, границы данных и поведение при сбое, а принимающий может проверить результат. После оценки доработка проходит свою приёмку; ограниченную работу сотрудников помогает организовать паспорт пилота WMS. Для неисправности в уже работающей операции используйте шаблон обращения в поддержку.
Следующий шаг: заполните задачу, источники, один обезличенный пример и ожидаемый результат в брифе. Откройте поддержку Skirbo в Telegram, чтобы передать описание и уточнить текущий статус сценария. Открытие чата не отправляет бриф автоматически. Пароли, токены и полные клиентские выгрузки в описание не вставляйте.
Источники и границы
Первичные документы проверены 31 октября 2026 года: OpenAPI Specification 3.1.1, редакция 24.10.2024, RFC 9110, июнь 2022, Microsoft Azure Architecture Center: Retry pattern, Stripe: порядок и повторная доставка событий. Они обосновывают правила описания обмена и исключений. Статусы реальной интеграции, настройки и права подтверждаются отдельной проверкой выбранной версии и кабинета. Материал представляет общую методику, а пример — проект требований.