Интеграция с Диадок

Диадок — инструкция по подключению и работе

Модуль «Интеграция с Диадок» формирует счёт и акт в PDF, счёт-фактуру и УПД в XML и передаёт документы из заказа «1С-Битрикс: Управление сайтом» в Диадок. В версии 2.0.0 можно передать документ без подписи для последующей работы в кабинете Диадока либо подписать и отправить его из админки через КриптоПро.

Что понадобится

• Учётная запись Диадока с доступом к ящику организации-продавца.
  
• Доступ к API Диадока и Кабинету интегратора Контура.
  
• Client ID приложения, Client secret и Refresh token.
  
• ID ящика продавца — BoxId либо BoxIdGuid.
  
• Реквизиты продавца, банковские реквизиты и данные подписанта XML.
  

Для подписания в Диадоке понадобятся подходящая электронная подпись и полномочия подписанта. Доступ к API, исходящие документы и услуги Контура оплачиваются отдельно от лицензии модуля. Условия и стоимость уточняйте в Контуре.

1. Установите модуль

1. Перед установкой на рабочий сайт сделайте резервную копию файлов и базы данных.
   
2. В административном разделе откройте «Marketplace → Установленные решения», установите «Интеграция с Диадок» и подтвердите установку.
   
3. Нужны PHP 8.2 или новее, главный модуль main 24.0.0 или новее, sale 26.0.0 или новее, модули catalog и currency, MySQL и UTF-8. Редакция CMS должна содержать интернет-магазин: «Малый бизнес» или «Бизнес».
   
4. Проверьте расширения PHP cURL, DOM, mbstring, iconv и zlib. Для PDF установите на сервере TTF-шрифт с кириллицей: DejaVu Sans, Liberation Sans или Arial. Если автоматический поиск не находит шрифт, укажите путь в настройках модуля.
   
5. Для ключей нужен закрытый каталог вне корня сайта с правом записи для PHP. Если его создание запрещено хостингом, обратитесь к администратору сервера. Открытый каталог сайта не подходит для хранения ключей.
   

2. Получите доступ к API

1. Оставьте заявку на странице интеграции с API Диадока. Укажите, что подключаете модуль для CMS «1С-Битрикс: Управление сайтом».
   
2. Получите доступ к Кабинету интегратора и идентификатор приложения Client ID.
   
3. Откройте приложение в Кабинете интегратора. В разделе «API-ключи» нажмите «+ Выпустить ключ». Этот ключ используется в модуле как Client secret.
   
4. Сохраните ключ в надёжном месте. Не используйте вместо него пароль от Диадока и не публикуйте ключ на скриншотах.
   

Подробности: подключение к Диадок API.

3. Проверьте права сотрудника в Диадоке

Refresh token выпускается от имени конкретной учётной записи и действует в пределах её прав. Убедитесь, что у записи есть доступ к ящику продавца и право создавать и редактировать документы и черновики. Сотруднику, который подписывает документы в Диадоке, также нужно право подписи. Для интеграции можно выделить отдельную служебную учётную запись.

4. Получите Refresh token

1. В настройках приложения Кабинета интегратора выберите способ получения токенов AuthorizationCode.
   
2. В разделе «Выпуск токенов» выберите нужную площадку: Diadoc.PublicAPI для основной или Diadoc.PublicAPI.Staging для тестовой. Для обновления токенов нужен доступ offline_access.
   
3. Нажмите «Получить refresh-токен». Если после изменения настроек Контур просит подождать, повторите выпуск через несколько минут.
   
4. Выберите учётную запись с доступом к ящику продавца и подтвердите запрашиваемые разрешения. Для отдельной служебной записи можно открыть ссылку в приватном окне браузера.
   
5. Если потребуется API-ключ, введите Client secret приложения. Сохраните полученный Refresh token.
   

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

Модуль обновляет токены при обращении к API и сохраняет новый Refresh token. При длительном перерыве может понадобиться повторный выпуск. Для каждой установки модуля, каждого сайта и другой интеграции используйте отдельный Refresh token: совместное использование копии обновляемого токена может нарушить работу подключений.

