GenerateTitleXml

Обобщённый метод генерации. Позволяет изготовить xml-файл любого титула любого типа документа.

POST /GenerateTitleXml
Query Parameters:
 
  • boxId – идентификатор ящика
  • documentTypeNamedId – уникальный строковый идентификатор типа документа
  • documentFunction – строковый идентификатор функции, уникальный в рамках типа документа
  • documentVersion – строковый идентификатор версии, уникальный в рамках функции типа документа
  • titleIndex – числовой идентификатор титула документа
  • disableValidation – отключение валидации полученного XML-документа по XSD-схеме данного типа документа; параметр может отсутствовать
  • editingSettingId – идентификатор настройки редактирования содержимого документа; параметр может отсутствовать
  • letterId – идентификатор сообщения, содержащего соответствующий титул отправителя; параметр может отсутствовать; обязателен при генерации титула получателя (titleIndex > 0)
  • documentId – идентификатор документа, содержащего соответствующий титул отправителя; параметр может отсутствовать; обязателен при генерации титула получателя (titleIndex > 0)
Request Headers:
 
Status Codes:
  • 200 OK – операция успешно завершена
  • 400 Bad Request – данные в запросе имеют неверный формат или отсутствуют обязательные параметры
  • 401 Unauthorized – в запросе отсутствует HTTP-заголовок Authorization, или в этом заголовке содержатся некорректные авторизационные данные
  • 402 Payment Required – закончилась подписка на API
  • 403 Forbidden – у пользователя нет права для работы с указанным типом документа
  • 405 Method Not Allowed – используется неподходящий HTTP-метод
  • 500 Internal Server Error – при обработке запроса возникла непредвиденная ошибка

В теле запроса должен содержаться упрощенный XML-файл, соответствующий XSD-схеме контракта для генерации титула. XSD-схема контракта, необходимого для генерации титула, может быть получена с помощью ссылки, доступной в поле UserDataXsdUrl контракта DocumentTitle, который можно получить с помощью метода-справочника GetDocumentTypes.

В теле ответа содержится сгенерированный XML-файл титула, построенный на основании данных из запроса. Файл изготавливается в соответствии с XSD-схемой соответствующего титула документа.

Имя файла сгенерированного титула возвращается в стандартном HTTP-заголовке Content-Disposition.

Как использовать. Генерация титула отправителя (первого титула документа):

В качестве примера рассмотрим генерацию счёта-фактуры формата приказа ФНС №820. Для этого с помощью метода GetDocumentTypes найдем интересующий тип и версию:

"DocumentTypes": [
   {
       "Name": "Invoice",
       "Title": "Счет-фактура",
       "SupportedDocflows": [
           "External"
       ],
       "RequiresFnsRegistration": true,
       "Functions": [
           {
               "Name": "default",
               "Versions": [
                   {
                       "Version": "utd820_05_01_01",
                       "SupportsContentPatching": true,
                       "SupportsEncrypting": true,
                       "SupportsPredefinedRecipientTitle": false,
                       "IsActual": true,
                       "Workflows": [
                           {
                               "Id": 10,
                               "IsDefault": true
                           }
                       ],
                       "Titles": [
                           {
                               "Index": 0,
                               "IsFormal": true,
                               "XsdUrl": "/GetContent?typeNamedId=Invoice&function=default&version=utd820_05_01_01&titleIndex=0&contentType=TitleXsd",
                               "UserDataXsdUrl": "/GetContent?typeNamedId=Invoice&function=default&version=utd820_05_01_01&titleIndex=0&contentType=UserContractXsd",
                               "SignerInfo": {
                                   "SignerType": "ExtendedSigner",
                                   "ExtendedDocumentTitleType": "UtdSeller"
                               },
                               "MetadataItems": [
                                   "..."
                               ],
                               "EncryptedMetadataItems": [
                                   "..."
                               ]
                           }
                       ]
                   }
               ]
           }
       ]
   }
]

