Контрагенты
Диадок предоставляет возможность работать с контрагентами.
Работа со списком активных контрагентов
Активные контрагенты — это контрагенты, с которыми текущая организация установила партнерские отношения. Диадок хранит список таких контрагентов и позволяет им управлять.
Список активных контрагентов существует только для удобства поиска контрагентов и не влияет на возможность обмениваться документами. Обмен документами возможен с любыми организациями — в том числе с теми, которые не входят в список активных контрагентов. Исключение составляют следующие организации:
Организации, установившие в своих реквизитах настройку «Документы от контрагентов» в значение «Только организации из списка «Ваши контрагенты»». В этом случае отправить документ такой организации может только организация из списка ее активных контрагентов.
Организации, работающие с другими операторами ЭДО.
Список активных контрагентов в веб-интерфейсе Диадока упрощает пользователю выбор контрагента при выполнении операций. Кроме этого веб-интерфейс предоставляет возможность просматривать список активных контрагентов и редактировать его — приглашать контрагентов или удалять их из списка.
Та же функциональность доступна и через API. Действия, выполненные в веб-интерфейсе и через API будут зеркальными — то есть будут отражаться в обоих сервисах. Также API предоставляет возможность работать с группами контрагентов, подробнее в инструкции Группы контрагентов.
Если ваш список активных контрагентов небольшой и редко изменяется, вы можете не реализовывать работу со списком через API в вашем интеграционном решении: достаточно перед использованием интеграционного решения настроить список через веб-интерфейс.
Получение списка активных контрагентов
Чтобы получить текущий список активных контрагентов, используйте метод GetCounteragents (V3). При вызове метода не указывайте дополнительных параметров, в этом случае метод вернет весь список.
Пример HTTP-запроса метода GetCounteragents:
GET /V3/GetCounteragents?myBoxId={{myBoxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8
Пример тела ответа метода GetCounteragents:
{
"TotalCount": 1,
"Counteragents": [
{
"LastEventTimestamp": "2024-08-06T12:36:38.8979088Z",
"IndexKey": "40623A7CD898B2EA038D201F602A644F91B1B7AAD54CFAF3",
"Organization": {
"OrgIdGuid": "72c3b5bf-3a9f-4fb5-a3ef-112cb2b3a8dc",
"OrgId": "72c3b5bf-3a9f-4fb5-a3ef-112cb2b3a8dc",
"Inn": "9147414342",
"Kpp": "757645784",
"FullName": "Ромашка",
"ShortName": "Ромашка",
"JoinedDiadocTreaty": true,
"Boxes": [
{
"BoxId": "2a208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"BoxIdGuid": "2a208d03-2a60-4f64-91b1-b7aad54cfaf3",
"Title": "Ромашка",
"InvoiceFormatVersion": "v5_02",
"EncryptedDocumentsAllowed": false
}
],
"Ogrn": "9130523523154",
"FnsParticipantId": "2BM-9147414342-757645784-202407101104400484330",
"Address": {
"RussianAddress": {
"ZipCode": "620142",
"Region": "66",
"City": "Екатеринбург",
"Street": "Сажинская",
"Building": "11"
},
"AddressCode": ""
},
"Departments": [],
"IfnsCode": "6174",
"IsPilot": false,
"IsActive": true,
"IsTest": false,
"IsBranch": false,
"IsRoaming": false,
"IsEmployee": false,
"InvitationCount": 0,
"SearchCount": 0,
"Sociability": "AllOrganizations",
"IsForeign": false,
"HasCertificateToSign": true
},
"CurrentStatus": "IsMyCounteragent",
"LastEventTimestampTicks": 638585445988979088,
"MessageToCounteragent": "Примите приглашение к сотрудничеству",
"InvitationDocumentId": {
"MessageId": "215a68d5-28a0-4c6a-b9ec-cdba1530fd49",
"EntityId": "ad810ad2-8d4f-4fd9-9321-5359dfc0a37a"
},
"CounteragentGroupId": "ecd591dd-b56f-4178-ab4a-8a5532f231f7"
}
],
"TotalCountType": "Equal"
}
Приглашение контрагента к сотрудничеству
Чтобы пригласить контрагента к сотрудничеству, используйте метод AcquireCounteragent (V3).
Вызовите метод AcquireCounteragent (V3). Он отправит асинхронный запрос на установление отношений сотрудничества и вернет в ответе идентификатор операции, с помощью которого вы сможете проверить, успешно ли выполнена операция.
Если идентификатор ящика контрагента неизвестен, его можно получить с помощью метода GetOrganizationsByInnKpp: в ответе метод вернет структуру Organization, в поле
Boxesкоторой будет храниться идентификатор ящика контрагента. Этот идентификатор можно передать в теле запроса методаAcquireCounteragent.Пример HTTP-запроса метода AcquireCounteragent:
POST /V3/AcquireCounteragent?myBoxId={{boxId}} HTTP/1.1 Host: diadoc-api.kontur.ru Authorization: Bearer {{access_token}}Пример тела запроса метода AcquireCounteragent:
{ "BoxId": "{{counteragentBoxId}}", "MessageToCounteragent": "Примите приглашение к сотрудничеству", "InvitationDocument": { "FileName": "invitation", "SignedContent": { "Content": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0...NC50Ls+", // содержимое XML-файла в кодировке base-64 "Signature": "MIIN5QYJKoZIhvcNAQcCoIIN1jCCDdIA...kA9MJfsplqgW", // содержимое файла подписи в кодировке base-64 } } }
Пример тела ответа метода AcquireCounteragent:
{ "TaskId": "997818e1-9420-4f8f-857f-c86fb070d0a7" }
Вызовите метод AcquireCounteragentResult (V2), передав ему в качестве параметра идентификатор, полученный на предыдущем этапе. В ответе метод вернет информацию об отправленном приглашении.
Пример HTTP-запроса метода AcquireCounteragentResult:
GET /V2/AcquireCounteragentResult?taskId=997818e1-9420-4f8f-857f-c86fb070d0a7 HTTP/1.1 Host: diadoc-api.kontur.ru Authorization: Bearer {{access_token}}Пример тела ответа метода AcquireCounteragentResult:
{ "BoxId": "1f208d03-2a60-4f64-91b1-b7aad54cfaf3", "InvitationDocumentId": { "MessageId": "88d108be-27ec-4808-8a38-8062e7cf4988", "EntityId": "ce1d22da-f9e8-4c4c-af34-09bc94ad1fdd" } }
Когда ваш контрагент примет приглашение к сотрудничеству, он появится в списке активных контрагентов.
Разрыв отношений с контрагентом
Чтобы разорвать партнерские отношения с контрагентом и удалить его из списка активных контрагентов, использйте метод BreakWithCounteragent (V2).
Пример HTTP-запроса метода BreakWithCounteragent:
POST /V2/BreakWithCounteragent?myBoxId={{myBoxId}}&counteragentBoxId={{counteragentBoxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Получение информации о контрагенте
Чтобы получить информацию о контрагенте и статусе партнерства с ним, используйте метод GetCounteragent (V3).
Пример HTTP-запроса метода GetCounteragent:
GET /V3/GetCounteragent?myBoxId={{myBoxId}}&counteragentBoxId={{counteragentBoxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8
Пример тела ответа метода GetCounteragent:
{
"LastEventTimestamp": "2024-08-06T12:36:38.8979088Z",
"Organization": {
"OrgIdGuid": "72c3b5bf-3a9f-4fb5-a3ef-112cb2b3a8dc",
"OrgId": "72c3b5bf-3a9f-4fb5-a3ef-112cb2b3a8dc",
"Inn": "9147414342",
"Kpp": "757645784",
"FullName": "Ромашка",
"ShortName": "Ромашка",
"JoinedDiadocTreaty": true,
"Boxes": [
{
"BoxId": "2a208d032a604f6491b1b7aad54cfaf3@diadoc.ru",
"BoxIdGuid": "2a208d03-2a60-4f64-91b1-b7aad54cfaf3",
"Title": "Ромашка",
"InvoiceFormatVersion": "v5_02",
"EncryptedDocumentsAllowed": false
}
],
"Ogrn": "9130523523154",
"FnsParticipantId": "2BM-9147414342-757645784-202407101104400484330",
"Address": {
"RussianAddress": {
"ZipCode": "620142",
"Region": "66",
"City": "Екатеринбург",
"Street": "Сажинская",
"Building": "11"
},
"AddressCode": ""
},
"Departments": [
{
"DepartmentId": "00000000-0000-0000-0000-000000000000",
"ParentDepartmentId": "",
"Name": "Головное подразделение",
"Abbreviation": "ГП",
"Address": {
"RussianAddress": {
"Region": ""
},
"AddressCode": ""
},
"IsDisabled": false
}
],
"IfnsCode": "6174",
"IsPilot": false,
"IsActive": true,
"IsTest": false,
"IsBranch": false,
"IsRoaming": false,
"IsEmployee": false,
"InvitationCount": 0,
"SearchCount": 0,
"Sociability": "AllOrganizations",
"IsForeign": false,
"HasCertificateToSign": true
},
"CurrentStatus": "IsMyCounteragent",
"LastEventTimestampTicks": 638585445988979088,
"MessageToCounteragent": "Примите приглашение к сотрудничеству",
"InvitationDocumentId": {
"MessageId": "215a68d5-28a0-4c6a-b9ec-cdba1530fd49",
"EntityId": "ad810ad2-8d4f-4fd9-9321-5359dfc0a37a"
},
"CounteragentGroupId": "ecd591dd-b56f-4178-ab4a-8a5532f231f7"
}
Получить ленту событий по изменению отношений с контрагентом можно с помощью метода GetCounteragentEvents (V1). Подробнее в инструкции Лента событий по контрагентам.
Получение сертификатов контрагента
Если вы хотите отправить контрагенту зашифрованный документ, вам нужно выбрать сертификат, на который будет зашифрован этот документ. Для этого вы можете получить все сертификаты контрагента и выбрать из них подходящий.
Организация может запросить список сертификатов контрагента только если у нее включена возможность отправки зашифрованных документов. Эта возможность указана в поле Organization.Box.EncryptedDocumentsAllowed.
Чтобы получить сертификаты контрагента, используйте метод GetCounteragentCertificates (V2).
Пример HTTP-запроса метода GetCounteragentCertificates:
GET /V2/GetCounteragentCertificates?myBoxId={{myBoxId}}&counteragentBoxId={{counteragentBoxId}} HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: Bearer {{access_token}}
Accept: application/json; charset=utf-8
Пример тела ответа метода GetCounteragentCertificates:
{
"Certificates": [
{
"RawCertificateData": "MIIIyjCCCHegAwIBAgIRAdD...Brfw=="
}
]
}
Поиск контрагентов
Найти контрагентов, не входящих в список активных контрагентов, можно с помощью методов для поиска организаций:
GetOrganizationsByInnKpp — возвращает организации с указанными ИНН и КПП.
GetOrganizationsByInnList (V2) — возвращает организации и их статусы по указанному списку ИНН.
GetBox — по идентификатору ящика возвращает информацию об организации, которой он принадлежит.
GetOrganization — по идентификатору организации возвращает принадлежащий ей ящик и ее данные: например, ИНН, КПП, название и т.п.