# Обмен BoatApp v1

Универсальный контракт; обработка внутри конкретной конфигурации 1С пока не создана.

HTTPS, JSON UTF-8. Базовый путь `/api/integration/v1`. Заголовки: `Authorization: Bearer <ключ>` и `X-BoatApp-Client: 1`. Администратор создаёт ключ для источника (`onec`, например), выбирает чтение или чтение/запись. Секрет показывается один раз; в 1С хранить в защищённом хранилище, не в коде. Ключ можно отозвать.

`GET /export?entity=ships|equipment|inspections&after_id=0&limit=200` — постраничная выгрузка ID, version, external_id и данных. Инспекции включают снимки результатов. `next_after_id` задаёт следующую страницу; null означает конец. Это полный обмен, не журнал удалений. Удаление и импорт инспекций в v1 не поддерживаются.

`POST /preview` — проверить пакет без изменения реестра:

```json
{"request_id":"уникальный-ID-пакета","ships":[{"external_id":"UUID-судна-1С","name":"Пример судна"}],"equipment":[{"external_id":"UUID-имущества-1С","ship_external_id":"UUID-судна-1С","name":"Огнетушитель","category":"Противопожарное имущество","unit":"шт.","required_qty":2,"actual_qty":2,"expiry_date":"2027-12-31"}]}
```

`POST /commit/{batch_id}` — применить проверенный пакет одной транзакцией. Предварительный просмотр действует 30 минут. Повторное подтверждение возвращает прежний результат; повтор request_id с другим содержимым отклоняется. При обрыве соединения повторять тот же запрос с тем же request_id. Для 429/5xx — повтор с задержкой; 401/403 — проверить доступ; 409 — обновить экспорт и сформировать новый пакет; 422 — исправить данные. Таймаут клиента: 30 секунд. Ошибки содержат `detail`.

Внешний ID стабилен в пределах источника и типа объекта. В 1С использовать UUID ссылки. Для явного связывания с существующей записью передавать `boatapp_id`. Имена не используются для автоматического связывания. Обновление требует актуальной `version` из экспорта. Изменение между просмотром и подтверждением отменяет весь пакет с 409.

Импорт — полная карточка, не PATCH: пропущенные необязательные поля получают значения по умолчанию, null очищает дату. Количества — неотрицательные целые; даты — YYYY-MM-DD. Интервал 0 означает отсутствие освидетельствования. Не более 1000 строк. Отсутствие строки в пакете не удаляет её из базы.

## Excel

Администрирование → Обмен и Excel → скачать шаблон → заполнить → проверить → подтвердить. Листы «Суда» и «Имущество». .xlsx до 5 МБ; .xls предварительно пересохранить. Формулы не исполняются и не принимаются: вставлять значения. Даты — Excel, YYYY-MM-DD или ДД.ММ.ГГГГ.

Код судна на листе имущества должен соответствовать коду на листе судов или уже сохранённой связи выбранного источника. При повторной загрузке сохранять коды и источник. Неизменившиеся строки пропускаются; для изменений указывать текущую версию. Ошибки блокируют весь файл. Для существующих записей использовать ID BoatApp, чтобы явно связать их с внешними кодами.

Машинные ключи не открывают веб-админку. Действия записываются в журнал. Сопоставление справочников и регламентное задание в 1С добавляются после выбора конфигурации.