Справочники — Договора

Метод для создания или обновления договоров с условиями (товары, услуги, зоны доставки) в Цифре из 1С.

POST /api/contract/create

Для создания или обновления договоров в Цифре необходимо отправить запрос на метод API, передав массив договоров в поле Data.

Параметры запроса

Параметр	Тип	Обязательный	Описание
`SecretKey`	string	Да	Секретный ключ
`Data`	array	Да	Массив договоров для создания/обновления

Логика работы

Данные передаются в массиве Data
Если договор с переданным Guid уже существует в системе — он будет обновлён
Если договора с таким Guid нет — будет создан новый
При обновлении договора товары, не переданные в Conditions, будут удалены из договора

Структура Data[]

Поле	Тип	Обязательное	Описание
`Guid`	string	Да	Идентификатор договора в 1C
`CompanyGuid`	string	Условно	Идентификатор контрагента в 1С. Обязателен для индивидуальных договоров
`CompanyName`	string	Условно	Название контрагента. Обязательно только если компании с `CompanyGuid` ещё нет в Цифре — тогда она будет создана с этим именем. Для уже существующих компаний поле можно не передавать
`TemplateType`	string	Нет	Тип договора: `typical` (типовой) или `individual` (индивидуальный)
`Name`	string	Нет	Название договора
`Date`	datetime	Нет	Дата договора
`Balance`	float	Нет	Баланс договора. Может быть положительным, отрицательным, дробным
`Status`	string	Нет	Статус документа (по умолчанию `confirmed`). Допустимые значения: `confirmed` (Действует), `not-confirmed` (Не согласован), `done` (Закрыто)
`Organization`	object	Нет	Поставщик. Если передан и не пустой — обязательны `Name` и `Guid`. См. карточку ниже
`Conditions`	array	Нет	Условия договора — товары, услуги и зоны доставки (см. карточки ниже)

Organization — Поставщик

Необязательный объект. Если передан и не пустой — оба поля обязательны. Поставщик ищется по Guid; если не найден — создаётся с типом Поставщик. При невалидном поставщике документ всё равно создаётся (без поставщика), ошибка попадает в errors.

Поле	Тип	Обязательное	Описание
`Guid`	string	Да	Идентификатор поставщика в 1C
`Name`	string	Да	Наименование поставщика

Conditions[] — Товары

Применяется, когда поле Service пустое, null или отсутствует.

Поле	Тип	Обязательное	Описание
`Guid`	string	Да	Идентификатор товара в 1C
`Name`	string	Да	Наименование товара
Остальные поля (`Price`, `VatRate`, `Unit`, `Sku`, `Characteristics` и др.) — см. документацию по продукции

Conditions[] — Услуги

Применяется, когда указан Service.

Поле	Тип	Обязательное	Описание
`Guid`	string	Да	Идентификатор услуги в 1C
`Name`	string	Да	Наименование услуги
`Service`	string	Да	Тип услуги: `mix` (доставка), `downtime` (простой), `pump` (насос), `other` (прочее)
`Price`	float	Нет	Цена услуги (по умолчанию 0)
`VatRate`	float	Нет	Процент НДС (по умолчанию 0)
`VatInPrice`	boolean	Нет	Включен ли НДС в цену (по умолчанию false)
`PriceType`	string	Нет	Тип цены (по умолчанию `by_one`). См. карточку «Типы цен» ниже

Conditions[] — Зоны доставки

Применяется, когда Zone = true.

Поле	Тип	Обязательное	Описание
`Zone`	boolean	Да	Должно быть `true` для обозначения зоны доставки
`Guid`	string	Да	Идентификатор зоны в 1C
`Name`	string	Да	Название зоны доставки
Остальные поля — см. документацию по зонам доставки

Типы цен (PriceType)

Допустимые значения PriceType зависят от типа услуги.

Тип услуги (Service)	Допустимые значения PriceType	Описание
`mix`	`by_one`, `by_all`	За 1 м³ или за рейс
`pump`	`by_one`, `by_all`	За единицу или за все единоразово
`downtime`	`free`, `by_one`	Бесплатно или за час
`other`	`by_one`, `by_all`	За единицу или за все единоразово

Примечания

