|
2.1.1.3. XML для работы с приглашениями и таблицами данных контрагентов
|
|
|
Эти XML файлы используются для выполнения Регламента обмена приглашениями обмениваться документами с помощью Такском-Доклайнз. Предусмотрено два XML формата:
|
•
|
XML списка приглашенных и пригласивших к обмену контрагентов (используется для отслеживания статусов приглашений и для запросов на отправку приглашений по списку);
|
|
•
|
XML команд принятия и отклонения приглашения.
|
XSD схемы для создания и проверки XML можно скачать по ссылке:
Во всех этих XML файлах должны быть следующие параметры:
|
|
“Xmlns: http://api-invoice.taxcom.ru/ ContactActions” для команд принятия и отклонения приглашения или “Xmlns: http://api-invoice.taxcom.ru/contacts” для других.
|
|
|
“Encoding: utf-8”.
|
XML списка контактов
Файл XSD схемы: Contacts.xsd.
Этот XML файл содержит список приглашенных, пригласивших или приглашаемых контрагентов, а также информацию о подразделениях и сотрудниках организации с включенной опцией "Показывать контрагентам при заполнении данных получателя". В таком же виде поступает обновление списка "Мои контрагенты", включающее входящие приглашения от контрагентов за определённый период.
Contacts:
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
| ||||||||||||
|
Asof
|
Дата и время - стандарт XML (YYYY-MM-DDТHH:mm:ss.ttt)
|
Отметка времени
|
Да
| ||||||||||||
|
Contact
|
Комплексный тип.
См. следующую табл.
|
Содержит узел Contact для каждой записи обновления списка контактов.
См. следующую табл.
|
Нет
| ||||||||||||
|
TemplateID
|
Идентификатор типа GUID
|
Идентификатор шаблона письма приглашения Тег TemplateID опционален. Если его нет, то используется шаблон по умолчанию.
Указанный шаблон должен быть создан и записан в системе заранее.
Набор поддерживаемых маркеров шаблона, которые при формировании сообщения заменяются на реальные значения:
|
Нет
|
Contact:
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
|
|
State
|
Комплексный тип.
См. следующую табл.
|
Значение статуса входящего или исходящего приглашения.
См. следующую табл.
|
Нет
|
|
Name
|
Текст, до 255 символов
|
Полное или краткое наименование организации или индивидуального предпринимателя.
|
Да
|
|
Inn
|
Число, до 12 символов
|
ИНН юридического лица (10 цифр) или индивидуального предпринимателя (12 цифр). Система проверят правильность ИНН.
|
Да
|
|
Kpp
|
Число, до 9 символов
|
КПП юридического лица получателя (если получатель - индивидуальный предприниматель, то значение не задаётся);
|
Нет
|
|
SenderEmail
|
Текст, максимальная длина 32 символа
|
Адрес электронной почты отправителя в формате [имя_пользователя]@[сервер].[домен] (например, demo@mail.ru)
|
Нет
|
|
Email
|
Текст, до 32 символов
|
Адрес электронной почты контрагента в формате [имя_пользователя]@[сервер].[домен] (например, demo@mail.ru)
|
Да
|
|
Login
|
Текст, до 255 символов
|
Псевдоним пользователя в системе Такском-Доклайнз.
|
Нет
|
|
EDXClientId
|
Текст, до 46 символов
|
Идентификатор участника документооборота.
|
Нет
|
|
ExternalContactId
|
Текст, до 255 символов
|
Идентификатор контрагента во внешней учетной системе.
|
Нет
|
|
Comment
|
Текст, до 255 символов
|
Текст приглашения или комментарий
|
Нет
|
|
Agreements
|
Комплексный тип.
См. табл. "Agreements\Agreement" ниже.
|
Список договоров (контрактов) с контрагентом.
См. табл. ниже.
|
Нет
|
|
OperatorId
|
Текст, 3 символа
|
Идентификатор доверенного оператора электронного документооборота, присвоенный ФНС и состоящий из 3 символов, например, 2AL, 2BM, 2BE.
|
Нет
|
|
ScanFilename
|
Текст, до 100 символов
|
Имя файла вложения, включая расширение. Поддерживаемые типы расширения - ".pdf", ".jpg", ".png".
|
Нет
|
|
Scan
|
Текст, до 10 МБ
|
Файл вложения в кодировке Base64 (ограничение по объему - 10 МБ).
|
Нет
|
|
OrganizationStructure
|
Комплексный тип
См. табл. "OrganizationStructureType" ниже
|
Информация об организационной структуре
|
Нет
|
|
Active
|
Bool
|
Активность абонента. Абонент считается активным, если за предыдущие 6 месяцев зафиксирована его авторизация. В ином случае абонент считается неактивным. Для роумингового кабинета не отображается.
|
Нет
|
Наличие элемента «OperatorId» однозначно свидетельствует об отправке приглашения в роуминг, тому оператору, с которым необходим обмен документами.
Наличие элемента «OperatorId» запрещает использование элемента «EDXClientId».
Наличие одного из элементов «ScanFilename» или «Scan» влечёт за собой обязательное присутствие второго.
State:
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
|
|
Code
|
Перечисление, enum
|
Код статуса приглашения может принимать значения:
Sent - Приглашение отправлено контрагенту, ожидание ответа.
Accepted - Приглашение принято.
Rejected - Приглашение отклонено.
Error - Ошибка
Incoming - Контрагент ожидает ответа на приглашение.
|
Да
|
|
ErrorCode
|
Перечисление, enum
|
Если есть ошибка, данный код указывает её причину:
1.Некорректный формат ИНН контрагента. ErrorCode=InvalidInn.
Данное описание применяется при выявлении ошибки в ИНН.
2.Неверный формат email контакта. ErrorCode=InvalidEmail.
3.Невозможно отправить приглашение, так как контрагент не найден в базе абонентов компании "Такском", и адрес электронной почты задан неверно. ErrorCode = NotFound.
Данное описание применяется при невозможности обработать запрос.
4.Не найдены приглашения. ErrorCode = NotFound.
Данное значение применяется при попытке выполнения команд "принять" или "отклонить" для несуществующего входящего приглашения (передан логин контрагента, который не отправлял приглашений принимающей стороне).
|
Нет
|
|
Changed
|
Дата и время - стандарт XML (YYYY-MM-DDТHH:mm:ss.ttt)
|
Дата и время последнего изменения статуса контакта (приглашения).
|
Да
|
Внимание!
Поле State используется только в методах получения данных из списка приглашений (GetContactListUpdates, GetContacts).
|
Agreements\Agreement:
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
|
|
Number
|
Текст, до 255 символов
|
Номер договора/контракта
|
Нет
|
|
Date
|
Дата и время - стандарт XML (YYYY-MM-DDТHH:mm:ss.ttt)
|
Дата заключения договора/контракта
|
Нет
|
OrganizationStructureType
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
|
|
RootDepartment
|
Комплексный тип DepartmentStructuredInfoType
См. следующую таблицу.
|
Информация о головном подразделении
|
Да
|
DepartmentStructuredInfoType
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
|
|
SubDepartments
|
Содержит список вложенных подразделений.
Тип DepartmentStructuredInfoType
|
Информация о вложенных подразделениях
|
Нет
|
|
Employees
|
Содержит список сотрудников. Тип EmployeeShortInfoType
|
Информация о сотрудниках подразделения
|
Да
|
|
ID
|
Тип строка. 32 символа
|
Идентификатор подразделения
|
Да
|
|
Name
|
Тип строка. 1 - 255 символов
|
Наименование подразделения
|
Да
|
EmployeeShortInfoType
|
Атрибут
|
Тип
|
Описание
|
Обязательное присутствие
|
|
ID
|
Тип строка. 32 символа
|
Идентификатор сотрудника
|
Да
|
|
Name
|
Тип строка. 1 - 255 символов
|
Фамилия, имя, отчество сотрудника
|
Да
|
|
Position
|
Тип строка. 0 - 255 символов
|
Сведения о должности, занимаемой сотрудником
|
Да
|
XML команда принятия приглашения к обмену электронными документами и XML команда отклонения приглашения или отказа от обмена электронными документами имеют одинаковую структуру и используют упомянутые выше атрибуты.
Примеры
Пример XML файла заявки на отправку приглашений:
<?xml version="1.0" encoding="utf-8"?>
<Contacts xmlns="http://api-invoice.taxcom.ru/contacts">
<Contact>
<ExternalContactId>Client-993</ExternalContactId>
<Name>ООО "Нептун"</Name>
<Inn>7714698320</Inn>
<Email>GruzdevMV@taxcom.ru</Email>
<Comment>Это Иванов А. В.</Comment>
</Contact>
<TemplateID>1B3F3F57-96BD-40AB-83FE-8C63540EE8BD</TemplateID>
</Contacts>
Пример XML файла статусов приглашений и структуры организации
<?xml version="1.0" encoding="windows-1251"?>
<Contacts Asof="2016-06-02T16:02:25.597" xmlns="http://api-invoice.taxcom.ru/contacts">
<Contact>
<State Code="Accepted" ErrorCode="" Changed="2015-09-08T13:45:02.137">Контакт подтвержден, обмен документами доступен</State>
<Name>Индивидуальный предприниматель Нестриженко Филофей Дементьевич</Name>
<Inn>787419301376</Inn>
<Login>nestr</Login>
<EDXClientId>2AL-93D14F72-E2A4-4DE6-8859-03B70C547106-00000</EDXClientId>
<Email />
<Agreements />
<OrganizationStructure>
<RootDepartment ID="e33af870-d0d4-46cf-828a-fe1205c1f438" Name="Головное подразделение">
<SubDepartments />
<Employees>
<Employee ID="7fc990f9-08c9-44c9-b2a0-ccf8a76cace4">
<Name LastName="Иванов" FirstName="Петр" />
<Position />
</Employee>
</Employees>
</RootDepartment>
</OrganizationStructure>
</Contact>
<TemplateID>00000000-0000-0000-0000-000000000000</TemplateID>
</Contacts>
Приложение Такском-Ассистент может отправлять в систему Такском-Доклайнз команды принятия или отклонения приглашений
Пример XML файла команды принятия приглашения
(от абонента с идентификатором 2AL-2971F132-1B2A-401E-8ACC-02F11180F3FC-00000)
<?xml version="1.0" encoding="utf-8"?>
<ContactActions xmlns="http://api-invoice.taxcom.ru/ContactActions">
<ContactAction Type="Accept" EdxClientId="2AL-2971F132-1B2A-401E-8ACC-02F11180F3FC-00000" />
</ContactActions>
Пример XML файла команды отклонить приглашение
(от абонента с идентификатором 2AL-077966D6-2204-4714-B5B0-B63EDF6BAEB6-00000)
<?xml version="1.0" encoding="utf-8"?>
<ContactActions xmlns="http://api-invoice.taxcom.ru/ContactActions">
<ContactAction Type="Reject" EdxClientId="2AL-077966D6-2204-4714-B5B0-B63EDF6BAEB6-00000" />
</ContactActions>