Интеграция 1С: API v2

Архивная редакция v2. Для новых подключений и доработки обработки используйте полное руководство и ТЗ v3. v3 — редакция документа; версия API не меняется.

Версия 2.0 · обновлено 28 сентября 2026 года

Для лагерей, бухгалтеров и разработчиков обработки 1С. Изменения относительно первой версии описаны в отдельном файле Изменения в v2.

1. Что делает интеграция

• 1С получает с платформы «Наши лагеря» путёвки, оплаты и готовые PDF индивидуальных договоров.
• 1С автоматически отправляет на платформу PDF актов оказания услуг и УПД.
• Документы появляются в карточке заказа в панели лагеря, в разделе Акты и УПД. В ЛК родителя они не отображаются и в скачиваемый комплект не входят.
• Исправления передаются новой редакцией. Отзыв сохраняет историю, но отключает скачивание отозванного документа через платформу.

Все HTTP-соединения инициирует 1С. Платформа не подключается к базе 1С и не требует её публикации в интернете. Обработка 1С вызывает API по расписанию и повторяет неуспешные запросы. Обмен данными идёт в обе стороны в рамках этих исходящих запросов.

Обновление платформы предоставляет API и отображение документов. Для автоматической отправки разработчик лагеря должен обновить обработку/расширение 1С по этому руководству. Специфические имена объектов конфигурации и обработчики проведения реализуются в самой базе 1С.

2. Подключение и проверка

Базовый адрес production: https://api.ourcamps.ru/api/v1/public. Для тестов используйте адрес тестового окружения, полученный от поддержки. Наличие кода в ветке DEVEL не означает его публикацию на production.

Все запросы передают заголовок:

X-API-Key: YOUR_CAMP_API_KEY

Лагерь определяется по ключу. Передавать camp_id в accounting-маршрутах не требуется. Номер базы и идентификаторы документов не заменяют аутентификацию.

Попросите администратора включить для интеграционного ключа право Загрузка актов и УПД из 1С. Старые ключи продолжают читать данные, но не получают право записи автоматически. В системном администрировании это поле API-ключа allow_accounting_uploads.

Для автоматизированной настройки сотрудник с правом управления лагерем может создать ключ через существующий JWT API:

POST /api/panel/camps/{camp_id}/api-keys
Content-Type: application/json

{"name":"1С Бухгалтерия","allow_accounting_uploads":true}

Существующему ключу разрешение меняется через PATCH /api/panel/camps/{camp_id}/api-keys/{key_id} с {"allow_accounting_uploads":true}. Это служебная настройка с авторизацией сотрудника, а не запрос по ключу 1С. При перегенерации ключа документные связи сохраняются.

Проверка связи

GET /accounting/connection

Поля data:

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

3. Формат ответов и ошибок

JSON-ответы используют общий формат:

{
  "success": true,
  "data": [],
  "meta": {
    "trace_id": "request-trace-id",
    "pagination": {
      "count": 120,
      "page": 1,
      "pages": 2,
      "page_size": 100,
      "next": "https://api.ourcamps.ru/api/v1/public/accounting/vouchers?page=2&page_size=100",
      "previous": null
    }
  }
}

data может быть объектом или массивом. pagination присутствует только для списков. Ошибки возвращаются с success=false, массивом errors и meta.trace_id. Скачивание договора возвращает двоичный application/pdf, без JSON-обёртки. Успешное удаление пакета возвращает 204 без тела.

Лимит API: 100 запросов в минуту на ключ. Рекомендуемая частота обмена: раз в 5–15 минут; запускайте только один экземпляр задания на подключение.

В журнале 1С сохраняйте время, этап, HTTP-код, trace_id, ID объекта, версию и число созданных/обновлённых/повторных записей. Не записывайте ключи, PDF и паспортные данные в журнал. Ошибка не должна отображаться как успешный обмен с нулём записей.

4. Путёвки и готовые названия

