# Подключение 1С к Нейре

Подключение настраивает специалист, обслуживающий вашу конфигурацию 1С. Это контракт HTTP-сервиса, а не универсальная обработка для любой базы. Перед включением проверьте обмен на копии базы. Поддерживаются задачи и товары с остатками; денежные счета, проводки, файлы и удаления не переносятся.

Опубликуйте сервис по публичному HTTPS-адресу, например `https://example.ru/hs/neyra/`. Закройте его отдельным Bearer-токеном (от 16 символов) с доступом только к выбранной области. Все три метода ниже принимают POST и JSON UTF-8, возвращают JSON. Перенаправления не поддерживаются. Максимум 500 записей в области и 2 МБ в ответе.

## capabilities

Запрос: `{}`.

Ответ: `{"protocol":"neyra/1","entities":["tasks","assets"],"idempotency":true,"optimisticConcurrency":true}`.

Объявляйте только реализованные сущности. Эти возможности должны быть реализованы, а не просто перечислены в ответе.

## list

Запрос: `{"entity":"assets","cursor":null,"limit":100}`.

Ответ: `{"items":[{"id":"устойчивый-идентификатор","version":"1","data":{"name":"Кабель","description":"","unit":"м","quantity":10}}],"nextCursor":null}`.

При продолжении передавайте непрозрачный nextCursor. Сортировка должна быть устойчивой, без повторов и пропусков; курсор желательно привязывать к снимку. ID — неизменный строковый идентификатор объекта, version — строковая ревизия, меняющаяся при любом изменении передаваемых полей. Возвращайте originId для объектов, созданных через upsert. Не используйте имя как ID.

Задачи: `{"title":"Проверить поставку","description":"","status":"todo","priority":"normal","due_date":null}`. Статусы: todo, in_progress, review, done, blocked. Приоритеты: low, normal, high, critical. Срок — ISO 8601 с часовым поясом или null. Остаток — итоговое неотрицательное количество с точностью до 6 знаков, не движение. Все строки возвращаются полностью.

## upsert

Запрос: `{"entity":"assets","id":null,"originId":"neyra:connection-uuid:local-uuid","expectedVersion":null,"idempotencyKey":"operation-uuid","data":{"name":"Кабель","description":"","unit":"м","quantity":10}}`.

Ответ: `{"item":{"id":"устойчивый-идентификатор","version":"2","originId":"neyra:connection-uuid:local-uuid","data":{"name":"Кабель","description":"","unit":"м","quantity":10}}}`.

В одной транзакции 1С:
1. Заблокируйте ключ idempotencyKey. Если он уже обработан, верните сохранённый ответ без повторной записи. Храните ключи не меньше срока жизни подключения. Повтор с другим телом отвергайте.
2. При id=null найдите запись по originId либо создайте одну. Обеспечьте уникальность originId. При заданном id запись должна существовать; не восстанавливайте удалённые записи.
3. Для обновления атомарно сравните expectedVersion с текущей ревизией под блокировкой. При несовпадении верните HTTP 409 без изменений.
4. Проверьте обязательные поля и права. Для остатков запишите только разницу через штатный документ/регистр вашей конфигурации; не переписывайте бухгалтерские регистры напрямую.
5. Сохраните результат, новую ревизию, originId и ответ по idempotencyKey вместе. Верните фактические значения после записи.

HTTP 401/403 — нет доступа, 409 — конфликт ревизии, 429 — лимит, 5xx — временный сбой. Не возвращайте пароли и внутренние данные в ошибках.

## Включение и проверка

В Нейре: профиль → Обмен → Автоматический обмен → Добавить подключение. Укажите адрес, токен, название базы, сущность и направление. Проверьте доступ и сохраните на паузе. Первое включение охватывает все активные записи выбранного типа команды; одинаковые названия сами не объединяются. Сначала используйте отдельную тестовую команду и базу.

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