Project

General

Profile

View source (English) EN RU ET LT LV Русский
English Eesti Lietuvių Latviešu

Wiki » 04 Transmission communication channels and API »

01 Описание электронной почты

  1. Электронная почта является одним из каналов передачи, используемых Docura для обмена деловыми документами с партнёрами. Задействованы два независимых механизма:
    1. Входящие — почтовый ящик на почтовом сервере Docura, куда партнёры отправляют документы для автоматического парсинга и доставки в Docura (раздел 02).
    2. Исходящие — уведомления, которые Docura отправляет партнёрам при получении или отправке документа, с самим документом в качестве вложения (раздел 03).
  2. Электронная почта удобна тем, что партнёру не требуется программное обеспечение EDI, учётная запись FTP и сертификаты — достаточно почтового ящика. Это делает электронную почту самым быстрым способом подключения контрагента, у которого нет EDI вообще.
  3. Слабыми сторонами электронной почты являются доставляемость (SPF, DKIM и DMARC домена отправителя, см. раздел 06) и тот факт, что почтовые клиенты составляют письма очень по-разному (см. раздел 02).

02 Входящий почтовый шлюз (парсинг)

  1. Для входящих документов Docura создает почтовый ящик на своем почтовом сервере, в домене @edi.docura.net. Почтовый ящик создается службой поддержки Docura в панели администратора почтового сервера — отправителю нужно знать только адрес.
  2. Именование согласовывается со службой поддержки Docura. Типичные шаблоны:
    1. — стандартный случай, один шлюз на контрагента. Название компании пишется без пробелов, допустимы короткие читаемые сокращения (например, ep@ для Eesti Pagar).
    2. — когда задействовано несколько стран или форматов, например
    3. — когда типы документов обрабатываются отдельно, например
  3. Почтовый ящик отслеживается: Docura периодически собирает письма, извлекает содержимое, преобразует его в согласованный формат и доставляет документ в среду Docura клиента. Это также работает для контрагентов, которые вообще не хотят реального EDI-соединения — иногда это называется «слепым» EDI.
  4. Нет строгих правил относительно самого письма — отправитель не обязан отправлять один документ в одном письме:
    1. Письмо может содержать несколько документов или один архив (например, zip) со множеством файлов внутри — все подбирается и обрабатывается.
    2. Важно соответствие согласованному макету и формату документа, а не количество файлов в письме.
  5. Содержимое, которое может быть разобрано:
    1. Прайс-листы Excel — загружаются как PRODUCTCATALOG / PRICAT (макет согласовывается заранее)
    2. XML-документы — Docura XML или другой согласованный формат (INVOICE, ORDER, DESADV и другие)
    3. Другие форматы по согласованию — EDIFACT, CSV, Telema/Edisoft XML
  6. Два режима извлечения документа из письма (выбираются для каждого отношения совместно со службой поддержки Docura):
    1. Вложение — все вложения письма извлекаются по одному и каждое обрабатывается. Это обычный режим.
    2. Тело — все письмо преобразуется в XML и обрабатывается. Используется, когда данные находятся в тексте письма, а не в файле.
  7. Фильтры решают, что принимается, а что игнорируется. Они настраиваются Docura для каждого отношения:
    1. Фильтр отправителя (регулярное выражение) — принимать письма только с согласованной маски адреса.
    2. Фильтр темы (регулярное выражение) — принимать письма только с соответствующей темой.
    3. Фильтр имени файла (регулярное выражение, например (?i)(.*)(.xls|.xlsx)) вместе с типом файлового фильтра (например Error without notification). Это существует потому, что отправители часто добавляют логотипы, изображения и подписи, а каждое вложение обрабатывается — фильтр отсекает такие файлы.
  8. Таким образом, отправителю не требуется особая дисциплина: достаточно отправить на согласованный адрес, и лишний файл будет просто отфильтрован, а не вызовет ошибку парсинга.
  9. То, что не проходит фильтры, не теряется: если отношение настроено соответствующим образом, письмо пересылается без изменений на адрес ошибок, с перемещением исходных полей From и To в тему (иначе такое письмо попало бы в спам).
  10. Оригинальное письмо также может быть перенаправлено клиенту (Copy email) — используется, когда письма в свободной форме должны быть просмотрены человеком.
  11. Рабочий пример — Fristar_SIA: адрес принимает прайс-листы (Excel) и XML-счета, а страница описывает весь поток со стороны партнера.
  12. Шлюз не предназначен для массовых рассылок: скорость приема ограничена (около 150 писем в минуту). Выше этого письма попадают в журнал отклонений, а отправитель блокируется на 24 часа. Массовый обмен осуществляется через FTP или API.

