Цифра ↔ 1С

Договора

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

POST /api/contract/create

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

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

Параметр Тип Обязательный Описание
SecretKey string Да Секретный ключ
Data array Да Массив договоров для создания/обновления
Логика работы
  • Данные передаются в массиве Data
  • Если договор с переданным Guid уже существует в системе — он будет обновлён
  • Если договора с таким Guid нет — будет создан новый
  • При обновлении договора товары, не переданные в Conditions, будут удалены из договора

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

Поле Тип Обязательное Описание
Guid string Да Идентификатор договора в 1C
CompanyGuid string Условно Идентификатор контрагента в 1С
CompanyName string Условно Название контрагента
TemplateType string Нет Тип договора
Name string Нет Название договора
Date datetime Нет Дата договора
Balance float Нет Баланс договора
Status string Нет Статус документа

Типы цен (PriceType)

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

Тип услуги (Service) Допустимые значения PriceType Описание
mixby_one, by_allЗа 1 м³ или за рейс
pumpby_one, by_allЗа единицу или за все единоразово
downtimefree, by_oneБесплатно или за час
otherby_one, by_allЗа единицу или за все единоразово
Примечания
  • Типы договоров (TemplateType):
    • typical (типовой) — договор-шаблон без привязки к контрагенту. Поле company_id будет null
    • individual (индивидуальный) — договор с конкретным контрагентом. Требуется CompanyGuid
  • Определение типа договора:
    • Если указан TemplateType = typical → типовой договор (CompanyGuid не обязателен)
    • Если указан TemplateType = individual → индивидуальный договор (требуется CompanyGuid)
    • Если TemplateType не указан, но есть CompanyGuid → individual
    • Если TemplateType не указан и нет CompanyGuid → ошибка
  • Обязательные поля договора: Guid. Для индивидуальных договоров — также CompanyGuid, а CompanyName — только если компании с этим CompanyGuid ещё нет в Цифре: тогда она будет создана с этим именем. Для уже существующих компаний поле можно не передавать
  • Обязательные поля товара: Guid, Name
  • Обязательные поля услуги: Guid, Name, Service
  • Валидация услуг: PriceType должен соответствовать типу услуги. Для mix, pump, other: by_one или by_all. Для downtime: free или by_one
  • Значения по умолчанию для услуг: Price и VatRate — 0, VatInPrice — false, PriceType — by_one
  • Обязательные поля зоны доставки: Zone = true, Guid, Name
  • Обязательные поля тарифов в зонах: Guid, Name, Service. Валидация PriceType аналогична услугам
  • Определение типа элемента Conditions:
    • Если Zone = true — обрабатывается как зона доставки
    • Если Service пустой / null / отсутствует — обрабатывается как товар
    • Если Service указан — обрабатывается как услуга
  • Характеристики товаров: для каждой характеристики создаётся отдельная связь с документом; характеристики без Guid пропускаются. У характеристики могут быть свои Price, VatRate, VatInPrice — если не указаны, наследуются от товара
  • Синхронизация товаров: при обновлении договора товары, которые не были переданы в Conditions, будут удалены. Количество отображается в ответе: "удалено товаров: N"
  • Для индивидуальных договоров: если компания с CompanyGuid уже существует — используется она; если нет — будет создана автоматически по CompanyGuid + CompanyName. Если компании нет и CompanyName не передан — договор не создаётся, ошибка попадает в errors
  • Компания не будет создана, если её CompanyName входит в стоп-лист: ручной, (не выбран). В этом случае ошибка попадает в errors
  • Баланс (Balance): пишется в поле total документа. Поддерживаются положительные, отрицательные и дробные значения. Если поле не передано — значение total не меняется
  • Количество товара (Total): необязательное поле. Если не передано, передано пустым или null — в БД пишется NULL, и сумма по этой позиции не учитывается в общей сумме договора. Чтобы зафиксировать нулевой объём, передавайте 0 явно
  • Статус (Status): по умолчанию confirmed. Поддерживаемые значения: confirmed (Действует), not-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)
403Ошибка ключа. Секретный ключ не найден (success: false)
422Ошибка валидации. Data должен быть массивом (success: false)
500Ошибка сервера. Внутренняя ошибка обработки (success: false)

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

ПолеТипОписание
successbooleanУспешность операции
messagestringСообщение об успешных операциях
data_idintegerID записи в логе
errorsarrayМассив ошибок (только при наличии ошибок)

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

{
  "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
}

Подробности внутренней ошибки в ответ не попадают: причина фиксируется на стороне Цифры, искать её в теле ответа не нужно. Если ошибка повторяется — обратитесь в поддержку Цифры, указав data_id.

См. также

Создание контрагентов
company/create
Создание продукции
product/create
Создание зон доставки
delivery_zone/create
Создание счетов
invoice/create
Инструкция по заданию createContract
Создание договора в 1С