GET /accounting/vouchers?updated_since=2026-09-01T00:00:00Z&page_size=100

Параметры: updated_since (ISO datetime), status=active,refunded, issued_from и issued_to (даты), page, page_size (1–100; по умолчанию 20). Возвращаются выпущенные путёвки и их возвраты; неподтверждённые бронирования сюда не входят.

Поля путёвки

session содержит id, name, starts_at, ends_at, price, nomenclature_name. Например: Морские волки · 01.07.2026–14.07.2026.

parent содержит id, last_name, first_name, middle_name, phone, email, birth_date, passport_series, passport_number, passport_issued_by, passport_issued_date, passport_code, registration_address.

child содержит id, last_name, first_name, middle_name, birth_date, gender, document_type, document_series, document_number. Пол: male/female; документ: passport/birth_certificate либо незаполненное значение. Пол родителя не передаётся. Необязательные персональные поля могут быть пустыми или null.

Как использовать в 1С

• Номенклатуру сопоставляйте по session.id, название берите из session.nomenclature_name.
• Текст строки печатной формы берите из service_description. Он включает лагерь, смену и ребёнка; длина ограничена форматом действующего чека.
• Не создавайте отдельную номенклатуру на каждого ребёнка.
• Изменение названия или дат смены обнаруживается через updated_since и обновляет существующее соответствие. Аналогично учитываются изменения ребёнка, родителя, заказа, лагеря и договора в поддерживаемых путях изменения данных.
• final_price уже содержит применённую скидку. Повторно вычитать её нельзя. В текущей модели итог может включать трансфер; не прибавляйте его второй раз. Комиссия ЮKassa не уменьшает final_price.
• Уже проведённые документы и ранее выданные PDF не перезаписываются автоматически самой платформой. Правило исправлений в 1С определяет бухгалтер лагеря.
• Номер документа реализации назначает 1С. Не заменяйте его order_number или ID платформы.

Даты выпуска путёвки и готовности акта имеют разный смысл. Условие формирования бухгалтерского документа и его дата задаются настройкой обработки 1С по правилам лагеря.

5. Оплаты

GET /accounting/payments?updated_since=2026-09-01T00:00:00Z&page_size=100

Параметры: updated_since, date_from, date_to, page, page_size.

Возвращаются успешные оплаты. В v2 инкрементальный отбор выполняется по updated_at: платёж, созданный вчера и подтверждённый сегодня, попадает в сегодняшний обмен. Для дедупликации используйте id, а не дату или сумму.

Суммы после удержаний и комиссия ЮKassa

Новые поля добавлены в обычный список оплат и в записи пакетов resource=payments. Существующие amount оплаты и final_price путёвки сохраняют прежний смысл. Обработка 1С должна читать новые поля отдельно, чтобы учитывать комиссию. Для автоматического получения комиссии и дозаполнения старых оплат используйте POST /accounting/sync-batches с resource=payments и сохраняйте next_updated_since после обработки всех страниц; порядок описан в разделе 8.

Пример полей одной оплаты при удержании 305 ₽ с 10 000 ₽:

{
  "amount": "10000.00",
  "income_amount": "9695.00",
  "fee_total": "305.00",
  "income_status": "available"
}

Стоимость реализации и оплата родителя в таком примере остаются 10 000 ₽. 305 ₽ передаются отдельно для учёта удержания ЮKassa; 9 695 ₽ — сумма после удержаний. Конкретные документы, счета и проводки определяет бухгалтер для своей конфигурации 1С. Эти данные не подтверждают дату фактического зачисления денег на банковский или лицевой счёт и не заменяют банковскую или казначейскую выписку. Удержанную комиссию не нужно повторно перечислять ЮKassa.

fee_total содержит совокупное удержание. API не разбивает его по видам услуг и НДС: сведения об информационно-технологических услугах, проведении расчётов и НДС берите из реестров и УПД ЮKassa. Нельзя начислять НДС на всё удержание по единой ставке или создавать повторный расход, если комиссия уже учтена другим обменом. Возвраты учитываются отдельно: эти поля не являются суммой платежа за вычетом возвратов.