Типы договоров (TemplateType):
- typical (типовой) — договор-шаблон без привязки к контрагенту. Поле company_id будет null
- individual (индивидуальный) — договор с конкретным контрагентом. Требуется CompanyGuid
Определение типа договора:
- Если указан TemplateType = typical → типовой договор (CompanyGuid не обязателен)
- Если указан TemplateType = individual → индивидуальный договор (требуется CompanyGuid)
- Если TemplateType не указан, но есть CompanyGuid → individual
- Если TemplateType не указан и нет CompanyGuid → ошибка
Обязательные поля договора: Guid. Для индивидуальных договоров — также CompanyGuid
Обязательные поля товара: Guid, Name
Обязательные поля услуги: Guid, Name, Service
Валидация услуг: PriceType должен соответствовать типу услуги. Для mix, pump, other: by_one или by_all. Для downtime: free или by_one
Обязательные поля зоны доставки: Zone = true, Guid, Name
Обязательные поля тарифов в зонах: Guid, Name, Service. Валидация PriceType аналогична услугам
Определение типа элемента Conditions:
- Если Zone = true — обрабатывается как зона доставки
- Если Service пустой / null / отсутствует — обрабатывается как товар
- Если Service указан — обрабатывается как услуга
Характеристики товаров: для товаров с характеристиками создаётся отдельная связь документа с товаром для каждой характеристики; характеристики без Guid пропускаются; если характеристик нет — создаётся одна связь с простым GUID товара
Синхронизация товаров: при обновлении договора товары, которые не были переданы в Conditions, будут удалены. Количество отображается в ответе: "удалено товаров: N"
Для индивидуальных договоров: если компания с CompanyGuid уже существует — используется она; если нет — будет создана автоматически по CompanyGuid + CompanyName. Если компании нет и CompanyName не передан — договор не создаётся, ошибка попадает в errors
Компания не будет создана, если её CompanyName входит в стоп-лист: ручной, тест, (не выбран), физ.лицо. В этом случае ошибка попадает в errors
Баланс (Balance): пишется в поле total документа. Поддерживаются положительные, отрицательные и дробные значения. Если поле не передано — значение total не меняется
Статус (Status): по умолчанию confirmed. Поддерживаемые значения: not-confirmed, confirmed, done, archived. Неизвестное значение тихо заменяется на confirmed
Поставщик (Organization): необязателен. Если передан непустым, то Name и Guid обязательны. Невалидный поставщик (нет Name/Guid или имя в стоп-листе ручной, тест, (не выбран), физ.лицо) не блокирует создание документа — документ сохраняется без поставщика, а ошибка попадает в errors (частичный успех)
Товары/услуги/зоны без обязательных полей пропускаются и не создаются
Поля Min и Max для услуг в договорах НЕ используются (только для зон доставки)
Не отправляйте за раз более 2000 договоров или более 1 МБ данных

Пример запроса 1С → Цифра

{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Data": [
    {
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "CompanyGuid": "33ab5192-265g-22fc-a84f-355cgfdc5f1b",
      "CompanyName": "ООО Ромашка",
      "TemplateType": "individual",
      "Name": "Договор поставки №43",
      "Date": "2024-04-03 00:00:00",
      "Balance": -125000.50,
      "Status": "confirmed",
      "Organization": {
        "Guid": "88gh1647-720l-77kh-f39k-800hkllh0k6g",
        "Name": "ООО Поставщик"
      },
      "Conditions": [
        {
          "Guid": "44cd6203-376h-33gd-b95g-466dghde6g2c",
          "Name": "БСТ М400",
          "Sku": "БСГ-М400",
          "Unit": "м³",
          "Price": 5000,
          "Total": 10,
          "Vat": 20,
          "VatInPrice": true,
          "Characteristics": [
            {
              "Guid": "char-001-aaa",
              "Name": "F200"
            },
            {
              "Guid": "char-002-bbb",
              "Name": "W6"
            }
          ]
        },
        {
          "Guid": "66ef8425-598j-55if-d17i-688fijgf8i4e",
          "Name": "Щебень фр. 5-20",
          "Price": 1500,
          "Total": 5,
          "VatRate": 0,
          "VatInPrice": false
        },
        {
          "Guid": "55de7314-487i-44he-c06h-577ehife7h3d",
          "Name": "Доставка",
          "Price": 50,
          "VatRate": 20,
          "VatInPrice": true,
          "Service": "mix"
        },
        {
          "Zone": true,
          "Guid": "zone-77fg9536-609k-66jg-e28j-799gjkhg9j5f",
          "Name": "Зона А - Центральный район",
          "Price": 100
        }
      ]
    }
  ]
}

Коды ответов

Код	Описание
201	Успешное создание. Все договоры обработаны без ошибок (`success: true`)
207	Частичный успех. Часть данных обработана, но есть ошибки (`success: true`)
401	Ошибка ключа. Секретный ключ не найден (`success: false`)
422	Ошибка валидации. Data должен быть массивом (`success: false`)
500	Ошибка сервера. Внутренняя ошибка обработки (`success: false`)

Структура ответа

Поле	Тип	Описание
`success`	boolean	Успешность операции
`message`	string	Сообщение об успешных операциях
`data_id`	integer	ID записи в логе
`errors`	array	Массив ошибок (только при наличии ошибок)

Примеры ответов

{
  "success": true,
  "message": "Добавлено документов: 1, товаров: 3, удалено товаров: 2, сервисов: 2, зон: 1",
  "data_id": 123
}

{
  "success": true,
  "message": "Добавлено документов: 1, товаров: 1, удалено товаров: 1, сервисов: 1, зон: 0",
  "data_id": 123,
  "errors": [
    "Документов без GUID: 1",
    "Договоров без CompanyName (нужен для создания новой компании): 1",
    "Документов без Organization.Name: 1",
    "Документов без Organization.Guid: 1",
    "Не удалось создать поставщика (имя в стоп-листе: \"ручной\", \"тест\", \"(не выбран)\", \"физ.лицо\"): 1",
    "Товаров без GUID: 2",
    "Услуг без типа: 1"
  ]
}

{
  "success": false,
  "message": "Секретный ключ не найден",
  "data_id": null
}

{
  "success": false,
  "message": "Неверный тип данных",
  "data_id": 123
}

{
  "success": false,
  "message": "Произошла ошибка: подробное описание ошибки",
  "data_id": 123
}

См. также

Создание контрагентов

company/create

Создание продукции

product/create

Создание зон доставки

delivery_zone/create

Инструкция по заданию createContract

Создание договора в 1С