Документация API-интеграции сайта: паспорт интеграции и порядок работы

Документация API-интеграции — это описание конкретной связки: список полей, форматов, правил обработки ошибок и ответственных. Она позволяет новому разработчику или подрядчику быстро понять, как соединены системы и какие данные передаются. Она не заменяет справочник платформы: справочник описывает все возможности системы, а документация интеграции — только те методы и поля, которые используются в вашей конкретной связке. Ниже — состав такого документа, порядок работы с версиями, учебный пример, таблица выбора формата и чек-лист приёмки.

Зачем бизнесу документация API-интеграции и где её границы

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

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

Границы стоит обозначить сразу:

• паспорт описывает одну конкретную связку, а не все интеграции компании;
• он ссылается на официальную документацию платформы, а не копирует её;
• он фиксирует договорённости между сторонами, а не заменяет техническое задание на разработку;
• он не является юридическим документом о персональных данных — это отдельная зона, которую проверяет профильный специалист.

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

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

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

Паспорт интеграции: состав и обязательные разделы

Паспорт интеграции — основной практический артефакт этой темы. Это документ, который заполняется по ходу работ и обновляется при изменениях. Разумный минимум:

• назначение связки и бизнес-задача, которую она закрывает;
• перечень систем-участников и направление обмена;
• способ обмена и точка входа: кто инициирует, по какому адресу, с какой периодичностью;
• описание полей: обязательные, необязательные, форматы, допустимые значения;
• правила обработки ошибок и повторов;
• ответственные с обеих сторон и порядок эскалации;
• версия контракта и история изменений;
• способ проверки: как убедиться, что обмен прошёл корректно.

Эти восемь пунктов — не догма, а каркас. В конкретной связке к ним добавляют то, что важно именно здесь: например, правила округления сумм, порядок работы с изображениями, ограничения по объёму одной передачи. Но убирать пункты из каркаса не стоит: каждый из них закрывает свой класс вопросов, которые рано или поздно возникнут.

Что в паспорт не входит

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

Отдельно стоит убрать из паспорта маркетинговые формулировки. Документ читают не для того, чтобы вдохновиться, а для того, чтобы понять, как устроен обмен. Фразы вроде «гибкая и надёжная интеграция» не несут информации и только увеличивают объём.

Как поддерживать актуальность

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

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

Описание полей и действующий контракт

Самая полезная часть паспорта — таблица полей. Для каждого поля фиксируют имя, тип, обязательность, формат, источник, назначение и поведение при отсутствии значения (например, передавать null, пустую строку или игнорировать). Отдельно описывают, что считается идентификатором записи и как сопоставляются объекты в двух системах.

Контракт — это договорённость о том, что именно считается корректным обменом. Он включает структуру запроса и ответа, смысл ответов об успехе и ошибке, правила частичной передачи и ограничения по объёму и частоте.

Для понимания контекста можно изучить API-интеграция сайта на Битрикс с внешними системами (общие принципы) и Интеграция магазина с платёжными системами: онлайн-оплата и касса (специфика статусов).

Обязательные и необязательные поля

Разделение на обязательные и необязательные поля — не формальность. Если поле помечено обязательным, приёмная сторона вправе отклонить запрос без него. Если необязательным — должна корректно обработать его отсутствие. Это правило стоит проговорить в паспорте явно, иначе стороны будут трактовать его по-разному, и каждая будет считать, что права.

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

Форматы и допустимые значения

Формат поля — это не только тип данных, но и договорённость о деталях: как записывается дата, в какой валюте передаётся сумма, что означает пустое значение. Чем конкретнее описан формат, тем меньше споров при приёмке. Если значение может принимать ограниченный набор вариантов, эти варианты перечисляют в паспорте.

Особое внимание — денежным и количественным полям. Нужно заранее решить, передаётся ли сумма в минимальных единицах или в основной валюте, как округляется, что делать с отрицательными значениями. Эти детали кажутся мелкими, пока не появится расхождение на копейку, которое потом ищут неделю.

Идентификаторы и сопоставление

Отдельный источник ошибок — сопоставление записей. Нужно заранее решить, по какому признаку объект считается «тем же самым» в двух системах, что делать при дублях и как поступать, если идентификатор изменился. Ответ на эти вопросы фиксируется в паспорте, а не остаётся в переписке. Иначе при первом же расхождении начнётся выяснение, кто и что имел в виду.

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

Обработка ошибок и повторные попытки

Ошибки при обмене неизбежны, и паспорт должен описывать, что с ними делать. Полезно зафиксировать: какие ситуации считаются ошибкой, попадает ли проблемная запись в отдельный отчёт, повторяется ли попытка автоматически и сколько раз, что происходит с остальными записями, если одна не прошла. Молчаливая потеря данных — критический сценарий, поэтому правило «проблемная запись не теряется, а фиксируется в журнале ошибок» стоит внести в документ явно.

Хорошо, когда в паспорте указано, кто и как часто смотрит отчёт об ошибках. Документ без ответственного за разбор ошибок описывает проблему, но не решает её.

Ответственные, версии и порядок изменений

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

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

• у контракта есть номер версии;
• изменения, ломающие совместимость, выпускаются как новая версия;
• старая версия поддерживается, пока стороны не перейдут на новую;
• каждая версия описана в истории изменений с датой и причиной.