Одно перечисление — несколько оплат родителей

Оплата родителя и фактическое перечисление на банковский или лицевой счёт лагеря — разные события. Если обработка создаёт поступление на счёт по каждой оплате с платформы, а выписка затем добавляет общий перевод платёжного сервиса, поступления задваиваются. Замена amount на income_amount эту ошибку не исправляет.

Пример без возвратов и переходящих остатков: три родителя оплатили по 10 000 ₽. Платформа передаёт три оплаты на общие 30 000 ₽ и три удержания по 305 ₽, всего 915 ₽. Если эти деньги перечислены одним переводом, выписка отражает одно поступление 29 085 ₽. Три дополнительных поступления по 10 000 ₽ или по 9 695 ₽ на счёт лагеря из данных платформы создавать не нужно.

Не формируйте документ фактического поступления суммированием income_amount за вчерашний paid_at: дата оплаты не определяет состав и дату перевода. Выходные, сроки перечислений, возвраты и остатки могут изменять сумму и дату поступления; их подтверждают выписка и сведения провайдера. См. правила перечислений ЮKassa. yookassa_payment_id идентифицирует оплату родителя у провайдера, а не общий перевод.

Контрагента и договор сопоставляйте по реквизитам плательщика в выписке и условиям подключения. Не подставляйте родителя или название «ЮKassa» автоматически: платёжный агрегатор и банк плательщика могут быть разными организациями. Название банка плательщика само по себе не определяет контрагента.

Если расход по комиссии и НДС уже отражаются по УПД ЮKassa, fee_total используется для удержания и сверки, а не для второго начисления того же расхода. Удержание не является новым перечислением лагеря поставщику: не создавайте фиктивное списание поверх фактической выписки.

Документы и счета зависят от конфигурации 1С

Для карточных оплат в типовой коммерческой «1С:Бухгалтерии 8» применяется документ «Оплата платежной картой» и транзитный счёт 57.03; проводка по дебету 51 относится к фактическому банковскому зачислению. Это пример для конкретной конфигурации, описанный в материале 1С об эквайринге. Если бухгалтер настроил расчёты через 76.09, обработка поддерживает согласованную схему вместо параллельного отражения той же оплаты ещё и через 57.03.

В «1С:Бухгалтерии государственного учреждения» используются собственные документы и план счетов, в том числе для поступлений на лицевые счета казначейства. Счета 51, 57.03 и 76.09 из коммерческого примера нельзя переносить туда автоматически. Для СБП и других способов оплаты документ также выбирается по конфигурации: method=yookassa само по себе не означает оплату картой. Разработчик и бухгалтер должны согласовать схему для используемой базы; API не задаёт бухгалтерские счета.

Переход с обработки, создававшей лишние поступления

Разработчик 1С должен отключить создание факта поступления на банковский или лицевой счёт из каждой оплаты ЮKassa и настроить отдельный учёт оплат через сервис. С бухгалтером проверьте уже созданные документы и их движения; исправляйте или сторнируйте ошибочные поступления по правилам базы и закрытых периодов, сохраняя связи с родителями, заказами и ID оплат. Не удаляйте всю загруженную историю автоматически. Реальное поступление из выписки должно остаться в учёте один раз.

Сохраняйте соответствие payment.id платформы документу оплаты 1С и выполняйте создание или обновление по этому ID. Для комиссии храните связь с той же оплатой; для фактического перечисления используйте идентификаторы самой выписки. Платформа передаёт данные и не исправляет документы или дубли в базе 1С самостоятельно.

Если раньше суммы после удержаний не было