5. Найдите ящик продавца через форму создания документа

ID ящика своей организации можно узнать в форме создания документа. Для поиска достаточно сохранить API-ключи; включать обмен и формировать документ на этом шаге не нужно.

1. В настройках модуля выберите сайт и площадку, введите Client ID, Client secret и Refresh token и сохраните настройки. Поле «ID ящика отправителя» пока оставьте пустым, флажок «Разрешить обмен с Диадоком» не устанавливайте.
   
2. Откройте любой доступный вам заказ, перейдите в блок «Документы Диадок» и откройте документы заказа. Либо откройте «Сервисы → Диадок → Документы заказов» и укажите внутренний ID заказа.
   
3. В разделе «Создать документ» временно введите ИНН своей организации в поле «ИНН покупателя» и КПП при наличии — в поле «КПП покупателя».
   
4. Нажмите «Найти по ИНН / КПП». Поиск выполняется без перезагрузки страницы. Если найдено несколько ящиков, выберите ящик своей организации на нужной площадке.
   
5. Скопируйте ID выбранного ящика из поля «Ящик получателя». В списке он указан в конце выбранного варианта. Не нажимайте «Сформировать и сохранить»: для получения ID создавать документ не требуется.
   
6. Вернитесь в настройки модуля того же сайта и вставьте скопированное значение в поле «ID ящика отправителя». Заполните ИНН/КПП продавца и остальные реквизиты, включите обмен, сохраните настройки и нажмите «Проверить подключение».
   

При работе с документом покупателя введите уже его ИНН и КПП и найдите его ящик заново. Собственный ящик используется как ящик отправителя. У основной и тестовой площадок разные ящики; площадка модуля должна совпадать с доступами токена.

Модуль принимает BoxId вида «32 шестнадцатеричных символа@diadoc.ru» и GUID с дефисами. Не подставляйте ИНН, ID организации или идентификатор участника ЭДО вместо ID ящика.

6. Настройте подключение в Битриксе

1. Откройте «Настройки → Настройки продукта → Настройки модулей» и выберите «Интеграция с Диадок». Прямая страница: /bitrix/admin/settings.php?mid=proffiweb.pwdiadoc.
   
2. Выберите сайт. Продавец, площадка, ящик и ключи настраиваются отдельно для каждого сайта.
   
3. На вкладке «Подключение» выберите площадку, введите Client ID, ID ящика отправителя, Client secret и Refresh token.
   
4. На вкладке «Продавец» заполните организацию или ФИО ИП, ИНН, КПП при наличии, юридический адрес и банковские реквизиты. Эти сведения используются в PDF.
   
5. На вкладке «Подписант XML» заполните ФИО, должность и способ подтверждения полномочий. Для подписания XML ФИО должны соответствовать выбранному сертификату КЭП.
   
6. Если подпись выполняется по МЧД, на вкладке «МЧД» заполните регистрационный номер доверенности (GUID), ИНН доверителя и ИНН представителя. При выбранном способе «Машиночитаемая доверенность» эти сведения обязательны. Полномочия, регистрацию и действительность доверенности проверяйте в Диадоке.
   
7. На вкладке «Документы» выберите НДС и функцию УПД по умолчанию. Перед созданием проверяйте их соответствие операции.
   
8. Установите флажок «Разрешить обмен с Диадоком», сохраните настройки и нажмите «Проверить подключение». Должно появиться сообщение о доступности ящика отправителя.
   

Сохранённые секреты не показываются в форме. Пустые поля Client secret и Refresh token сохраняют прежние значения; для замены введите новые, для удаления используйте отдельный переключатель. Не копируйте настроенные ключи в публичный архив модуля.

В блоке «Права доступа» назначьте группам просмотр или создание документов и отдельно разрешите «Передавать в Диадок» и «Подписывать». Для действия «Подписать и отправить» нужны оба разрешения, право создания документов и доступ к изменению конкретного заказа. Разрешения разных групп сотрудника объединяются. Администраторы имеют полный доступ; остальные сотрудники после обновления на 2.0.0 не получают новые разрешения автоматически. Настройки и ключи доступны только администратору.

