Как отправить и получить товарную накладную ТОРГ-12 в рекомендованном ФНС формате¶

Сценарий работы с товарной накладной ТОРГ-12¶

Продавец формирует файл титула продавца, подписывает и направляет покупателю.
Покупатель получает товарную накладную, подписанную и отправленную продавцом;
Покупатель формирует файл титула покупателя, подписывает своей ЭП и отправляет в адрес продавца.

Примечание

Более подробно о порядке обмена электронными накладными между компаниями можно почитать на сайте

Формирование файла титула продавца для товарной накладной ТОРГ-12¶

Cгенерировать файл титула, соответствущий утвержденному формату, можно с помощью метода GenerateTitleXml. Для этого передайте в метод следующие параметры:

documentTypeNamedId — тип документа;

documentFunction — функция документа;

documentVersion — версия документа;

titleIndex — идентификатор титула документа.

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

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

Ниже приведено тело ответа метода GetDocumentTypes. Для упрощения из него удалены другие типы, функции, версии и информация о метаданных.

{
  "Name": "XmlTorg12",
  "Title": "Накладная",
  "SupportedDocflows": [
    1,
    0
  ],
  "RequiresFnsRegistration": false,
  "Functions": [
    {
      "Name": "default",
      "Versions": [
        {
          "Version": "tovtorg_05_02_01",
          "SupportsContentPatching": true,
          "SupportsEncrypting": false,
          "SupportsPredefinedRecipientTitle": false,
          "SupportsAmendmentRequest": false,
          "Titles": [
            {
              "Index": 0,
              "IsFormal": true,
              "XsdUrl": "/GetContent?typeNamedId=XmlTorg12&function=default&version=tovtorg_05_02_01&titleIndex=0&contentType=TitleXsd",
              "UserDataXsdUrl": "/GetContent?typeNamedId=XmlTorg12&function=default&version=tovtorg_05_02_01&titleIndex=0&contentType=UserContractXsd",
              "SignerInfo": {
                "SignerType": 2,
                "ExtendedDocumentTitleType": 4
              },
              "MetadataItems": [],
              "EncryptedMetadataItems": []
            },
            {
              "Index": 1,
              "IsFormal": true,
              "XsdUrl": "/GetContent?typeNamedId=XmlTorg12&function=default&version=tovtorg_05_02_01&titleIndex=1&contentType=TitleXsd",
              "UserDataXsdUrl": "/GetContent?typeNamedId=XmlTorg12&function=default&version=tovtorg_05_02_01&titleIndex=1&contentType=UserContractXsd",
              "SignerInfo": {
                "SignerType": 2,
                "ExtendedDocumentTitleType": 5
              },
              "MetadataItems": [],
              "EncryptedMetadataItems": []
            }
          ],
          "IsActual": true,
          "Workflows": [
            {
              "Id": 3,
              "IsDefault": true
            }
          ]
        }
      ]
    }
  ]
}

documentTypeNamedId = XmlTorg12 — имя типа документа,
documentFunction = default — функция документа,
documentVersion = tovtorg_05_02_01 — версия формата,
titleIndex = 0 — титул продавца,
UserDataXsdUrl — URL-путь метода, возвращающего файл XSD-схемы контракта для генерации титула с помощью метода генерации.

Отправка файла титула продавца для товарной накладной ТОРГ-12¶

Полученный XML-файл титула продавца можно отправить с помощью метода PostMessage.

В теле запроса метода передайте структуру MessageToPost, заполненную следующими данными:

Для этого подготовьте структуру MessageToPost:

в поле FromBoxId укажите идентификатор ящика отправителя;
в поле ToBoxId укажите идентификатор ящика получателя;
для передачи XML-файла титула отправителя акта сверки используйте вложенную структуру DocumentAttachment:
- XML-файл передайте в поле Content структуры SignedContent, подпись — в поле Signature;
- TypeNamedId=XmlTorg12;
- Function=default;
- Version=tovtorg_05_02_01.

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

"FromBoxId": "db32772b-9256-49a8-a133-fda593fda38a",
"ToBoxId": "13254c42-b4f7-4fd3-3324-0094aeb0f15a",
"DocumentAttachments": [
        {
            "SignedContent":
            {
                "Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+",        //контент xml-файла в кодировке base-64
                "Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW",       //контент файла подписи в кодировке base-64
            },
            "TypeNamedId": "XmlTorg12",
            "Function": "default",
            "Version": "tovtorg_05_02_01"
        }
    ]
}

После отправки в теле ответа будет содержаться отправленное сообщение, сериализованное в протобуфер Message.