Платформа сохраняет подтверждённую сумму ЮKassa. Если её нет, выгрузка возвращает pending и запускает фоновое получение данных по точному платежу. Фоновое задание также дозаполняет старые успешные оплаты; недоступные данные повторно запрашиваются с паузой. Платформа не подставляет предполагаемый процент, нулевую комиссию или полную сумму вместо неизвестной суммы после удержаний. При неоднозначной связи старой оплаты с платежом или недоступных настройках ЮKassa состояние остаётся pending до устранения причины.

После успешного получения данных обновляется updated_at записи оплаты. Она повторно попадает в инкрементальный обмен с тем же id. Обработка должна обновить существующую оплату и связанную комиссию, сохранив исходную сумму оплаты. Для операции комиссии используйте устойчивое соответствие с id оплаты на платформе; yookassa_payment_id позволяет сверять её с ЮKassa и другими загрузками. Повторная выдача записи не должна создавать вторую оплату или вторую комиссию.

Страницы уже созданного пакета неизменны: запись с pending внутри него не станет available. Сохраните результат пакета и его next_updated_since, затем создайте следующий пакет с этой границей. Полученные позже суммы придут как обновление оплаты. Не нужно удерживать весь обмен в ожидании комиссии. Если параллельно используется штатный модуль ЮKassa в 1С или загрузка банковской выписки, настройте сопоставление операций и исключите дубли.

vat_code и tax_system_code относятся к данным услуги/лагеря. Их маппинг и исторические значения должны поддерживаться обработкой; НДС с комиссии эквайера не берётся из vat_code путёвки.

6. PDF договоров в 1С

GET /accounting/contracts?updated_since=2026-09-01T00:00:00Z&page_size=100

Этот список возвращает созданные индивидуальные договоры лагеря независимо от режима оформления и наличия уже выпущенной путёвки. Параметры: updated_since, page, page_size. Готовая публичная оферта лагеря не является индивидуальным договором и этим маршрутом не выдаётся.

Поддерживаются оба сценария:

1. Договор подписан онлайн: выгружается подписанный PDF из сервиса подписи.
2. Включена дополнительная генерация договоров, в том числе при публичной оферте: выгружается созданный PDF. Для получения файла не требуется онлайн-подпись.

Метаданные договора

GET /accounting/contracts/{id}/file?version={version}
X-API-Key: YOUR_CAMP_API_KEY

Передавайте ключ и при скачивании PDF. Файл хранится в 1С как вложение к соответствующему договору/продаже. version не является SHA-256 содержимого PDF; сравнивайте её как непрозрачный идентификатор изменения.

Если версия изменилась между чтением списка и скачиванием, API вернёт 409. Получите актуальный список/метаданные и повторите запрос. Если сервис подписи недоступен, API вернёт 503; подписанный экземпляр не подменяется неподписанным.

Сформированный для очной подписи договор не считается подписанным только потому, что существует PDF. file_variant=generated может также относиться к подписи, зарегистрированной вручную: этот файл остаётся исходным созданным экземпляром, а не сканом подписанного документа.

Договоры синхронизируйте отдельным потоком. Так договор, созданный после загрузки продажи, не потеряется. Для вложений ведите соответствие contract.id + version; обновляйте вложение по правилам хранения редакций в вашей 1С.

7. Автоматическая отправка актов и УПД

Обработка 1С автоматически ставит документ в очередь отправки после проведения/готовности выбранной печатной формы. Отдельного подтверждения на платформе нет. Расписание обработки выбирает лагерь; рекомендуем 5–15 минут.

Точный критерий готовности задайте в 1С: печатная форма должна быть готова к просмотру сотрудниками лагеря. Черновики в этот поток не отправляются. Изменение печатной формы увеличивает revision; отмена проведения или удаление ранее опубликованной формы отправляет отзыв. Эти события должны сохраняться в очереди до подтверждения API.

Адрес

PUT /accounting/documents/{kind}/{external_id}

• kind: act (акт оказания услуг) либо upd (УПД).
• external_id: GUID документа 1С, неизменный при повторах.
• source_id: постоянный GUID базы/подключения 1С, хранится в настройках. При замене API-ключа не меняется.