03 Исходящие уведомления

  1. Исходящие письма — это уведомления о документах. Уведомление настраивается для каждого отношения: тип документа, статус документа, направление и партнер, поэтому у одной организации может быть несколько уведомлений с различными настройками.
  2. Получатели собираются из нескольких источников:
    1. To — электронная почта получателя, взятая из самого документа (Document-Invoice/Document-Parties/Receiver/E-mail)
    2. плюс любые адреса, явно указанные в уведомлении
    3. плюс, для некоторых партнеров, адреса, взятые из LOCCAT получателя — используется, когда один счет должен быть доставлен во многие магазины или пункты доставки
  3. Reply-to берется из электронной почты отправителя в документе (Document-Invoice/Document-Parties/Sender/E-mail), чтобы ответ партнера дошел до нужного человека.
  4. Тело письма формируется с помощью XSLT-шаблона (Email xslt), и документ может быть прикреплен в виде файла.
  5. По умолчанию все уведомления отправляются с домена Docura: .

04 Настройки SMTP-соединения

SMTP-соединение — это сохраненный набор учетных данных, который сообщает Docura, какой почтовый ящик и какой сервер использовать для отправки. Оно создается и поддерживается в веб-приложении Docura (вкладка Уведомления, окно Обновить SMTP-соединение):

Поле Значение
Description Свободный комментарий, обычно имя почтового сервера
serverName Хост SMTP-сервера почтового ящика отправителя
serverPort SMTP-порт, обычно 25, 465 или 587
Username Логин почтового ящика, т.е. адрес, с которого фактически отправляется почта
User password Пароль от этого почтового ящика
Connection security Режим шифрования, обычно SSL_TLS
  1. Кнопка Test connection проверяет сохраненные учетные данные до переключения уведомления.
  2. SMTP-соединение также может быть создано через API (операция createSmtpConnection): organizationId, description, fromName, serverName, serverPort, userName, userPassword, connectionSecurity.

05 Настройки уведомлений в EDI-Web

Адреса отправителей не являются глобальными — они устанавливаются в самом уведомлении: Уведомления — Редактировать, вкладка Информация об уведомлении.

Поле Значение
Email Адрес(а) получателя(ей) уведомления
From name (name <email>) Адрес, С КОТОРОГО отправляется уведомление
Reply to (name <email>) Адрес, на который пойдёт ответ партнёра
Partner Организация-партнёр, к которой относится уведомление
Smtp connection Какое SMTP-соединение (почтовый ящик) используется для отправки
Email xslt XSLT-шаблон, который формирует тело письма
Enabled Включено / выключено
  1. На вкладке SMTP показывается соединение, которое используется данным уведомлением, на вкладке XSLT — шаблон.
  2. Получатели, которых нет в самом документе, могут быть добавлены дополнительно в уведомлении, см. раздел 03.

06 Какой адрес отправителя используется

  1. По умолчанию: домен Docura. От = , Ответить = адрес клиента. Доставляемость гарантирована, потому что домен Docura имеет корректные записи SPF, DKIM, DMARC и PTR. Это охватывает большинство случаев и является рекомендуемой настройкой.
  2. От = собственный домен клиента. Два варианта:
    1. Через собственный почтовый сервер клиента — SMTP-сервер клиента, логин и пароль хранятся как SMTP-подключение. SPF и DKIM домена клиента проходят, потому что почта действительно отправляется их сервером. Это самый безопасный вариант для поля «От» клиента.
    2. Через почтовый сервер Docura, сохраняя адрес клиента в поле «От». Тогда DNS клиента должен быть подготовлен заранее, иначе такие письма попадают в спам или отклоняются:
      TXT mail._domainkey "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq4dvMit/5L1okysL1nzm3d+qsl1XYeEg8sUzuBHSWRzX8UQ2Xai6cYukmBU7N4Brn69+1xc8DbdUwlP1mpiYhf2qTK7yaYjZTnfyyyumTCFhkHGDfJmga6p2JsOIUQ5dFhlE4gQBUI4FY3a3XZM2gbUVTr08dGkpEJA3yrsbJ5akl88tJsvX4Osw1EJl6i9dn" "1yzX+VxFlD6imjDDgYvyu2sxzWhU6dGtvg7KsP+8x0mXXp9gGFT/odo5zbLjmD0VT9KMWNwRUlBAsOT7bCJgauEXk9ygSnCazZ5UpmGgKfPuXIEXGTEUzRSblTNqKsUjGZtdiWxBo2FXPqnT+AIPwIDAQAB" 

