Перейти к основному содержимому

Единичный (без состояния)

Информация о разделе​

Страница содержит сценарии использования API, предусматривающие работу для единичных клиентов (одной организации). Такие клиенты не хранят информацию на своей стороне: работа происходит в режиме опроса — "тонкий клиент".

Добавление организации​

Начните ведение документооборота с добавления организации. Для этого необходимо зарегистрировать нового абонента в системе Астрал.ЭДО. С его помощью можно получить идентификатор абонента и воспользоваться методами работы с ЭДО.

Для регистрации абонента необходимо выполнить ряд обязательных действий:

  • [Обязательно] Создать заявку на подключение.

    Для создания новой заявки, необходимо передать открытую часть ключа сертификата с помощью метода [POST]/api/v1/registration. В результате вернется подробная информация о созданной заявке на регистрацию.

  • [Обязательно] Заполнить или обновить регистрационную заявку.

    Чтобы выбрать тарифный план и отправить заявку на обработку, необходимо заполнить ряд минимально требуемых реквизитов: юридический адрес организации, email и телефон. Заполнить новые или обновить текущие реквизиты заявки можно одним из следующих методов:

    В результате вернется системное сообщение об успешном обновлении реквизитов.

    ВАЖНО: При заполнении идентификатора налогового органа вносите значение согласно списку доступных налоговых органов, зарегистрированных в системе Астрал.ЭДО. Получить список можно с помощью метода [GET]/api/v1/registration/tax-authoritу.

  • [Обязательно] Выбрать или обновить тарифный план.

    Чтобы завершить процесс создания заявки, необходимо выбрать тарифный план и указать его. Метод [PUT]/api/v1/registration/requests/{registrationRequestId}/tariff позволит обновить сведения о выбранном тарифе. В результате вернется системное сообщение об успешном обновлении тарифа в заявке.

    Примечание — список доступных тарифов можно получить с помощью метода [GET]/api/v1/registration/tariffs, а также расширений [GET]/api/v1/registration/tariffs/extensions.

  • [Опционально] Удалить заявку.

    Чтобы удалить созданную заявку, необходимо воспользоваться методом [DELETE]/api/v1/registration/requests/{registrationRequestId}.

    ВАЖНО: Удалить заявку возможно только в статусе New или Rejected. В случае попытки удаления заявки в любом другом статусе, система вернет сообщение об ошибке: “Невозможно удалить отправленную или принятую заявку на регистрацию”.

    Примечание — для получения актуального статуса можно воспользоваться методом [GET]/api/v1/registration/requests/{registrationRequestId}.

  • [Обязательно] Отправить заявку на обработку.

    С целью завершить регистрацию, необходимо отправить заявку на подключение в сервис Астрал.ЭДО с помощью метода [PUT]/api/v1/registration/requests/{registrationRequestId}/dispatch. В результате вернется системное сообщение об успешной отправке заявки.

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

  • [Опционально] Получить информацию по отправленной заявке.

    Чтобы получить подробную информацию по заявке и узнать ее статус, необходимо воспользоваться методом [GET]/api/v1/registration/requests/{registrationRequestId}.

  • [Опционально] Получить список отправленных заявок.

    Для получения списка активных заявок на подключение можно воспользоваться методом [GET]/api/v1/registration/requests. В результате вернется список отправленных ранее заявок.

Получение идентификатора пользователя​

Большинство методов API требуют идентификатор абонента, от имени которого выполняются действия в системе. Данный идентификатор записывается в Header многих запросов (подробнее о структуре методов в документации или же в "Swagger" сервиса).

Для получения идентификатора абонента необходимо выполнить следующие шаги:

  • [Обязательно] Получить список абонентов.

    Для получения списка абонентов, к которым пользователь имеет доступ, необходимо выполнить метод API [GET]/api/v1/abonents. В результате вернется подробный список абонентов, с названиями организаций, идентификаторами и другой информацией. Для дальнейшей работы, в методы API необходимо будет прокидывать идентификатор абонента используя заголовки.

  • [Опционально] Получить подробную информацию об абоненте.

    В случае, если вам необходимо получить подробную информацию об абоненте (информация о лицензиях, адресах или сотродниках), вы можете воспользоваться методом API [GET]/api/v1/abonents/{abonentId}. В результате работы метода вернется полная информация по указанному идентификатору абонента.

Первичная установка связи​

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

