Цифра ↔ 1С

Счета

Метод для создания или обновления счетов на оплату в Цифре из 1С.

POST /api/invoice/create

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

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

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

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

Поле Тип Обязательное Описание
Guid string Да Идентификатор счёта в 1C
CompanyGuid string Да Идентификатор контрагента
CompanyName string Да Название компании
Date datetime Нет Дата счёта
Status string Нет Статус счёта
ContractGuid string Нет Идентификатор договора
ContractName string Нет Название договора
Sum float Нет Сумма счёта

Автоматическое определение VatInPrice

Если поле VatInPrice не указано в товарах счёта, система автоматически определяет его значение на основе математических расчётов:

Логика работы
  • НДС не включён в цену (VatInPrice = false) — когда Sum ≈ Price × Quantity (с погрешностью 0.01)
  • НДС включён в цену (VatInPrice = true) — когда Sum ≈ (Price × Quantity) + VatMount (с погрешностью 0.01)

Примеры автоматического определения

Пример 1: НДС не включён 1С → Цифра 
{
  "Price": 1000,
  "Quantity": 2,
  "Sum": 2000,
  "VatRate": 20,
  "VatMount": 400
}

Результат: VatInPrice = false, так как Sum = Price × Quantity = 2000.

Пример 2: НДС включён 1С → Цифра 
{
  "Price": 1000,
  "Quantity": 2,
  "Sum": 2400,
  "VatRate": 20,
  "VatMount": 400
}

Результат: VatInPrice = true, так как Sum = (Price × Quantity) + VatMount = 2400.

Примечания
  • Обязательные поля счёта: Guid, CompanyName, CompanyGuid
  • Обязательные поля товара: Guid, Name
  • Перед созданием счёта система автоматически создаёт или находит компанию по CompanyName и CompanyGuid
  • Если указан ContractGuid, система ищет существующий договор или создаёт новый с указанным ContractName
  • Счёт связывается с договором через поле parent_id, если договор найден или создан
  • Валидация товаров: товары без обязательных полей (Guid, Name) будут пропущены, но счёт будет создан. Информация о пропущенных товарах отображается в ответе
  • Если поле VatInPrice не указано, оно определяется автоматически на основе математических расчётов
  • Статус счёта (Status): по умолчанию "Не оплачен". Возможные значения: "Оплачен", "Оплачен частично", "Отменен"
  • Числовые поля товара (Price, Quantity, Sum, VatMount, VatRate): по умолчанию 0, поддерживается формат с запятой или точкой
  • VatRate может быть указан с символом процента (например, "20%") или без него (например, 20)
  • Sum и VatMount используются для автоматического определения VatInPrice
  • Не отправляйте за раз более 2000 счетов или более 1 МБ данных
Пример запроса 1С → Цифра 
{
  "SecretKey": "2akgzOCYsAxLwpNl",
  "Data": [
    {
      "Guid": "22db4291-154f-11ec-973e-244bfecb4e0a",
      "CompanyGuid": "33ab5192-265g-22fc-a84f-355cgfdc5f1b",
      "CompanyName": "ООО Поставки",
      "Date": "2024-03-27 10:45:01",
      "Status": "Оплачен",
      "ContractGuid": "44cd6203-376h-33gd-b95g-466dghde6g2c",
      "ContractName": "№11 от 29.04.2022",
      "Sum": 15000,
      "Products": [
        {
          "Guid": "55de7314-487i-44he-c06h-577ehife7h3d",
          "Name": "Бетон М150",
          "Quantity": 4,
          "Price": 4000,
          "Sum": 16000,
          "VatRate": 20,
          "VatMount": 3200,
          "VatInPrice": false
        }
      ]
    }
  ]
}

Коды ответов

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

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

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

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

{
  "success": true,
  "message": "Создано счетов: 2",
  "data_id": 123
}
{
  "success": true,
  "message": "Создано счетов: 1",
  "data_id": 123,
  "errors": [
    "Счетов без GUID: 1",
    "Счетов без CompanyGuid: 1",
    "Не удалось создать компанию (имя в стоп-листе: \"ручной\", \"(не выбран)\"): 1",
    "Товаров без GUID: 2"
  ]
}
{
  "success": false,
  "message": "Секретный ключ не найден",
  "data_id": null
}
{
  "success": false,
  "message": "Неверный тип данных",
  "data_id": 123
}
{
  "success": false,
  "message": "Произошла внутренняя ошибка",
  "data_id": 123
}

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

См. также

Создание контрагентов
Справочник — Контрагенты
Создание договоров
Справочник — Договора
Двусторонний обмен данных
Общая информация