Методы для работы с DraftsBuilder

Подробная спецификация методов показана в Swagger в разделе Черновики и конструктор черновиков (draftsbuilder).

Список доступных методов

Создание DraftsBuilder

Метод: POST CreateDraftsBuilder

Метод создает шаблон черновика. В результате метод вернет идентификатор созданного DraftsBuilder и все его содержимое.

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

  • sender — информация об отправителе;

  • payer — информация о налогоплательщике, организации, за которую отправляется отчет;

  • recipient — информация о получателе отчетности, налоговом органе;

  • builder-type — тип DraftsBuilder;

  • builder-data — данные для указанного типа DraftsBuilder. Состав полей будет отличаться для каждого типа DraftsBuilder.

    Параметры Builder-data в зависимости от типа DraftsBuilder:

    Тип DraftsBuilder fns534-inventory предназначен для формирования черновика описи, чтобы отправить в ИФНС запрошенные документы к входящему требованию или поясняющие документы к отправленному отчету.

    Если входящее требование было получено (или исходный отчет был отправлен) через Контур.Экстерн или API, то заполните только параметр related-document. Черновик описи (ответа на требование) будет сформирован при помощи DraftsBuilder и после отправки превратится в документооборот с типом urn:docflow:fns534-inventory.

    Если исходный отчет отправлен через стороннего оператора ЭДО — то заполните только параметр id-file-osn. Черновик описи будет сформирован при помощи DraftsBuilder и после отправки превратиться в документооборот с типом urn:docflow:fns534-submission.

    • related-document — связанный документ (требование или отчет), отправленный через Контур.Экстерн (или API), на который формируется опись:

      • related-docflow-id — идентификатор связанного документооборота;

      • related-document-id — идентификатор документа в связанном документообороте.

    • id-file-osn — идентификатор файла основания — отчета, отправленного через другого оператора ЭДО. Нужно передать значение поля ИдФайл из xml-файла отчета. Данный идентификатор будет подставлен в поле ИдФайлОсн описи. Например, для отчета НДС поле ИдФайл = «NO_NDS_0007_0007_7381415822111135111_20180810_d229fcba-3747-4ce0-bb6d-7a2f220b07da».

    пример Request Body для создания DraftsBuilder Ответа на требование

Получение DraftsBuilder

Метод: GET GetDraftsBuilder

Метод помогает просмотреть содержимое созданного DraftsBuilder. Метод вернет метаинформацию и текущий статус DraftsBuilder (new, building, finished).

Получение метаинформации DraftsBuilder

Метод: GET GetDraftsBuilderMeta

Метод возвращает только метаинформацию DraftsBuilder без статуса.

Редактирование DraftsBuilder

Метод: PUT UpdateDraftsBuilder

Метод обновляет DraftsBuilder и его метаинформацию на переданные в запросе. Если DraftsBuilder с переданным draftsBuilderId не найден, метод создаст его.

Редактирование метаинформации DraftsBuilder

Метод: PUT UpdateDraftsBuilderMeta

Метод обновляет метаинформацию DraftsBuilder.

Сборка содержимого DraftsBuilder в черновик

Метод: POST BuildDrafts

Чтобы завершить создание черновика описи необходимо привести все переданные данные к установленному формату. Сборку черновиков нужно запускать, когда добавлены все файлы документов, необходимые для отправки отчета в налоговый орган. Если после сборки доложить в черновик новый документ, файл описи станет недействительным.

В результате работы метод вернет информацию о выполнении сборки, которая содержит: идентификатор TaskId, состояние сборки, результат, сообщение об ошибке.

Когда запускается сборка DraftsBuilder, на него ставится блокировка. После успешного завершения сборки нельзя вносить изменения в DraftBuilder. Если необходимо повторно загрузить документы, нужно создать и наполнить новый DraftBuilder.

Важно

Во время сборки документы проходят проверки. Если документы в билдере не корректные, то это не будет являться ошибкой сборки, метод вернет ответ 202 Accepted. Документы с ошибками будут перечислены в модели error-drafts-builder-documents. Данные документы необходимо исправить, повторно создать DraftBuilder, загрузить исправленные файлы и повторить сборку. Если хотя бы один документ корректный — будет создан черновик.