Методы для инициатора​

  • [Опционально] Получить идентификатор участника ЭДО (ИдЭДО).

    Необходимо найти идентификатор участника ЭДО (ИдЭДО) контрагента, используя метод API [GET]/api/v1/counterparties/globalIds (возможно наличие идентификаторов, в такой ситуации, необходимо уточнить верный идентификатор у вашего контрагента).

  • [Обязательно] Отправить приглашение контрагенту.

    Для отправки приглашения необходимо воспользоваться методом API [POST]/api/v1/invitations используя идентификатор участника ЭДО (ИдЭДО). В результате успешного выполнения данного запроса будет возвращен идентификатор приглашения. Идентификатор необходим для получения подробной информации о приглашении.

    Примечание — идентификатор ЭДО можно получить запросив его у контрагента напрямую, не используя метод поиска.

  • [Опционально] Проверить состояние отправленного приглашения.

    Для определения состояния приглашения необходимо воспользоваться методом [GET]/api/v1/invitations/{invitationId}, используя ранее полученный идентификатор. Это позволит узнать характер ответа в случае получения его от контрагента. Для определения состояния обратите внимание на статус в ответе.

    ВАЖНО: Если контрагент отклонил приглашение, его можно отправить повторно. Если контрагент добавил вас в черный список, отправить приглашение будет невозможно до тех пор, пока он не исключит вас из черного списка.

  • [Опционально] Проверить адресную книгу.

    Если получатель примет приглашение, то он автоматически появится в вашей адресной книге, посмотреть которую можно с помощью метода [GET]/api/v1/counterparties/contacts. Данный метод вернет вам информацию по контрагентам, с которыми налажена связь.

  • [Опционально] Проверить список исходящих приглашений.

    В случае, если вы отправили приглашения сразу нескольким контрагентам, возможно посмотреть все исходящие приглашения, вызвав метод [GET]/api/v1/invitations/outgoing. Обратите внимание, что в данный список попадают приглашения, статусы которых принимают одно из следующих значений: Sent, Rejected или Deferred. Если ваше приглашение приняли, cтатус примет значение Accept, следовательно, оно не попадет в этот список.

Методы для получателя​

  • [Обязательно] Запросить список входящих приглашений.

    Другие контрагенты также могут отправлять приглашения. Для того чтобы узнать, есть ли у вас входящие приглашения, необходимо воспользоваться методом [GET]/api/v1/invitations/incoming. результате вернется список входящих приглашений (если они есть), на которые можно сформировать ответ (как принять, так и отклонить).

    ВАЖНО: В списке выводятся приглашения только в статусе Sent.

  • [Обязательно] Принять или отклонить приглашение.

    Заключительным шагом для установки связи с контрагентом является формирование ответа на приглашение. В данном случае есть два возможных варианта ответа:

    • [PUT]/api/v1/invitations/{invitationId}/acceptance - метод позволяет принять приглашение и начать обмен документами. Приглашение перейдет в статус Accept;
    • [PUT]/api/v1/invitations/{invitationId}/rejection - метод позволяет отклонить приглашение, если вы считаете, что установка связи вам не требуется. Приглашение перейдет в статус Rejected.

    ВАЖНО: Нельзя принять приглашение в статусе Rejected - "Отклонено". Если требуется установить связь после ее разрыва, необходимо снова воспользоваться методом отправки приглашения.

Разрыв установленной связи (Любая сторона)​

Даже после принятия приглашения, есть возможность разорвать существующую связь.
В случае, если вы не знаете идентификатор контакта, то можно воспользоваться следующим способом:

  • [Обязательно] Получить идентификатор контакта.
    Для получения вашей адресной книги и идентификатора контакта необходимо воспользоваться методом [GET]/api/v1/counterparties/contacts. Данный метод вернет вам информацию по контрагентам, с которыми уже налажена связь.
  • [Обязательно] Выполнить удаление контакта по идентификатору.
    После того как вы получили идентификатор контакта контрагента, с которым вы хотите разорвать связь, необходимо восползоваться методом для удаления контакта [DELETE]/api/v1/counterparties/contacts/{contactId}.

