Cтруктурно, понятно и без технического жаргона

© Аналитик Вася

1. Определить контекст интеграции

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

• Зачем нужна интеграция? (Например: «Автоматизировать передачу заказов из CRM в 1С»).
• Кто участники? (Система A → Система B, включая владельцев. Обозначить - какая система в роли поставщика данных, какая - в роли потребителя.).
• Тип интеграции:
  • Real-time (REST API, вебхуки).
  • Асинхронная (FTP, очереди Kafka/RabbitMQ).
  • Ручная выгрузка (CSV/Excel).

2. Задокументировать ключевые параметры

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

3. Детализировать данные

Вариант 1: Таблица полей

Вариант 2: Пример payload (для API)

json:

 

// Запрос от CRM к 1С 

{

  "order_id": "12345-ABCDE",

  "status": "shipped",

  "items": [

    {"sku": "X-100", "qty": 2}

  ]

}

 

4. Описать сценарии обработки (Use Cases)

• Успешный сценарий:
  • CRM отправляет данные в 1С →
  • 1С возвращаетHTTP 200+ {"success": true, "request_id": "987"} →
  • CRM сохраняет request_id для отслеживания.
• Ошибки:
  • HTTP 400: Неверный формат данных → CRM логирует ошибку и уведомляет поддержку.
  • HTTP 504: Таймаут → CRM повторяет запрос 3 раза с интервалом 5 сек.

5. Добавить диаграммы (если нужно)

• Инфраструктура: Блок-схема с серверами, брандмауэрами, VPN.
• Диаграмма последовательности (UML Sequence Diagram):

6. Зафиксировать нефункциональные требования (NFR)

• Производительность: 1С должен обрабатывать запрос ≤ 500 мс.
• Безопасность: TLS 1.2+, аутентификация по OAuth 2.0.
• Логирование: Все ошибки сохранять в ELK (индекс integration_errors).

7. Чек-лист для проверки

• Все поля данных задокументированы (типы, обязательность).
• Описаны коды ошибок и реакция на них.
• Есть контакты ответственных за оба конца интеграции.
• Учтены edge cases (например, отмена заказа после синхронизации).

Шаблон для описания интеграционного взаимодействия в Confluence/Jira

 

markdown

 

## Интеграция: [Система A] → [Система B] 

 

### 1. Цель 

> [Зачем это нужно бизнесу?] 

 

### 2. Участники 

| Роль                  | Контакт            | 

|--------------------|-------------------| 

| Владелец System A  | Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в вашем браузере должен быть включен Javascript.  | 

 

### 3. Данные 

**Пример запроса:** 

```json

{ "key": "value" }

 

4. Сценарии

• Успех: [Описание].
• Ошибка: [Действия].

5. Требования к инфраструктуре

• Пропускная способность: ≥ 100 RPS.

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