Время сборки зависит от количества и размера файлов. Отследить состояние сборки черновиков можно при помощи метода GetBuildResult по полученному идентификатору задачи TaskId и идентификатору DraftsBuilderId.

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

deferred — флаг асинхронного выполнения запроса. Принимает только значение true. При таком значении запрос будет выполнен асинхронно: будет создана задача, статус выполнения которой можно посмотреть по task-id.

Предупреждение

Значение флага false для синхронного вызова метода устарело и больше не используется в методах API. При таком значении вернется ошибка 400 BadRequest.

Возможные коды ответов

  • 202 Accepted — поставлена задача на сборку DraftsBuilder в черновик, результаты сборки можно получить в задаче по TaskId;

  • 400 BadRequest — указаны некорректные входные данные или передано значение флага асинхронного вызова метода deferred — false.

Проверка статуса сборки

Метод: GET GetBuildResult

По переданным идентификаторам TaskId и DraftsBuilderId метод возвращает:

  • статус сборки;

  • идентификаторы черновиков, в каждом из которых будет находиться xml-файл описи, файлы, сообщение о представительстве (если есть).

Когда сборка завершится, значение статуса будет succeed. Если хотя бы в одном документе произошла ошибка, статус сборки вернется также со значением succeed, а документ будет записан в список ошибочных (error-drafts-builder-documents). Идентификаторы сформированных без ошибок черновиков будут в списке draft-ids.

Удаление DraftsBuilder

Метод: DELETE RemoveDraftsBuilder

Метод удаляет DraftsBuilder и все его содержимое.

Методы для работы с документами DraftsBuilder

Получение списка документов

Метод: GET GetDraftsBuilderDocuments

По идентификатору DraftsBuilderId метод находит список созданных в нем документов, для каждого возвращается: идентификатор документа, идентификатор DraftsBuilder, метаинформация.

Создание документа

Метод: POST CreateDraftsBuilderDocument

Чтобы добавить файлы, необходимо сначала добавить для них контейнер — документ. Вызывайте столько раз, сколько отдельных документов-контейнеров нужно создать.

Параметры Тела запроса (Request Body)

  • builder-data — данные для указанного типа DraftsBuilder. Состав полей будет отличаться для каждого типа DraftsBuilder.

    Параметры Builder-data в зависимости от типа DraftsBuilder:

    • claim-item-number — номер пункта требования, под которым документ указан в требовании в виде 1.ХХ или 2.ХХ;

    • label-for-grouping — метка группы документов для разделения по разным описям.

      Иногда ФНС просит, чтобы налогоплательщик прислал определенные документы в разных описях. По данной метке документы будут разделены в разные черновики с разными файлами описи. В параметре можно передать любую строку, главное — для одной группы указывать одну и ту же строку. Значение null также является меткой.

      Пример: для документа1 параметр не передан, для документа2 значение параметра «группа 1». Документы будут добавлены в разные черновики и будет сформировано две описи. Если параметр не передавать для всех документов, будет создан один черновик и один файл описи (в соответствии с ограничениями на размер и количество файлов).

    • scanned-document-name — название отсканированного документа;

    • type — тип документа. Enums: formalized, scanned, warrant;

    • background-processing — условия для немедленной обработки документа:

      • total-file-count — указание количества файлов в документе. Когда в документ будет добавлено указанное количество файлов, начнется обработка этого документа. Это позволяет перенести шаг подготовки документа на этап загрузки других документов, что существенно ускоряет сборку черновиков при большом количестве или размере файлов в документе.

        После начала обработки документ и его файлы будут заблокированы для изменений.

        Рекомендуется выставлять, если документ уже не будет изменен до запуска сборки DraftsBuilder в черновики. Если хотя бы один документ был подготовлен с неправильными данными, то нужно будет пересоздать DraftsBuilder целиком.

    Пример Request Body для создания документа:

    {
   "builder-data": {
      "claim-item-number": "1.00",
      "label-for-grouping": null,
      "scanned-document-name": "Имя документа.pdf",
      "type": "scanned"
   }
}