Импорт и отправка документа (Инициатор)​

  • [Обязательно] Проимпортировать документ в систему.

    Для импортирования документа в систему необходимо воспользоваться методом [POST]/api/v2/drafts. В результате выполнения будет создан черновик, и система вернет результат импорта с описанием.

    ВАЖНО: Все формализованные документы после импорта в систему обновляются в автоматическом режиме. Это означает, что файл, загруженный в систему, будет автоматически изменен (будут подставлены актуальные данные оператора, отправителя и получателя).

    Для того чтобы система не меняла содержимое формализованного документа необходимо воспользоваться методом [POST]/api/v2/drafts/withoutmodify. В результате выполнения будет создан черновик, и система вернет идентификатор черновика. В случае если данные из формализованного документа будут не валидны, система вернет ошибку с описанием.

  • [Опционально] Посмотреть информацию о созданном черновике.

    После импорта черновика есть возможность посмотреть информацию о только что созданном черновике. Для этого необходимо воспользоваться методом [GET]/api/v1/drafts/{draftId}. В результате отобразится информация по ранее загруженному черновику.

  • [Опционально] Посмотреть список черновиков.

    После импорта черновика есть возможность посмотреть список всех импортированных (но не отправленных) черновиков в систему. Для этого необходимо воспользоваться методом [GET]/api/v1/drafts.

  • [Опционально] Скачать файл из системы.

    После импорта черновика есть возможность скачать ранее загруженный файл из хранилища (если система производила изменения, они уже будут внесены в файл). Для этого необходимо воспользоваться методом [GET]/api/v1/drafts/{draftId}/file.

  • [Опционально] Удаление черновика.

    Если отправлять загруженный ранее документ не требуется, можно удалить черновик из системы. Для этого необходимо воспользоваться методом [DELETE]/api/v1/drafts/{draftId}. В результате документ пропадет из списка черновиков.

  • [Обязательно] Обновить информацию о черновике.

    В случае, если автоматически определить получателей не удалось, следует обновить информацию о получателях вручную, используя метод [PUT]/api/v1/drafts/{draftId}/metadata.

    ВАЖНО: Если для неформализованного документа необходимо потребовать ответную подпись, то в предыдущий метод необходимо передать параметр ResponseSignatureRequired = true.

    ДОПОЛНИТЕЛЬНО: Если вы не планируете смотреть итоговый документ, то его можно сразу же отправить, передав в предыдущий метод параметр ShouldSend = true. Этот признак означает, что следующий условно-обязательный пункт "Выполнить отправку файла" выполнится автоматически сразу после обновления данных в черновике.

  • [Условно-Обязательно] Выполнить отправку файла.

    В случае, если черновик находится в статусе «ReadyToSend», можно выполнить отправку документа контрагенту. Для этого необходимо воспользоваться методом [PUT]/api/v1/drafts/{draftId}/dispatch. В результате документооборот будет запущен в асинхронном режиме, а статус черновика будет изменен на WaitingSignature - "Ожидает подписи".

    Примечание — является условно-обязательным, так как документ может быть отправлен в предыдущем пункте.

  • [Обязательно] Запросить список входящих запросов на подпись.

    В зависимости от ваших действий, вам будут поступать запросы на подпись. Одно из таких действий — отправка черновика. Черновик переходит в статус ожидания подписи, и система создает запрос на подпись документа. Для получения списка запросов на подпись необходимо воспользоваться методом [GET]/api/v1/cryptography/requests. Среди списка полученных запросов на подпись необходимо найти запрос с параметром DocumentId == DraftId. Этот запрос будет являться запросом на подпись ранее отправленного документа.

    Примечание — в запросе на подпись будет отсутствовать информация о документообороте и транзакции, так как на этапе подписи черновика документооборот еще не создан.

  • [Условно-Обязательно] Скачать документ для подписи.

    В случае формализованного XML документа, он изменяется в процессе актуализации внутренних данных и потому его необходимо скачать воспользовавшись методом [GET]/api/v1/cryptography/requests/{requestId}/file. Неформализованные документы не подвергаются дополнительной обработке, а соответственно документ уже присутствует у вас в исходном виде и подписать можно именно его.

    Примечание — является условно-обязательным, так как необходимости выполнять его для неформализованных документов нет.

  • [Обязательно] Прикрепить подпись к запросу на подпись.

    Для того, чтобы прикрепить подпись к документу, необходимо использовать метод [POST]/api/v1/cryptography/requests/{requestId}/sign. В результате выполнения метода подпись будет прикреплена к документу, и он будет отправлен. Отправленный документ будет удален из списка черновиков и перемещен в исходящий документооборот.

  • [Опционально] Посмотреть список исходящих документооборотов.

    После отправки документа, будет создана запись о документообороте в списке исходящих документов. Для просмотра данного списка необходимо воспользоваться методом [GET]/api/v1/docflows/outgoing.

Альтернативные методы​

Вариант 1​

  • [Обязательно] Прикрепить подпись к документу черновика.

    Система так же готова принимать подпись к сформированному черновику через метод [POST]/api/v2/drafts/{draftId}/sign. В результате выполнения будет ответ, что подпись прикреплена и валидна. Иначе будет описанна причина не возможности прикрепления подписи к файлу черновика.

  • [Обязательно] Выполнить отправку документа для старта документооборота [POST]/api/v2/drafts/{draftId}/dispatch.

    В результате выполнения будет ответ со списокм идентификаторов нового документооборота и их получателей.

