код boxid что это
Доставка
Источник данных
Коннектор может работать с четырьмя типами источников файлов:
Настройка серверов включает в себя специальные параметры (например, тип подключения, тип авторизации, путь к рабочей папке) и общие параметры для каждого типа источника файлов: группировка документов в пакеты и их связывание.
Чтобы отправить документы в одном письме, нужно сгруппировать их любым из способов:
Ниже на схемах приведены примеры группировки файлов в письма при установке уровня вложенности «0» или «1».
Схема 1. Пример группировки файлов в письма с уровнем вложенности «0».
Схема 2. Пример группировки файлов в письма с уровнем вложенности «1».
Типы и форматы документов
Коннектор позволяет отправлять любые типы документов, которые поддерживает Диадок.
Основные типы документов:
Поддерживаемые форматы формализованных документов, которые закреплены законодательством: 820@, 736@, 551@, 552@.
Некоторые неформализованные документы требуют дополнительных данных, таких как: дата, номер, сумма. Их можно указать в имени исходного файла документа.
Если учетная система не может выгрузить счета-фактуры, накладные, акты или УПД в формате установленном ФНС или в формате, который необходим для отправки в электронном виде (произвольный PDF или XML), то можно воспользоваться функцией преобразования документов. Поддерживаемые форматы исходных файлов, для которых применима функция преобразования:
Возможен вариант сложного преобразования, когда из одного файла требуется сформировать несколько файлов.
Эти настройки выполняются в индивидуальном порядке через менеджера.
Загрузка документов в Диадок
Для отправки документа потребуется задать правила маршрутизации для определения:
Исходящие для последующей отправки и подписи.
Подписать и оправить документы получателям. Потребуется обязательная авторизация пользователя в коннекторе под сертификатом.
Получатель документа может быть определен по:
При маршрутизации по паре ИНН-КПП применяется следующий порядок поиска организации в Диадоке:
Поиск по КПП одновременно происходит как по реквизитам ящика организации, так и по реквизитам подразделений ящика организации.
Отправка документов в роуминговые ящики осуществляется в головное подразделение.
Исключение составляют документы с типом «Приглашение». Для них нет проверок на наличие получателя в списке контрагентов.
Более гибкие настройки по маршрутизации документов представляет «файл маршрутизации». Это текстовый файл, который содержит строки, состоящие из пары ключ–значение, разделенные пробелами. Кодировка файла: UTF-8 или UTF-8 (без BOM). Если указан ключ, то должно быть указано значение.
Файл маршрутизации определяется по имени, которое удовлетворяет заданному регулярному выражению (подробнее смотрите в разделе «Использование регулярных выражений» ). Файл маршрутизации не должен располагаться в корне рабочей папки. Его можно разместить в подпапке вместе с отправляемыми документами или на уровень выше.
Идентификатор участника ЭДО
Идентификатор, или ID, — это уникальный номер. Идентификатор участника ЭДО оператор электронного документооборота присваивает пользователям системы. Идентификационный номер выдается организации по ИНН-КПП. Компании с одинаковым ИНН и разными КПП будут работать с электронными документами под своими идентификаторами.
Что такое идентификатор
Идентификатор участника ЭДО состоит из комбинации цифр и латинских букв разного регистра.
Первые три символа в номере — это ID оператора электронного документооборота. Набор последующих знаков помогает распознавать пользователей ЭДО.
Как определить оператора ЭДО по идентификатору? Если вы хотите узнать, какой провайдер у контрагента, обратите внимание на первую часть идентификационного номера. Найдите на сайте ФНС России список доверенных операторов юридически значимого электронного документооборота. В списке приведены основные сведения об операторах, в том числе идентификаторы ОЭД. Зная идентификатор участника ЭДО, вы легко определите оператора по первым трем символам.
Так, ID участника ЭДО для клиентов оператора СКБ Контур будет начинаться с 2ВМ.
Зачем нужен идентификатор
Для обмена счетами-фактурами и другими формализованными документами организации необходимо получить идентификатор участника ЭДО. В xml-файлах электронных документов должны быть заполнены поля с номерами отправителя и получателя. Использование уникальных кодов дает возможность ФНС и операторам ЭДО определить организацию в своих системах.
Также идентификаторы участников нужны для настройки роуминга между организациями — клиентами разных операторов ЭДО. В процессе подключения оператору понадобится узнать идентификатор контрагента, с которым абонент хочет наладить связь.
Как получить идентификатор
При регистрации в системе ЭДО новый пользователь подписывает заявление об участии в электронном документообороте. В Контур.Диадоке оно создается, когда организация отправляет первый формализованный документ. Пользователю достаточно проверить реквизиты и подтвердить свое намерение подать заявление.
На основе заявления об ЭДО оператор формирует информационное сообщение, в котором и указывает уникальный код участника — идентификатор ЭДО. Вместе с реквизитами организации данные передаются в налоговую, и новый пользователь может начать работу с электронными формализованными документами.
Где посмотреть в Диадоке
Чтобы узнать идентификатор участника ЭДО в Контур.Диадоке, зайдите в веб-интерфейс сервиса. Откройте меню «Настройки». Вы сразу же увидите идентификатор участника ЭДО (GUID).
Если вы перейдете в раздел «Реквизиты организации», тоже сможете посмотреть идентификационный номер своей организации.
Как узнать идентификатор ЭДО контрагента
Откройте вкладку «Контрагенты» в веб-интерфейсе Контур.Диадока. Через поиск найдите бизнес-партнера, идентификатор которого вы хотите узнать. Нажмите на активную ссылку в наименовании организации. Откроется новое окно в виде карточки контрагента. Кликните на ссылку со словом ID в первой строчке.
Подключиться к Диадоку, чтобы использовать все преимущества ЭДО
Где взять BoxId в GUID формате для УПД по 820 приказу? #576
Comments
Edward72 commented Oct 31, 2019
В теле запроса GenerateTitleXml нужно заполнять BoxID продавца и покупателя. Формат требуется GUID. API Диадока позволяет нам получить идентификатор ящика вызовом GetBox. Но в ответе мы получаем идентификатор вида «97be5d3704394d62bf40442dcb2489b8@diadoc.ru», что совсем не похоже на GUID. Вопрос: где брать идентификатор ящика в GUID формате?
The text was updated successfully, but these errors were encountered:
OlgaPetushina commented Nov 1, 2019
Edward72 commented Nov 5, 2019
В части получения идентификатора ящика вы правы. Это я неправильно указал метод, конечно же GetOrganization и далее по списку ящиков получаем их идентификаторы (непонятно только, зачем список, если ящиков всегда один). А вот в части преобразовать самостоятельно можно подискутировать. Да это не сложно, да, я это в итоге так и сделал. Но возникает вопрос о единообразии данных в API Диадока. Почему в одном случае BoxId должен быть такого вида «97be5d3704394d62bf40442dcb2489b8@diadoc.ru», а в другом «97be5d37-0439-4d62-bf40-442dcb2489b8»? Уважаемые разработчики, объясните вашу логику!
OlgaPetushina commented Nov 5, 2019
@Edward72 boxid возвращается в таком виде в целях обратной совместимости. Мы планируем поднять версию метода и возвращать BoxId как guid. Сроков нет пока.
Edward72 commented Nov 5, 2019
Ок. Поясните тогда по списку ящиков. Зачем в структуре Organization ящики представлены в виде списка? Бывают ли ситуации когда их больше одного?
OlgaPetushina commented Nov 5, 2019
Edward72 commented Nov 5, 2019
alogicman commented Nov 5, 2019
Ок. Поясните тогда по списку ящиков. Зачем в структуре Organization ящики представлены в виде списка? Бывают ли ситуации когда их больше одного?
Это опять для обратной совместимости: когда-то давно у одной организации могло быть несколько ящиков. Сейчас понятия организации и ящика фактически смешались, так как их отношение 1:1 — у организации ровно один ящик.
Когда-нибудь мы приведем все в единообразное состояние — везде будет использоваться нормальный boxId, а у организации не будет массива ящиков 🙂
Edward72 commented Nov 6, 2019
никто не ответил. С каким контрагентом мне работать? Если их два, с одинаковым ИНН/КПП?
NataliaShumikhina commented Nov 6, 2019
Никаких противоположных мнений нет. Организация=Ящик=уникальная связка ИНН-КПП-Id участника ЭДО-признак тестовая/роуминговая/реальная
Это всё нормальные ситуации.
Если вы получили в ответе несколько ящиков, то вы сами выбираете, с каким работать:
Edward72 commented Nov 7, 2019
i82 commented Nov 7, 2019
Если вам требуются технические консультации, я могу предложить оплатить платные консультации. Вы будете получать ответ оперативнее с учётом всего вашего контекста от выделенного специалиста. Если это потребуется, обратитесь к вашему менеджеру.
Edward72 commented Feb 13, 2020
Опять про ящики. Есть контрагент. Подразделение ПАО «Ростелеком» ИНН 7707049388 КПП 860143001. GetOrganization ищем по ИНН/КПП, находим, отправляем приглашение. И что? И ничего. А почему? А потому что, этот ящик они когда-то использовали, но потом все поменялось. У них теперь другой ящик. А старый остался висеть, непонятно зачем. А новый ящик где? А внутри ящика другого контрагента, у которого КПП 66854300. Это Макрорегиональный филиал «Урал». Но господа, в договоре с этим контрагентом КПП 66854300 не прописан! У нас есть КПП головы 770545001 и собственно грузополучателя КПП 860143001. Руками конечно все можно настроить, но мы говорим об интеграции. Итак, есть ИНН/КПП головы и грузополучателя. Ищем GetOrganization по ИНН/КПП грузополучателя, находим, приглашаем и тишина. Что дальше? Ок. Ищем только по ИНН. Находим 66 организаций! Куда дальше? Мне что, нужно лепить в программе костыль, где указывать, что в Диадоке работаем через конкретный КПП? Ок. Допустим. Следующий вопрос. В поддержке мне объяснили, что направляя формализованные документы с КПП грузополучателя в ящик филиала «Урал», документы перенаправятся в ящик нашего потребителя. А что делать с неформализованными документами? Куда их слать? На деревню дедушке? Когда наконец логику работы с Диадоком приведут в нормальный вид?
i82 commented Feb 13, 2020
Структуру филиалов каждая компания формирует самостоятельно, как и принимает решения об удалении ящиков. Мы не можем гарантировать работу Ростелекома, информация о том, куда следует отправлять документы вам необходимо согласовать с контрагентом.
Маршрутизация неформализованных документов не производится т.к. Диадок не может определить из контента, куда его требуется смаршрутизировать. Для маршрутизации таких документов нужно явно указывать подразделение получателя при отправке.
Edward72 commented Feb 13, 2020
Речь идет не о структуре филиалов. А о том, что Диадок не позволяет работать с филиалами, не заморачиваясь с той самой структурой филиалов. Мне то какое должно быть дело до их структуры? Сегодня она одна, завтра другая. Есть ИНН/КПП получателя. Все. Больше ничего не должно быть нужно. И слова «Диадок не может», которые звучат из уст разработчиков того самого Диадока, выглядят как минимум неубедительно. Как максисмум: типа, мы тут сделали кое как, пользуйте как хотите и как можете, мы ничего переделывать не будем.
i82 commented Feb 13, 2020
ToDepartmentId в методе отправки.
В апи Диадок предоставляет данные как есть, без дополнительной логической обработки, для более предсказуемого поведения и вашей возможности для гибкой настройки интеграции. Компания Ростелеком проинформирована о том, что выбранное ими решение может быть неудобным для их контрагентов без относительно интерфейса работы с ними.
Edward72 commented Feb 13, 2020
Что еще можно было услышать? Виноваты не мы, виноваты сами пользователи. А наша система самая офигенская, что-то допиливать, изменять в ней нет необходимости. Платите деньги за использование и пользуйте как есть. А сделать элементарное, поиск по ИНН/КПП в своей базе (базе Диадока) в том числе и подразделений ну никак. Еще расскажите мне про «техническую невозможность».
i82 commented Feb 13, 2020
Попрошу вас воздержаться от оценочных суждений.
Это пожелание по доработке тоже зафиксировал, но в ближайшие задачи она не попадёт
Edward72 commented Feb 13, 2020
Ваш запрос в бэклоге. Если вы хотите поднять приоритет, обратитесь к вашему менеджеру, он сможет это сделать
GetDocuments¶
Элементы в списке DocumentList.Documents идут в порядке возрастания меток времени (поля Document.TimestampTicks). В поле DocumentList.TotalCount указывается общее количество документов, удовлетворяющих запросу.
В массиве DocumentList.Documents содержится не более 1000 элементов; для получения остальных документов нужно вызывать метод GetDocuments с теми же параметрами, меняя значение afterIndexKey.
Первая часть этой строки задает тип документа и может следующие значения:
| Вариант | Описание | Примечание |
|---|---|---|
| Строковый идентификатор любого доступного в организации типа (см. поле TypeNamedId ) | Например, Invoice, XmlAcceptanceCertificate, Nonformalized и т.п. | |
| Any | Аггрегированный запрос для всех документов в ящике без учета по типу | |
| AnyInvoiceDocumentType | Аггрегированный запрос только для типов Invoice, InvoiceRevision, InvoiceCorrection, InvoiceCorrectionRevision | более не поддерживается и не рекомендуется к использованию |
| AnyBilateralDocumentType | Аггрегированный запрос только для типов Nonformalized, Torg12, AcceptanceCertificate, XmlTorg12, XmlAcceptanceCertificate, TrustConnectionRequest, PriceList, PriceListAgreement, CertificateRegistry, ReconciliationAct, Contract, Torg13 | более не поддерживается и не рекомендуется к использованию |
| AnyUnilateralDocumentType | Аггрегированный запрос только для типов ProformaInvoice, ServiceDetails | более не поддерживается и не рекомендуется к использованию |
Строка DocumentClass задает класс документа и может принимать следующие значения:
| Вариант | Описание |
|---|---|
| Inbound | Только входящие |
| Outbound | Только исходящие |
| Internal | Только внутренние |
| Proxy | Только документы, переданные через промежуточного получателя |
Строка DocumentStatus задает статус документа и может принимать следующие значения:
| Вариант | Описание |
|---|---|
| Пустое значение | Любой документ указанного класса Class |
| NotRead | Документ не прочитан |
| NoRecipientSignatureRequest | Документ без запроса ответной подписи |
| WaitingForRecipientSignature | Документ в ожидании ответной подписи |
| WithRecipientSignature | Документ с ответной подписью |
| WithSenderSignature | Документ с подписью отправителя |
| RecipientSignatureRequestRejected | Документ с отказом от формирования ответной подписи |
| WaitingForSenderSignature | Документ, требующий подписания и отправки |
| InvalidSenderSignature | Документ с невалидной подписью отправителя, требующий повторного подписания и отправки |
| InvalidRecipientSignature | Документ с невалидной подписью получателя, требующий повторного подписания и отправки |
| Approved | Согласованный документ |
| Disapproved | Документ с отказом согласования |
| WaitingForResolution | Документ, находящийся на согласовании или подписи |
| SignatureRequestRejected | Документ с отказом в запросе подписи сотруднику |
| Finished | Документ с завершенным документооборотом |
| HaveToCreateReceipt | Требуется подписать извещение о получении |
| NotFinished | Документ с незавершенным Документооборотом |
| InvoiceAmendmentRequested | Документ, по которому было запрошено уточнение |
| RevocationIsRequestedByMe | Документ, по которому было запрошено аннулирование |
| RequestsMyRevocation | Документ, по которому контрагент запросил аннулирование |
| RevocationAccepted | Аннулированный документ |
| RevocationRejected | Документ, запрос на аннулирование которого был отклонен |
| RevocationApproved | Документ, запрос на аннулирование которого был согласован |
| RevocationDisapproved | Документ с отказом согласования запроса на аннулирование |
| WaitingForRevocationApprovement | Документ, находящийся на согласовании запроса аннулирования |
| NotRevoked | Неаннулированный документ |
| WaitingForProxySignature | Документ в ожидании подписи промежуточного получателя |
| WithProxySignature | Документ с подписью промежуточного получателя |
| InvalidProxySignature | Документ с невалидной подписью промежуточного получателя, требующий повторного подписания и отправки |
| ProxySignatureRejected | Документ с отказом от формирования подписи промежуточным получателем |
| WaitingForInvoiceReceipt | Документ в ожидании получения извещения о получении счета-фактуры |
| WaitingForReceipt | Документ в ожидании получения извещения о получении |
| RequestsMySignature | Документ, по которому контрагент запросил подпись |
| RoamingNotificationError | Документ с ошибкой доставки в роуминге |
Примеры строки filterCategory:
Необязательный параметр counteragentBoxId позволяет ограничить выдачу только теми документами, у которых идентификатор ящика контрагента совпадает с counteragentBoxId.
Необязательные параметры timestampFromTicks и timestampToTicks позволяют задать интервал времени, в котором осуществляется поиск.
Необязательные параметры fromDocumentDate и toDocumentDate также позволяют задать интервал времени, в котором осуществляется поиск.
Однако при этом фильтрация списка документов производится по дате формирования документа в учетной системе (реквизиту самого документа), а не по метке времени, связанной с загрузкой документа в ящик Диадока.
Если какой-то параметр отсутствует в запросе, то его значение неявно принимается равным +/- бесконечности. В выдачу метода GetDocuments попадают только те документы, у которых заполнен реквизит «Дата документа».
Параметры fromDocumentDate и toDocumentDate задаются в формате ДД.ММ.ГГГГ, то есть представляют собой только даты, а не полноценные метки времени.
Необязательный параметр afterIndexKey позволяет итерироваться по списку документов, удовлетворяющих фильтру.
Если в запросе присутствует параметр afterIndexKey, то список документов в выдаче начинается с документа, следующего за документом, имеющим ключ afterIndexKey (поле Document.IndexKey ).
Cам документ с ключом afterIndexKey в выдачу при этом не попадает. Если данный параметр в запросе отсутствует, то выдается начало списка документов, удовлетворяющих фильтру.
GenerateTitleXml¶
Обобщённый метод генерации. Позволяет изготовить xml-файл любого титула любого типа документа.
В теле ответа содержится сгенерированный XML-файл титула, построенный на основании данных из запроса. Файл изготавливается в соответствии с XSD-схемой соответствующего титула документа.
Имя файла сгенерированного титула возвращается в стандартном HTTP-заголовке Content-Disposition.
Как использовать. Генерация титула отправителя (первого титула документа):
В качестве примера рассмотрим генерацию счёта-фактуры формата приказа ФНС №820. Для этого с помощью метода GetDocumentTypes найдем интересующий тип и версию:
Для простоты примера из ответа убраны другие типы, функции, версии, и информация о метаданных. Главное, что нужно взять из этой информации:
Теперь нужно подготовить контент для титула. Титул — это xml-файл, соответствующий xsd-схеме. Часть данных в титуле может быть заполнена только пользователем — это информация о товарах, услугах и т.д. А часть данных может быть заполнена автоматически на основании формата и информации в Диадоке. Например, заполнить реквизиты организации продавца и покупателя по идентификатору ящика, установить значения КНД, версии формата, версии программы и т.д. Для упрощения генерации, Диадок позволяет заполнить только «пользовательский» xml-файл, он же UserDataXml. На базе UserDataXml метод генерации сформирует основной титул, дополнив его всеми необходимыми данными согласно xsd-схеме.
Общая схема работы:
Выбор, как формировать UserDataXml, остаётся за разработчиком интеграционного решения.
Один из путей — это кодогенерация из xsd-схемы упрощённого титула. Ссылка на схему находится в поле UserDataXsdUrl из выдачи GetDocumentTypes выше.
В качестве примера, в C# SDK для всех версий формата приказа №820 есть пример кодогенерации.
Чтобы воспользоваться ей в C#-клиенте, достаточно заполнить объект UniversalTransferDocument для титула отправителя (или UniversalTransferDocumentBuyerTitle для титула получателя) и затем сериализовать в XML.
Итого, имея идентификаторы типа, функции, версии, порядкового номера титула, а также пользовательский контент, можем получить сам титул счёта-фактуры.
Пример UserDataXml (тело запроса):