Получение информации о документе

Метод: GET GetDraftsBuilderDocument

Метод возвращает всю информацию о документе по его идентификатору.

Получение метаинформации документа

Метод: GET GetDraftsBuilderDocumentMeta

Метод возвращает метаинформацию документа по его идентификатору.

Редактирование документа

Метод: PUT UpdateDraftsBuilderDocument

Метод обновляет документ и его метаинформацию на переданные в запросе. Если документ с переданным documentId в DraftBuilder не найден, метод создаст его.

Редактирование метаинформации документа

Метод: PUT UpdateDraftsBuilderDocumentMeta

Метод обновляет метаинформацию документа.

Удаление документа в DraftBuilder

Метод: DELETE RemoveDraftsBuilderDocument

Метод удаляет документ по его идентификатору в заданном DraftBuilder.

Методы для работы с файлами

Получение списка всех файлов документа

Метод: GET GetDraftsBuilderDocumentFiles

По идентификатору DraftsBuilder и документу в нем метод находит список добавленных файлов.

Создание файла в документе

Метод: POST CreateDraftsBuilderDocumentFile

Метод создает файл в документе. Вызывайте столько раз, сколько файлов нужно положить в документ-контейнер.

Параметры Тела запроса (Request Body):

  • content-id — идентификатор контента в сервисе контентов;

  • base64-signature-content — контент подписи файла в формате base64;

  • meta — метаинформация файла:

    • file-name — полное имя файла;

      Для файла доверенности, который прилагается к банковской гарантии, имя должно соответствовать формату (см. Сведения об уполномоченном представителе Банка (Гаранта) (СвПред). Имя файла документа, подтверждающего полномочия представителя). Иначе метод вернет ошибку 400.

    • builder-data — данные для указанного типа DraftsBuilder. Состав полей будет отличаться для каждого типа DraftsBuilder.

      Параметры builder-data в зависимости от типа DraftsBuilder:

      scanned-file-order — порядковый номер файла в многостраничном документе. Если документ одностраничный, то файл будет один и передавать в параметре «1» не обязательно. Пример использования параметра: «3» будет означать, что данный файл — третья страница в документе.

      Пример Request Body для создания файла:

      {
   "content-id": "1fa932c7-84c2-4f20-acc5-56917ba85aaa",
   "base64-signature-content": "MIINFQYJKoZIhvcNAQcCoIINBjCCDQI...u5yhEBC9oMu/oLG0hL66DVA/09vGdg=",
   "meta": {
      "file-name": "Имя документа.pdf",
      "builder-data": {
         "scanned-file-order": "3"
      }
   }
}

Получение файла по идентификатору

Метод: GET GetDraftsBuilderDocumentFile

Метод возвращает всю информацию о файле по его идентификатору.

Редактирование файла в документе

Метод: PUT UpdateDraftsBuilderDocumentFile

Метод обновляет файл и подпись в документе на переданные в запросе. Если файл с переданным fileId в документе не найден, метод создаст его.

Получение подписи к файлу

Метод: GET GetDraftsBuilderDocumentFileSignatureContent

Метод возвращает подпись контрагента, если она была приложена к файлу, в формате base64.

Получение метаинформации файла

Метод: GET GetDraftsBuilderDocumentFileMeta

Метод возвращает метаинформацию файла.

Редактирование меты файла

Метод: PUT UpdateDraftsBuilderDocumentFileMeta

Метод обновляет метаинформацию файла.

Удаление файла документа

Метод: DELETE RemoveDraftsBuilderDocumentFile

Метод удаляет файл в документе DraftsBilder по его идентификатору.

Получение содержимого файла (deprecated)

Метод: GET GetDraftsBuilderDocumentFileContent

Внимание

Метод устарел. Вместо него используйте Сервис контентов. Идентификатор контента лежит в параметре content-id.

Метод возвращает содержимое файла в формате base64. Максимальный размер возвращаемого контента 32 МБ для тестовой и 64 МБ для рабочей площадки.