7. Сформируйте документ из заказа

1. Откройте заказ, найдите блок «Документы Диадок» и перейдите к документам. Либо откройте «Сервисы → Диадок → Документы заказов» и укажите внутренний ID заказа.
   
2. Выберите счёт, акт, счёт-фактуру или УПД, проверьте номер и дату. Для УПД выберите СЧФДОП или ДОП.
   
3. Для счёта-фактуры укажите фактический документ об отгрузке: наименование, номер и дату. Заказ и счёт на оплату не заменяют документ об отгрузке.
   
4. Проверьте реквизиты покупателя. Для организации нужны наименование, юридический адрес, ИНН и КПП; для ИП КПП не требуется.
   
5. Если документ будет передаваться в Диадок, до его создания нажмите «Найти по ИНН / КПП» и явно выберите ящик получателя. Поиск выполняется без перезагрузки страницы. При изменении ИНН или КПП выполните поиск заново.
   
6. Проверьте ставки НДС и ОКЕИ каждой позиции, подтвердите проверку и нажмите «Сформировать и сохранить».
   
7. Скачайте документ и проверьте файл. Для отложенной передачи нажмите иконку «Передать для подписания в Диадоке» и подтвердите действие, затем подпишите и отправьте документ в кабинете Диадока.
   
8. Для подписания из админки нажмите «Подписать и отправить», выберите сертификат КЭП, проверьте подписанта и подтвердите действие. Подтвердите запросы КриптоПро на доступ к ключу и PIN-код, если они появятся. Это действие отправляет подписанный документ контрагенту.
   
9. Нажмите «Получить статус» и проверьте результат в Диадоке. Статус «Передан с подписью» означает успешный ответ на передачу; результат проверки подписи и дальнейшего документооборота получите отдельно.
   

Действия в списке обозначены иконками: стрелка вниз — скачать PDF/XML; бумажный самолёт — передать для подписания в Диадоке; документ с пером — подписать и отправить; корзина — удалить локальный документ; логотип Диадока — открыть переданный документ; круговые стрелки — получить статус. Подсказка появляется при наведении или фокусе клавиатуры. В колонке «Статус» показано одно состояние на русском языке; после обновления оно заменяется актуальным состоянием Диадока.

Счёт и акт можно сформировать локально без API и ящика получателя. Чтобы передать такой файл позднее, создайте новый документ с настроенным подключением и выбранным ящиком. Для XML API нужен уже при формировании. Ящики отправителя и получателя при передаче должны различаться.

Для подписи из админки: установите на компьютер КриптоПро CSP, КриптоПро ЭЦП Browser plug-in и расширение поддерживаемого браузера, установите действующий сертификат с закрытым ключом. Разрешите работу расширения на адресе админки; открывайте рабочую админку по HTTPS. Проверку установки выполните на официальной странице КриптоПро. Лицензии и настройка КриптоПро обеспечиваются отдельно. При выборе сертификата модуль загружает официальный адаптер с сайта cryptopro.ru. Закрытый ключ и PIN-код модулю не передаются; сохраняются файл документа и сформированная подпись в составе запроса Диадоку.

При отмене запроса КриптоПро или ошибке подписи передача не выполняется. Если КриптоПро не ответил за две минуты, закройте его запрос перед новой попыткой. Если тайм-аут возник при передаче в Диадок, обновите страницу и проверьте состояние: для незавершённой операции используйте «Повторить тот же запрос». Не выбирайте другой режим и не создавайте новый документ для обхода неопределённого результата. Уже переданный документ нельзя повторно подписать в админке.

Документ формируется на весь заказ в RUB, не более 500 позиций вместе с доставкой. Поддерживаются ставки без НДС, 0, 5, 7, 10, 20 и 22%. Не поддерживаются частичные отгрузки, маркировка, прослеживаемость, акцизы, экспорт, авансовые и корректировочные документы, аннулирование в Диадоке. Оплата, остатки и статус заказа не меняются.