TXT @ "v=spf1 ip4:78.46.44.41 ip4:78.46.44.49 ip4:178.63.30.140 a mx ~all" 

TXT _dmarc "v=DMARC1;p=none"

01 Через Docura, сохраняя адрес клиента в поле «От». DNS

DNS-записи для клиента «От» (SPF, DKIM, DMARC). Необходимы только для варианта 2.2 выше. Все три записи — это TXT-записи в том же домене, который используется в поле «От» — @@ означает корень этого домена, а не субдомен.

01 SPF

Разрешена только одна запись SPF на домен. Если у вас уже есть запись, не создавайте вторую — добавьте адреса Docura в существующую запись, сохранив все, что там уже есть.

TXT @ "v=spf1 ip4:78.46.44.41 ip4:78.46.44.49 ip4:178.63.30.140 a mx ~all"

~all — это мягкий режим: письма с других адресов помечаются как подозрительные, но доставляются. -all отклоняет их, поэтому при использовании -all каждый отправитель домена должен быть указан в списке.

02 DKIM

Новая запись, ничего не заменяет. mail — это селектор, поэтому другие службы, подписывающие почту для вашего домена, не затрагиваются.

TXT mail._domainkey "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAq4dvMit/5L1okysL1nzm3d+qsl1XYeEg8sUzuBHSWRzX8UQ2Xai6cYukmBU7N4Brn69+1xc8DbdUwlP1mpiYhf2qTK7yaYjZTnfyyyumTCFhkHGDfJmga6p2JsOIUQ5dFhlE4gQBUI4FY3a3XZM2gbUVTr08dGkpEJA3yrsbJ5akl88tJsvX4Osw1EJl6i9dn" "1yzX+VxFlD6imjDDgYvyu2sxzWhU6dGtvg7KsP+8x0mXXp9gGFT/odo5zbLjmD0VT9KMWNwRUlBAsOT7bCJgauEXk9ygSnCazZ5UpmGgKfPuXIEXGTEUzRSblTNqKsUjGZtdiWxBo2FXPqnT+AIPwIDAQAB"

Две строки в кавычках, потому что одна строка TXT не может превышать 255 символов — DNS объединяет их при чтении.

03 DMARC

На домен разрешается только одна запись DMARC. Если она у вас уже есть, оставьте ее как есть. Приведенная ниже запись предназначена только для доменов, у которых ее нет.

TXT _dmarc "v=DMARC1;p=none"

04 PTR и HELO

Относятся к отправляющим серверам Docura, а не к вашему домену. Поддерживаются Docura, от вас не требуется никаких действий.

05 После добавления

Изменения DNS вступают в силу от нескольких минут до 24 часов в зависимости от TTL. Когда записи станут видны, запросите тестовое письмо у службы поддержки Docura, см. раздел 07. Пока оно не будет пройдено, продолжайте отправлять письма с домена Docura.

07 Тестирование и поддержка

  1. Попросите поддержку Docura отправить тестовое письмо на адрес клиента и проверить необработанные заголовки (From, Reply-to, результат SPF/DKIM/DMARC).
  2. Для входящего шлюза отправьте один заказ или счет (обычное письмо с любыми дополнительными файлами, которые добавляет ваш почтовый клиент) на адрес edi.docura.net и попросите поддержку подтвердить, что оно было правильно обработано.
  3. Пишите на или используйте чат в EDI-Web для решения любых вопросов, касающихся почтовых ящиков шлюза, фильтров, адресов отправителей и записей DNS.

Source version: 15 · Status: fresh · Roman Startsev