Электронный документооборот

Объект «Документ» в API

Объект «Документ» в API

Для выполнения команд API-интерфейса, которые связаны с операциями по документу, используется объект «Документ». Он определяет параметры любого исходящего или входящего документа в СБИС.

Структура объекта «Документ»

Условные обозначения:

Синие — параметры, которые возвращаются с сервера СБИС. Эти поля доступны только для чтения.

Красные — параметры, которые передаются на сервер как аргумент функции. Поля доступны только для записи.

Черные — параметры, которые можно как передать на сервер, так и получить в ответе на команду.

  • "Идентификатор": строка, используется для адресации документа
  • "Дата": строка в формате "ДД.ММ.ГГГГ". Используется при сортировке и фильтрации по типам в реестрах документов на online.sbis.ru
  • "Номер": строка, номер документа. Для отправляемых пакетов мы рекомендуем указывать уникальные номера
  • "Сумма": строка, содержит сумму документа
  • "Срок": строка в формате "ДД.ММ.ГГГГ", дата документа. Строка используется в некоторых типах документов
  • "Сумма": строка с суммой документа. Содержит сумму из первого формализованного первичного вложения
  • "Название": строка, содержит название документа
  • "Примечание": строка, содержит комментарии к документу в произвольном значении. Можно использовать при фильтрации
  • "ДатаВремяСоздания": строка в формате "ДД.ММ.ГГГГ ЧЧ.ММ.СС". Указывает на дату и время создания документа на сервере
  • "Удален": строка со значением "Да"/"Нет", флаг пометки документа на удаление
  • "Тип": строка, указывает на общий тип документа
  • "Направление": строка, указывающая на направление документа из списка допустимых направлений
  • "СсылкаДляНашаОрганизация": строка, содержит ссылку. При переходе по ссылке отображается карточка документа в личном кабинете организации. Для входа в кабинет может потребоваться аутентификация
  • "СсылкаДляКонтрагент": строка, содержит ссылку. При переходе по ссылке открывается карточка документа в личном кабинете контрагента. Для входа в кабинет может потребоваться электронная подпись
  • "СсылкаНаАрхив": строка, содержит ссылку на архив последней редакции документа, вложений и ЭП
  • "СсылкаНаPDF": строка, содержит ссылку на pdf-файл, где вложением является формализованный документ с «впечатанными» данными ЭП. Если значение пустое, то получить pdf-представление документа невозможно
  • "Состояние": объект, состояние документа:
  • "Редакция": массив объектов с информацией о редакции документа:
    • "Идентификатор": строка, используется для адресации к редакции документа
    • "Актуален": строка со значением "Да"/"Нет". Если есть более новая редакция, возвращается значение "Нет"
    • "ПримечаниеИС": строка, произвольное примечание информационной системы
    • "ДатаВремя": строка в формате "ДД.ММ.ГГГГ ЧЧ.ММ.СС". Указывает на дату и время, в которые была создана редакция
  • "Регламент": объект, содержит информацию о регламенте документооборота:
    • "Идентификатор": строка
    • "Название": строка
  • "ДокументОснование": массив объектов:
    • "Документ": объект:
      • "Идентификатор": строка
      • "Дата": строка в формате "ДД.ММ.ГГГГ"
      • "Номер": строка
      • "Тип": строка
    • "ВидСвязи": строка
    • "Сумма": строка
  • "ДокументСледствие": массив объектов
  • "НашаОрганизация": объект, который описывает «нашу организацию» по документу:
  • "Контрагент": объект, который описывает контрагента по документу:
  • "Подразделение": объект:
    • "Название": строка, название подразделения
    • "Идентификатор": строка, код подразделения
  • "Ответственный": объект:
    • "Фамилия": строка
    • "Имя": строка
    • "Отчество": строка
    • "Идентификатор": строка, идентификатор во внешней системе
  • "Автор": объект:
    • "Фамилия": строка
    • "Имя": строка
    • "Отчество": строка
    • "Идентификатор": строка, идентификатор во внешней системе
  • "Вложение": массив объектов (вложений документа):
    • "Идентификатор": строка, используется для адресации вложения
    • "Тип": строка, название типа формализованного вложения
    • "Подтип": строка, название подтипа формализованного вложения
    • "ВерсияФормата": строка, значение определяется по содержимому формализованного вложения
    • "ПодверсияФормата": строка, значение определяется по содержимому формализованного вложения
    • "Название": строка, содержит название вложения. Если названия нет, оно генерируется по реквизитам из тела формализованного вложения. Для неформализованного вложения может быть пустым
    • "Удален": строка со значением "Да"/"Нет", флаг пометки вложение на удаление
    • "УдаленКонтрагентом": строка со значением "Да"/"Нет", флаг удаления вложения получателем. Используется для внешнего документооборота
    • "Модифицирован": строка со значением "Да"/"Нет". Позволяет определить, вносились ли правки в тело вложения при подготовке к этапу документооборота. Например, изменился подписант или проставлен идентификатор участника документооборота. Если тело вложения было отредактировано, то нужно обновить данные в информационной системе
    • "Служебный": строка. Значение "Да" — признак служебного вложения, "Нет" — первичного вложения
    • "Дата": строка в формате "ДД.ММ.ГГГГ", извлекается из тела формализованного вложения. Указывает на дату загрузки для неформализованного вложения
    • "Номер": строка, значение извлекается из тела формализованного вложения. Для неформализованного вложения поле пустое
    • "Сумма": строка, значение извлекается из тела формализованного вложения. Для неформализованного вложения поле пустое
    • "Направление": строка, указывает направление конкретного вложения. Это может быть "входящее" вложение для "исходящего" документа. Например, "подтверждение даты получения" от оператора связи
    • "СсылкаНаHTML": строка, ссылка для скачивания данных html-представления. Используется только для формализованных вложений. Если значение пустое — вернуть представление невозможно
    • "СсылкаНаPDF": строка, ссылка для скачивания данных pdf-представления. Используется только для формализованных вложений. Если значение пустое — вернуть представление невозможно
    • "Редакция": объект:
      • "ДатаВремя": строка в формате "ДД.ММ.ГГГГ ЧЧ.ММ.СС". Указывает на дату и время, в которые была создана редакция вложения
      • "Номер": строка, номер редакции по порядку. Исходная версия имеет номер "1", нумерация непрерывная. Это значит, что если одно и то же вложение записывалось в разных редакциях, у них будут разные номера
    • "Файл": объект:
      • "Имя": строка, имя файла
      • "Ссылка": строка, ссылка для скачивания бинарных данных. Для скачивания используйте HTTP-GET запрос
      • "ДвоичныеДанные": строка в кодировке Bаse64. Используется для отправки содержимого бинарных данных на сервер. Размер не должен превышать 60 Мб
      • "Хеш": строка в Base64. Представляет собой криптографический хеш загруженных бинарных данных
    • "Подпись": массив объектов:
      • "Сертификат": объект, реквизиты владельца сертификата ЭП. Объект возвращается не во всех вызовах:
        • "ФИО": строка, подписант документа
        • "Должность": строка
        • "ИНН": строка, значение соответствует идентификационному номеру налогоплательщика
        • "КодСтраны": строка, код страны в стандарте ISO 3166-1 Alpha-2
        • "ОГРНИП": строка
        • "Название": строка, название организации
        • "Отпечаток": строка, отпечаток
        • "СерийныйНомер": строка, серийный номер
        • "Издатель": строка, издатель сертификата
        • "Квалифицированный": строка со значением "Да"/"Нет"
        • "ДействителенС": дата и время, указывает на начало срока действия сертификата
        • "ДействителенПо": дата и время, указывает на окончание срока действия сертификата
      • "Файл":объект:
        • "Имя": строка, совпадает с именем файла документа, к которому относится. Дополняется строкой «.sgn» для первой подписи, «2.sgn» для второй и последующих
        • "Ссылка": строка, ссылка для скачивания бинарных данных. Для скачивания данных используйте HTTP-GET запрос
        • "ДвоичныеДанные": строка в кодировке Base64. Используется для отправки содержимого бинарных данных на сервер
  • "Событие": массив объектов:
    • "ДатаВремя": строка в формате "ДД.ММ.ГГГГ ЧЧ.ММ.СС". Указывает на дату и время окончания события
    • "Название": строка
    • "Идентификатор": строка, уникальный идентификатор события
    • "Комментарий": строка. Содержит комментарий, который оставлен пользователем или системой
    • "Вложение": массив объектов, описание совпадает с массивом объектов "Документ.Вложение". Содержит вложения, ассоциированные с событием:
      • ...
  • "Этап": массив объектов:
    • "Название": строка, список типов документов
    • "Идентификатор": строка, уникальный идентификатор. Его следует сохранить и передавать на сервер при подготовке и выполнения действия над документом
    • "Служебный": строка со значением "Да"/"Нет"
    • "Вложение": массив объектов, описание совпадает с массивом объектов "Документ.Вложение". Содержит вложения, которые нужно подписать для выполнения этапа:
      • ...
    • "Действие": массив объектов:
      • "Название": строка, содержит название действия из списка допустимых значений
      • "ТребуетПодписания": строка со значением "Да"/"Нет". Признак "Да" означает, что регламент документооборота требует подписать вложения перед завершением этапа, а также указать информацию о подписанте при подготовке этапа
      • "ТребуетКомментария": строка со значением "Да"/"Нет". Признак "Да" означает, что регламент документооборота требует указать комментарий при подготовке к завершению этапа
      • "Сертификат": массив объектов:
        • "ФИО": строка
        • "Должность": строка
        • "ИНН": строка, значение соответствует идентификационному номеру налогоплательщика
        • "КодСтраны": строка, код страны в стандарте ISO 3166-1 Alpha-2
        • "Название": строка
        • "Отпечаток": строка
        • "СерийныйНомер": строка, серийный номер
        • "Издатель": строка, издатель сертификата
        • "Квалифицированный": строка со значением "Да"/"Нет"
        • "ДействителенС": дата и время, указывает на начало срока действия сертификата
        • "ДействителенПо": дата и время, указывает на окончание срока действия сертификата
        • "Ключ": объект:

Такой значительный объем информации, как правило, возвращается только сервером. Для отправки в качестве входящего параметра передается лишь обязательная часть объекта «Документ». Набор обязательных для указания входных параметров, а также возвращаемые сервером значения есть в описании каждого метода.

Поле «Документ.Идентификатор» используется для адресации к последней редакции документа, а «Документ.Редакция.Идентификатор» — для конкретной редакции документа.

В вашей информационной системе не следует хранить идентификаторы участников документооборота и какие-либо ссылки, кроме «Документ.СсылкаДляКонтрагент». Они могут быть изменены оператором связи без уведомления пользователей участников документооборота.

Реквизиты формализованного документа «Дата», «Номер», «Тип», «Подтип», «Версия», «ПодВерсия» и «Название» нужно передавать на сервер все вместе. В полях реквизитов должны быть указаны только правильные значения: если передать только часть реквизитов или с неверно указанными значениями, они будут записаны в систему. Это сделает отображение документов и генерацию pdf-представлений невозможными.