8. Проверьте работу перед использованием

Используйте тестовые ящики, предоставленные Контуром, и установите отношения контрагентов по быстрому старту Диадок API. Ящики, выбранная площадка и разрешения токена должны относиться к одному окружению. Тестовая организация на основной площадке не переключает модуль на тестовую площадку автоматически.

Сначала сформируйте и скачайте файл. Кнопка «Для подписания в Диадоке» сохраняет документ для последующей работы в кабинете. Кнопка «Подписать и отправить» отправляет подписанный документ в выбранный ящик сразу; при проверках используйте только согласованный тестовый ящик.

9. Повтор, ошибки и восстановление

• Ошибка авторизации. Проверьте Client ID, Client secret и Refresh token, разрешения и площадку. При необходимости выпустите новый токен.
  
• Нет доступа к ящику. Проверьте ID ящика, ИНН/КПП продавца, площадку и права учётной записи.
  
• Ошибка 402. Уточните у Контура состояние доступа организации к API и условия лицензии.
  
• Нет кнопки подписи или передачи. Администратор должен выдать соответствующие отдельные разрешения группе сотрудника; также нужны право создания документов и доступ к изменению заказа. Подпись доступна только для локального документа до передачи.
  
• КриптоПро недоступен. Проверьте CSP, Browser plug-in, расширение, сертификат с закрытым ключом и разрешение доступа для адреса админки.
  
• ФИО сертификата не совпадает с XML. Укажите правильного подписанта в настройках и сформируйте новый XML. Сохранённый файл не переписывается.
  
• XML не формируется из-за адреса. Проверьте юридические адреса организаций в ящиках Диадока. Реквизиты организаций в XML берутся из этих ящиков.
  
• Передача не завершена. После тайм-аута или неопределённого ответа повторяйте прежний запрос: его содержимое и operationId уже зафиксированы. Не создавайте другой документ для обхода такого состояния.
  
• Нужно исправить документ. Локальный документ до начала передачи можно удалить и сформировать заново. Файл после создания не переписывается. Документы с начатой или завершённой передачей локальным удалением не снимаются.
  
• Изменён ящик или площадка. Старый документ привязан к прежнему подключению. Верните исходные настройки либо создайте новый документ с новым номером.
  

10. Отключение и удаление

Для остановки обмена снимите флажок «Разрешить обмен с Диадоком» у нужного сайта. При удалении модуля документы, журнал, настройки и закрытые ключи по умолчанию сохраняются. Отдельный выбор удаления данных очищает таблицы и настройки всех сайтов; ключи в закрытом каталоге удаляет администратор сервера. Сообщения в Диадоке этим не отзываются. До удаления сохраните нужные документы и резервную копию.

По окончании 7-дневного пробного периода функции модуля блокируются штатной системой Маркета до приобретения лицензии. Документы и настройки не удаляются. Продление лицензии модуля и оплата услуг Диадока — отдельные действия.

Поддержка: support@proffiweb.ru, понедельник–пятница, 08:00–18:00 по Москве. Первый ответ — в течение рабочего дня. Не направляйте ключи и пароли в открытой переписке.

 

Техническая поддержка Proffiweb



E-mail: support@proffiweb.ru (mailto:support@proffiweb.ru).




Рабочие дни: понедельник–пятница, 08:00–18:00 по московскому времени. Первый ответ — в течение рабочего дня; обращения вне рабочего времени рассматриваются в следующий рабочий день. Срок устранения зависит от причины и необходимых сведений.




Поддержка охватывает установку, штатные настройки и воспроизводимые ошибки модуля в заявленной среде, в период действия поддержки по лицензии Маркета. Доработки, администрирование сервера, получение доступа к API и услуги Контура согласовываются отдельно.




В обращении укажите версию модуля, версии PHP и CMS, шаги воспроизведения и текст ошибки. Прикладывайте обезличенные скриншоты. Не направляйте пароли, Client secret, Refresh token и электронные подписи в открытой переписке.