Все дальнейшие действия происходят на стороне получателя.

Поиск товарной накладной ТОРГ-12¶

Чтобы найти все входящие акты ТОРГ-2, которые нужно обработать, используйте метод GetDocuments:

в поле boxId укажите идентификатор ящика, в котором нужно найти входящие документы;
в поле filterCategory укажите статус и тип документа: XmlTorg12.InboundNotFinished.

Пример запроса на получение товарной накладной ТОРГ-12 выглядит следующим образом:

GET /V3/GetDocuments?filterCategory=XmlTorg12.InboundNotFinished&boxId=db32772b-9256-49a8-a133-fda593fda38a HTTP/1.1
Host: diadoc-api.kontur.ru
Accept: application/json
Content-Type: application/json charset=utf-8
Authorization: DiadocAuth ddauth_api_client_id={{ключ разработчика}}, ddauth_token={{авторизационный токен}}

В теле ответа вернется список документов в виде структуры DocumentList с вложенной структурой Document. Чтобы получить документы, потребуются значения полей MessageId и EntityId.

Получение товарной накладной ТОРГ-12¶

Найденный документ можно получить с помощью метода GetMessage. В запросе передайте параметры, вернувшиеся в теле ответа метода GetDocuments: boxId, messageId, entityId.

Пример запроса на получение товарной накладной ТОРГ-12:

GET /V3/GetMessage?messageId=bbcedb0d-ce34-4e0d-b321-3f600c920935&entityId=30cf2c07-7297-4d48-bc6f-ca7a80e2cf95&boxId=db32772b-9256-49a8-a133-fda593fda38a HTTP/1.1
Host: diadoc-api.kontur.ru
Accept: application/json
Content-Type: application/json charset=utf-8
Authorization: DiadocAuth ddauth_api_client_id={{ключ разработчика}}, ddauth_token={{авторизационный токен}}

Пример структуры товарной накладной ТОРГ-12 XmlTorg12 в теле ответа:

{
    "EntityType": "Attachment",
    "EntityId": "654ac483-0dd4-4085-b70f-565c8b754e10",
    "Content": "lores ipsum",
    "AttachmentType": "XmlTorg12",
    "FileName": "ON_NSCHFDOPPR_2BM-7750370234-4012052808304878702630000000000_2BM_20150927_324c290e-f049-4906-baac-1ddcd7f3c2ff.xml",
    "NeedRecipientSignature": true,
    "SignerBoxId": "",
    "NotDeliveredEventId": "",
    "RawCreationDate": 635789700936777240,
    "SignerDepartmentId": "",
    "NeedReceipt": false,
    "IsApprovementSignature": false,
    "IsEncryptedContent": false
}

Формирование файла титула покупателя для товарной накладной ТОРГ-12¶

Генерация титула покупателя с помощью метода GenerateTitleXml выполняется аналогично титулу продавца.

Тип, функция и версия файла такие же, как у титула продавца, отличается только номер титула:

documentTypeNamedId = XmlTorg12,
documentFunction = default,
documentVersion = tovtorg_05_02_01,
titleIndex = 1 — титул покупателя.

Отправка файла титула покупателя для товарной накладной ТОРГ-12¶

Отправить сформированный титул покупателя можно с помощью метода PostMessagePatch.

В теле запроса метода передайте структуру MessagePatchToPost, заполненную следующими данными:

в поле BoxId укажите идентификатор ящика, в котором находится исходное сообщение;
в поле MessageId укажите идентификатор сообщения, к которому относится дополнение;
чтобы передать XML-файла титула, используйте структуру RecipientTitleAttachment:
- ParentEntityId — идентификатор титула продавца;
- XML-файл нужно передать в поле Content вложенной структуры SignedContent, подпись — в поле Signature;

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

"BoxId": "db32772b-9256-49a8-a133-fda593fda38a",
"MessageId": "bbcedb0d-ce34-4e0d-b321-3f600c920935",
"RecipientTitles":
[
    {
        "ParentEntityId":"30cf2c07-7297-4d48-bc6f-ca7a80e2cf95",
        "SignedContent":
        {
            "Content": "PD94bWwgdmVyc2l...LDQudC7Pg==",        //контент xml-файла в кодировке base-64
            "Signature": "MIIN5QYJKoZIhvc...KsTM6zixgz"        //контент файла подписи в кодировке base-64
        }
    }
]
}

После отправки в теле ответа будет содержаться отправленное дополнение, сериализованное в протобуфер MessagePatch.