Для простоты примера из ответа убраны другие типы, функции, версии, и информация о метаданных. Главное, что нужно взять из этой информации:

  • documentTypeNamedId: «Invoice» (имя типа документа);
  • documentFunction: «default» (у счёта-фактуры функция единственная);
  • documentVersion: «utd820_05_01_01» (интересующая нас версия формата приказа №820);
  • titleIndex: «0» (счёт-фактура — однотитульный документ, вторая сторона (получатель) свой титул не отправляет).

Теперь нужно подготовить контент для титула. Титул — это xml-файл, соответствующий xsd-схеме. Часть данных в титуле может быть заполнена только пользователем — это информация о товарах, услугах и т.д. А часть данных может быть заполнена автоматически на основании формата и информации в Диадоке. Например, заполнить реквизиты организации продавца и покупателя по идентификатору ящика, установить значения КНД, версии формата, версии программы и т.д. Для упрощения генерации, Диадок позволяет заполнить только «пользовательский» xml-файл, он же UserDataXml. На базе UserDataXml метод генерации сформирует основной титул, дополнив его всеми необходимыми данными согласно xsd-схеме.

Общая схема работы:

../_images/diadoc-api-generate-xml-schema11.png

Выбор, как формировать UserDataXml, остаётся за разработчиком интеграционного решения.

Один из путей — это кодогенерация из xsd-схемы упрощённого титула. Ссылка на схему находится в поле UserDataXsdUrl из выдачи GetDocumentTypes выше.

В качестве примера, в C# SDK для всех версий формата приказа №820 есть пример кодогенерации.

Кодогенерация осуществлена инструментом xsd.exe.

Чтобы воспользоваться ей в C#-клиенте, достаточно заполнить объект UniversalTransferDocument для титула отправителя (или UniversalTransferDocumentBuyerTitle для титула получателя) и затем сериализовать в XML.

Итого, имея идентификаторы типа, функции, версии, порядкового номера титула, а также пользовательский контент, можем получить сам титул счёта-фактуры.

Пример http-запроса:

POST /GenerateTitleXml?boxId=a96be310-0982-461a-8b2a-91d198b7861c&documentTypeNamedId=Invoice&documentFunction=default&documentVersion=utd820_05_01_01&titleIndex=0 HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: DiadocAuth ddauth_api_client_id={{ключ разработчика}}, ddauth_token={{авторизационный токен}}
Content-Type: application/xml; charset=utf-8

Пример UserDataXml (тело запроса):

<?xml version="1.0" encoding="utf-8"?>
<UniversalTransferDocument Function="СЧФ"
                           DocumentDate="01.08.2019"
                           DocumentNumber="140"
                           DocumentCreator="1"
                           DocumentCreatorBase="1"
                           CircumFormatInvoice="1"
                           Currency="643">
    <Sellers>
        <Seller>
            <OrganizationDetails OrgType="2"
                                 Inn="114500647890"
                                 FnsParticipantId="2BM-participantId1"
                                 OrgName="ИП Продавец Иван Иванович">
                <Address>
                    <RussianAddress Region="02"/>
                </Address>
            </OrganizationDetails>
        </Seller>
    </Sellers>
    <Buyers>
        <Buyer>
            <OrganizationReference OrgType="2"
                                   BoxId="74ef3a00-c625-3ef0-9b50-65bf7f96b9ae"/>
        </Buyer>
    </Buyers>
    <Table TotalWithVatExcluded="0" Vat="0" Total="0">
        <Item Product="Товарная позиция"
              Unit="796"
              Quantity="0"
              Price="0"
              TaxRate="без НДС"
              SubtotalWithVatExcluded="0"
              Vat="0"
              Subtotal="0"/>
    </Table>
    <Signers>
        <SignerDetails Inn="123456789047"
                       LastName="Подписантов"
                       FirstName="Иван"
                       MiddleName="Иванович"
                       RegistrationCertificate="1"
                       SignerPowers="0"
                       SignerType="3"
                       SignerStatus="1"
                       SignerPowersBase="Должностные обязанности"/>
    </Signers>