Порядок внесения изменений

Изменение проходит предсказуемый путь: описание в паспорте, согласование с обеими сторонами, проверка на тестовых данных, только потом — на рабочем контуре. Для любых правок действует общее правило: сначала копия и резерв, затем тест, и только потом изменение в рабочей среде с планом возврата. Это не бюрократия, а способ не потерять работающий обмен из-за одной необдуманной правки.

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

История изменений

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

Журнал ведут в том же документе, а не в отдельном файле, который легко потерять. Запись делают до внесения правки, а не после: так фиксируется намерение, а не его последствия.

Кто утверждает

Утверждать изменения должен владелец интеграции или назначенный им ответственный. Если изменение затрагивает данные, требующие юридической экспертизы (например, персональные данные), к согласованию подключают профильного специалиста.

Как читать официальную документацию платформы

Паспорт не заменяет справочник платформы, а опирается на него. Документация Bitrix Framework описывает структуру ядра: ядро D7 — современный стандарт, методы старого ядра помечены как устаревшие. При наличии предупреждений о deprecated-методах используйте аналоги из D7.

Полезные особенности справочника, которые стоит знать при чтении:

• документация носит справочный характер, а детальные принципы работы описаны в учебном курсе «Разработчик Bitrix Framework»;
• справочник может не охватывать все методы — иногда для понимания работы нужно смотреть сам код;
• в документации проставлены версии, с которых появилась сущность, а для устаревших — диапазон версий, когда она была действующей;
• отметка «устарел» у метода, параметра или ключа означает, что использовать его не рекомендуется, поскольку расширений и исправлений не будет;
• простановка версий выполнена не полностью, работы в этом направлении продолжаются.

Следить за изменениями можно через раздел «Что нового» в документации, подписку на канал отдела документации и блог разработчиков. Онлайн-версия справочника актуальнее скачанного файла: файлы обновляются периодически и могут не содержать последних изменений.

Если описания метода нет

Если метода нет в справочнике, изучите исходный код. Для демонстрации работы используйте модуль «Живое описание АПИ» из Маркетплейса (инструмент понимания, не замена документации). К адресу страницы справочника можно добавить якорь для быстрого перехода к примеру.

Что из справочника переносить в паспорт

В паспорт переносят только то, что относится к вашей связке: используемые методы, конкретные поля и ограничения. Полный перечень возможностей платформы в паспорт не копируют — он устареет и запутает читателя. Справочник остаётся источником, а паспорт — выжимкой под задачу.

Учебный пример: паспорт интеграции для обмена каталогом

Учебный пример. Данные условны, приведены для иллюстрации порядка работы, а не как реальный кейс.

Входные условия. Условная компания ведёт каталог товаров в учётной системе и хочет показывать актуальные цены и остатки на сайте. Обмен идёт в одну сторону: учётная система — источник, сайт — приёмник. Обновление запускается по расписанию. В каталоге несколько тысяч позиций, часть из которых периодически снимается с продажи.

Действия. Команда составляет паспорт интеграции:

1. Фиксирует назначение: показывать на сайте актуальные цену и наличие. 2. Описывает участников: учётная система и сайт, направление обмена — от учёта к сайту. 3. Задаёт точку входа и периодичность запуска. 4. Заполняет таблицу полей: идентификатор товара, наименование, цена, остаток, признак активности. Для каждого поля указывает обязательность и формат. 5. Определяет правило сопоставления: товар опознаётся по идентификатору из учётной системы. 6. Описывает поведение при ошибке: если запись не прошла, она попадает в список проблемных, остальные обрабатываются. 7. Назначает владельца интеграции и ответственных с обеих сторон.

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

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

Если источником данных выступает учётная система, полезно изучить обмен сайта на Битрикс с 1С — там описаны типовые сценарии и развилки обмена.

Как проверить результат и принять работу

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

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

Сравнение вариантов ведения документации

Формат документации выбирают под задачу. Ниже — сравнение типовых вариантов по критериям, которые важны при приёмке.

Выбор формата — не самоцель. Важно, чтобы документ был доступен тем, кому он нужен, и чтобы у него был владелец. Формат без владельца устаревает одинаково быстро в любом месте.

Типичные ошибки и ограничения

Ошибки в документации API-интеграции обычно одни и те же.

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

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

Ещё одно ограничение — человеческое. Документ работает, только если команда договорилась его читать и обновлять. Если паспорт существует формально, а решения принимаются в переписке, он быстро теряет смысл.

Какие исходные данные подготовить для оценки

Чтобы оценить объём работ по документации интеграции, нужны входные данные. Без них любая оценка будет гаданием.

• Перечень систем-участников и направление обмена.
• Бизнес-задача: что должно измениться в работе после запуска.
• Список полей, которые участвуют в обмене, с указанием обязательности.
• Правило сопоставления записей и известные исключения.
• Требования к периодичности и объёму обмена.
• Ответственные с обеих сторон и порядок эскалации.
• Сведения о текущем состоянии: есть ли уже работающая связка и её описание.
• Ограничения: юридические, организационные, технические.

Если часть данных неизвестна, это фиксируют как открытый вопрос, а не додумывают. Способ проверки неизвестного факта описывают отдельно: например, сверить поведение на тестовых данных или уточнить у владельца системы.