Акт и УПД одной реализации могут использовать одинаковый external_id: тип входит в ключ уникальности. Отправляйте только реально используемые печатные формы. API сохраняет документы и не создаёт повторную реализацию, оплату или чек.

Публикация: multipart/form-data

Передайте поле metadata с JSON-строкой и поле file с двоичным PDF. Boundary устанавливается отправителем HTTP-запроса. В metadata:

{
  "source_id": "22222222-2222-4222-8222-222222222222",
  "revision": 1,
  "status": "published",
  "number": "ACT-000123",
  "date": "2026-09-15",
  "amount": "40000.00",
  "currency": "RUB",
  "order_item_ids": [42]
}

Все данные примера синтетические. order_item_ids берутся из выгрузки платформы; случайные номера использовать нельзя.

Ограничения PDF: до 20 МиБ, 1–500 страниц, без пароля, корректный PDF. Файл Base64 в JSON не поддерживается. Не отправляйте сводный документ разных заказов или родителей.

Ответ

{
  "success": true,
  "data": {
    "applied": true,
    "received_revision": 1,
    "document": {
      "id": "33333333-3333-4333-8333-333333333333",
      "source_id": "22222222-2222-4222-8222-222222222222",
      "external_id": "11111111-1111-4111-8111-111111111111",
      "kind": "act",
      "kind_display": "Акт оказания услуг",
      "order_id": 15,
      "order_item_ids": [42],
      "number": "ACT-000123",
      "date": "2026-09-15",
      "amount": "40000.00",
      "currency": "RUB",
      "revision": 1,
      "status": "published",
      "status_display": "Доступен",
      "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
      "created_at": "2026-09-15T12:00:00Z",
      "updated_at": "2026-09-15T12:00:00Z"
    }
  },
  "meta": {"trace_id":"request-trace-id"}
}

sha256 фактически содержит 64 шестнадцатеричных символа, вычисленных сервером по файлу. applied=false означает, что идентичная версия уже принята. Это успешный результат. Поле document показывает текущую версию: она может быть новее повторно отправленной.

Повтор, исправление и отзыв

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

Отзыв: тот же PUT, JSON без файла. Передайте полные метаданные, увеличенную версию и status=revoked:

{
  "source_id": "22222222-2222-4222-8222-222222222222",
  "revision": 2,
  "status": "revoked",
  "number": "ACT-000123",
  "date": "2026-09-15",
  "amount": "40000.00",
  "currency": "RUB",
  "order_item_ids": [42]
}

В панели лагеря остаётся запись Отозван, открыть PDF нельзя. Ранее выданная краткоживущая ссылка может работать до истечения её срока (до 5 минут). Уже скачанные пользователем копии удалить невозможно. Повторная публикация после отзыва требует новой версии и PDF.

8. Надёжная постраничная синхронизация

Обычные списки сохранены для совместимости. Для автоматического обмена оплатами и комиссией используйте пакеты resource=payments: содержимое страниц фиксируется на момент создания пакета и не меняется при параллельном редактировании данных.

Обычный GET /accounting/payments использует страницы и сортировку по updated_at. Если между запросами изменяются оплаты, в том числе при переходе pending → available, записи могут переместиться между страницами и часть оплат может быть пропущена. Такой обход не гарантирует полноту при параллельных изменениях и не подходит для надёжного автоматического дозаполнения истории. Пакеты устраняют перемещение записей внутри конкретной выгрузки; обработка 1С всё равно должна выполнять создание или обновление по id, чтобы исключать дубли между запусками.

Создать пакет

POST /accounting/sync-batches
Content-Type: application/json

{"resource":"vouchers","updated_since":"2026-09-01T00:00:00Z"}

resource: vouchers, payments, contracts. При первом запуске updated_since опускается. Создавайте отдельный пакет и храните отдельную границу для каждого ресурса.

Ответ 201, поля data: id, resource, count, started_at, next_updated_since, expires_at, page_url.