</UniversalTransferDocument>

Пример получившегося титула (тело ответа):

HTTP/1.1 200 OK

<?xml version="1.0" encoding="windows-1251"?>
<Файл ИдФайл="ON_NSCHFDOPPR_2BM-participantId2_2BM-participantId1_20190822_c2b7d7f7-7f3b-467d-ac59-3f3815980a4d" ВерсФорм="5.01" ВерсПрог="Diadoc 1.0">
    <СвУчДокОбор ИдОтпр="2BM-participantId1" ИдПол="2BM-participantId2">
        <СвОЭДОтпр ИННЮЛ="6663003127" ИдЭДО="2BM" НаимОрг="АО &quot;ПФ &quot;СКБ Контур&quot;" />
    </СвУчДокОбор>
    <Документ КНД="1115131" ВремИнфПр="13.28.01" ДатаИнфПр="22.08.2019" НаимЭконСубСост="1" Функция="СЧФ" ОснДоверОргСост="1">
        <СвСчФакт НомерСчФ="140" ДатаСчФ="01.08.2019" КодОКВ="643">
            <СвПрод>
                <ИдСв>
                    <СвИП ИННФЛ="114500647890">
                        <ФИО Фамилия="Продавец" Имя="Иван" Отчество="Иванович" />
                    </СвИП>
                </ИдСв>
                <Адрес>
                    <АдрРФ КодРегион="02" />
                </Адрес>
            </СвПрод>
            <СвПокуп>
                <ИдСв>
                    <СвИП ИННФЛ="114500647890">
                        <ФИО Фамилия="Покупатель" Имя="Иван" Отчество="Иванович" />
                    </СвИП>
                </ИдСв>
                <Адрес>
                    <АдрРФ КодРегион="02" />
                </Адрес>
            </СвПокуп>
            <ДопСвФХЖ1 НаимОКВ="Российский рубль" ОбстФормСЧФ="1" />
        </СвСчФакт>
        <ТаблСчФакт>
            <СведТов НомСтр="1" НаимТов="Товарная позиция" ОКЕИ_Тов="796" КолТов="0" ЦенаТов="0" СтТовБезНДС="0.00" НалСт="без НДС" СтТовУчНал="0.00">
                <Акциз>
                    <БезАкциз>без акциза
                    </БезАкциз>
                </Акциз>
                <СумНал>
                    <СумНал>0.00</СумНал>
                </СумНал>
                <ДопСведТов НаимЕдИзм="шт" />
            </СведТов>
            <ВсегоОпл СтТовБезНДСВсего="0.00" СтТовУчНалВсего="0.00">
                <СумНалВсего>
                    <СумНал>0.00</СумНал>
                </СумНалВсего>
            </ВсегоОпл>
        </ТаблСчФакт>
        <Подписант ОснПолн="Должностные обязанности" ОблПолн="0" Статус="1">
            <ФЛ ИННФЛ="123456789047">
                <ФИО Фамилия="Подписантов" Имя="Иван" Отчество="Иванович" />
            </ФЛ>
        </Подписант>
    </Документ>
</Файл>

Генерация титула с настройкой редактирования

В случае, если указан параметр editingSettingId, то валидация сгенерированного файла будет выполняться по XSD-схеме, соответствующей данной настройке редактирования. Например, это означает, что если настройка редактирования позволяет не указывать какой-либо атрибут, то с помощью данного метода возможносгенерировать xml-файл, в котором будет отсутствовать данный атрибут. При этом валидация будет осуществлятся так, как если бы данный атрибут был опциональным по XSD-схеме.

Генерация титулов последующих участников

В случае, если тип документа содержит более одного титула, и нужно сгенерировать титулы для последующих участников (т.е. когда titleIndex > 0), то сценарий аналогичен примеру выше, за исключением дополнительных параметров в запросе.

В большинстве случаев в контенте последующих титулов нужна информация из предыдущих, поэтому в запрос нужно передать идентификаторы уже существующего в Диадоке документа (letterId+documentId).