Вариант 2​

  • [Обязательно] Сформировать готовый пакет к отправке.

    Система так же готова принимать готовый пакет для формирования нового документооборота. Для этого необходимо восползоваться методом [POST]/api/v2/docflows/{draftId}/dispatch. В случае импорта НЕформализованного документа необходимо в теле запроса указать список идентификаторов получателей и при необходимости указать флаг о том, что требуется ответная подпись от получателя документа. Во всех остальных случаях достаточно указать валидный документ и актуальную открепленную подпись. Размер импортируемого документа не должен превышать объема 60 мб. В случае если документ не валиден, указаны получатели с которыми не осуществлена связь или информация отправителя не соответстует информации хранящейся в системе будет возвращена модель с описанием ошибки отправки.

Вариант 3​

  • [Обязательно] Отправить подписанный документ (документ+подпись).

    Для того чтобы отправить подписанный документ (документ и подпись в одном контейнере) необходимо отправить запрос [POST]/api/v2/docflows для создания документооборота. В заголовке запроса указывается внутренний идентификатор абонента. В теле запроса передается информация о документе, который необходимо отправить, а также файл подписи к этому документу. В случае успешного создания документооборота (200) возвращается список с информацией о созданном документообороте.

  • [Опционально] Для неформализованного документооборота можно добавить флаг ResponseSignatureRequired, который указывает на необходимость ответной подписи.

  • [Опционально] По умолчанию созданный черновик для отправки документа доступен для редактирования, но если необходимо ограничить доступ только на чтение, можно указать параметр IsReadOnly со значением true.

Прием входящего документа (Получатель)​

  • [Обязательно] Посмотреть список входящих документооборотов.

    Для получения списка входящих документооборотов и их статусов необходимо воспользоваться методом [GET]/api/v1/docflows/incoming. В результате будет возвращен список документооборотов, соответствующих указанным фильтрам. Для получения актуальных документооборотов необходимо применить фильтрацию по дате создания ДО и/или по флагу "Просмотрено" - IsViewed.

  • [Опционально] Отметить документообороты как просмотренные.

    В случае пользования системой "просмотрено/не просмотрено", возможно отметить определенные ДО как просмотренные. Для этого необходимо воспользоваться методом [PUT]/api/v1/docflows/{docflowId}/viewed.

Действия с документооборотом (Любая сторона)​

  • [Обязательно] Получить информацию о возможных действиях над документооборотом.

    Чтобы узнать, какие действия можно выполнить над документооборотом, необходимо воспользоваться методом [GET]/api/v1/docflows/{docflowId}/actions. В результате вернется список доступных действий с документооборотом.

  • [Опционально] Получить полную информацию по документообороту.

    Для того, чтобы получить полную информацию по документообороту и список возможных действий, необходимо воспользоваться методом [GET]/api/v1/docflows/{docflowId}.

    Для того, чтобы получить архив с документами в рамках указанного документооборота, необходимо воспользоваться методом [GET]/api/v1/docflows/{docflowId}/documents/files.

  • [Опционально] Получить документ из документооборота.

    Для того, чтобы получить документ из документооборота, необходимо воспользоваться методом [GET]/api/v1/docflows/documents/{documentId}.

    Помимо этого есть возможность посмотреть информацию о транзакциях документооборота используя, метод [GET]/api/v1/docflows/{docflowId}/transactions.

    А так же есть возможность полуить печатный вид документа, метод [GET]/api/v1/docflows/documents/{documentId}/visualization.

  • [Условно-Обязательно] Получить список запросов на подпись.

    Документы, требующие подпись, находятся в списке запросов на подпись. Для получения запроса на подпись необходимо воспользоваться методом [GET]/api/v1/cryptography/requests. В результате вернется список запросов на подпись с информацией о документообороте, транзакции и документе.

    Примечание — является условно-обязательным, так как полностью зависит от типа документооборота и выполненных действий (например формирование ответного титула).

  • [Условно-Обязательно] Скачать документ для подписи.

    Для выполнения подписи сформированного документа (например ответного титула), его необходимо скачать с помощью следующего метода [GET]/api/v1/cryptography/requests/{requestId}/file. После скачивания документа его необходимо подписать.

    Примечание — является условно-обязательным, так как полностью зависит от типа документооборота и выполненных действий (например формирование ответного титула).

  • [Условно-Обязательно] Прикрепить подпись к запросу на подпись.

    Ранее вы уже использовали идентификатор запроса на подпись (RequestId), для того, чтобы скачать актуальную версию документа на подпись. Далее следует прикрепить подпись к документу используя следующий метод [POST]/api/v1/cryptography/requests/{requestId}/sign. В результате выполнения метода, подпись будет прикреплена к документу и выполнение документооборота продолжиться.

    ВАЖНО: Каждый раз когда документ будет требовать подписи, в данный список будет добавлять новый запрос на подпись.