1. Получить page_url с ключом, при желании добавить page_size=100.
2. Обработать все страницы по meta.pagination.next.
3. Завершить загрузку необходимых PDF; при ошибке сохранить её в устойчивой очереди повтора либо не завершать пакет.
4. Только после устойчивого сохранения всех результатов записать next_updated_since как новую границу этого ресурса.
5. Удалить пакет: DELETE /accounting/sync-batches/{id}.

Не подставляйте время окончания обработки с часов компьютера 1С. next_updated_since содержит время начала серверного запуска с перекрытием 5 минут. Повторяющиеся записи в этом интервале нормальны: они обрабатываются по ID/версии.

Пакет доступен 24 часа. После истечения создайте новый с прежней успешно сохранённой границей. Максимум: 10 неистёкших пакетов на лагерь, 10 000 записей в одном пакете. Просроченные пакеты удаляются фоновым заданием и при следующем создании пакета этого лагеря.

Если первичная загрузка превышает 10 000 записей, согласуйте с поддержкой порядок получения полной истории до запуска автоматического обмена; обычный список страниц при параллельных изменениях не обеспечивает её полноту. Для контроля делайте периодическую полную сверку ID, количества и сумм: пакет фиксирует страницы, но не заменяет сверку и не гарантирует учёт произвольных изменений БД вне штатных путей приложения.

Не запускайте создание нескольких пакетов одного ресурса параллельно. В ссылках переходов проверяйте ожидаемый API-origin перед передачей ключа.

9. Что увидят сотрудники лагеря

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

Документ привязан к заказу и его позициям. Сотрудник видит акты и УПД только в заказах доступного ему лагеря. В ЛК родителя они недоступны, в том числе в комплекте документов. Общие документы нескольких разных заказов не принимаются.

Новые редакции поступают автоматически из 1С. Для просмотра обновлённого состояния откройте заказ заново или обновите страницу. Изменять бухгалтерский PDF следует в 1С, затем отправлять новую редакцию; наша платформа его не перегенерирует.

10. Приёмка перед подключением лагеря

Проверьте на тестовых данных:

1. Верный/неверный ключ и отсутствие права загрузки.
2. Новую продажу, повтор полной выгрузки и отсутствие дублей.
3. Поздно подтверждённую оплату и несколько страниц данных.
4. Изменение даты смены после первой загрузки.
5. Онлайн-подписанный договор и дополнительно сгенерированный договор при оферте.
6. Автоматическую отправку акта и УПД одной реализации.
7. Повтор файла, новую редакцию, отзыв и повтор старого запроса после отзыва.
8. Обрыв сети после принятия файла сервером, но до получения ответа 1С.
9. Недоступность PDF-хранилища/сервиса подписи.
10. Правильные суммы и принадлежность актов и УПД в панели лагеря; отсутствие этих документов в ЛК родителя и его комплекте.
11. Оплату ЮKassa с available: исходные amount и final_price сохранены, комиссия учитывается отдельно и не дублируется при повторной загрузке.
12. Старую оплату с pending: после фонового получения суммы она приходит повторно с тем же id и новым updated_at, в том числе через следующий пакет.
13. Отсутствие данных или сбой ЮKassa: pending и null, без выдуманной нулевой комиссии; для наличных, терминала и счёта — not_applicable.
14. Несколько оплат родителей и одно перечисление: оплаты загружены на полную сумму без отдельных поступлений на банковский или лицевой счёт; реальное перечисление и расход по комиссии учтены один раз, плательщик взят из выписки.
15. Переход с прежней обработки: исправлены лишние банковские поступления, сохранены связи оплат и отсутствуют дубли после повторной выгрузки.

В v2 не включены выставление счетов из 1С, подтверждение банковских оплат из 1С и команды фактического возврата денег. Акты и УПД передаются как PDF; обмен титулами ЭДО/XML и подписание документов на платформе этим протоколом не выполняются.