Diadoc API
Diadoc API
Table of contents
Basic notions
• User – certificate owner, subject of athorization process.
• Company – in Diadoc - legal entity (or sole proprietor) from real world.
• Message – batch containing documents and signatures for sending via Diadoc.
• Box – message routing in Diadoc. Messages go between boxes (NOT between companies or NOT between users).
Relations between entities:
• Box is owned by one company. Otherwise answer to question “ Who is the recipient” is not clear, that is not good.
• Company may have several boxes. Accounting department, partners’ reports, etc. People from various departments can be engaged into that.
• User may have access to several boxes. For example, manager wants to control work of his subordinates from various departments.
• Several users may have access to one box. Various users process information from the box working in different shifts.
Authorization
Most intergrator interface commands require authorization. Commands require authorization token as an obligatiry authorization condition. Authorization token is a byte array uniquely identifying the user.
Moreover, all the integrator interface methods shall include so called “developer key” – unique string integrator identifier. You can receive it by sending a request to diadoc-api@skbkontur.ru. Integrator shall not tansfer its “developer key” to the third parties.
Standart HTTP-heading Authorization is used for transfer of authorization information with each request. Diadoc authentication scheme is called DiadocAuth. It is characterized by the following:
• ddauth_api_client_id – designed for developer key transfer;
• ddauth_token – designed for authorization token transfer.
Parameter values are separated from names by '='. Characteristics are separated by ','. For example:
Authorization: DiadocAuth
ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a,
ddauth_token=3IU0iPhuhHPZ6lrlumGz4pICEedhQ1XmlMN1Pk8z0DJ51MXkcTi6Q3CODCC4xTMsjPFfhK6XM4kCJ4JJ42hlD499/Ui5WSq6lrPwcdp4IIKswVUwyE0ZiwhlpeOwRjNrvUX1yPrxr0dY8a0w8ePsc1DG8HAlZce8a0hZiWylMqu23d/vfzRFuA==
Let’s have a look at a sequence of actions necessary at reference to Diadoc integrator interface functions. First, Diadoc client shall receive authorization token using Authenticate command. Take note, that parameter ddauth_api_client_id of HTTP heading Authorization shall include developer key received while registration. Corresponding HTTP-request is the following:
POST HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: DiadocAuth ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a
Content-Length: 1252
Connection: Keep-Alive
Positive server reply looks like the following:
HTTP/1.1 200 OK
Content-Length: 598
To receive authorization token the client shall decode Authenticate command reply body by privacy key corresponding to user certificate. Received byte array shall be encoded into Base64-string. Further, it is necessary to add HTTP heading Authorization with parameters ddauth_api_client_id= and ddauth_token= to each HTTP-request to Diadoc.
For example, command to receive list of boxes available for the user is translated into the following HTTP request:
POST HTTP/1.1
Host: diadoc-api.kontur.ru
Authorization: DiadocAuth ddauth_api_client_id=testClient-8ee1638deae84c86b8e2069955c2825a,ddauth_token=3IU0iPhuhHPZ6lrlumGz4pICEedhQ1XmlMN1Pk8z0DJ51MXkcTi6Q3CODCC4xTMsjPFfhK6XM4kCJ4JJ42hlD499/Ui5WSq6lrPwcdp4IIKswVUwyE0ZiwhlpeOwRjNrvUX1yPrxr0dY8a0w8ePsc1DG8HAlZce8a0hZiWylMqu23d/vfzRFuA==
For commands designed to work with a stated box (i.e. receive and send messages) control over box access has the following procedure:
1. Parameter ddauth_token is taken from current request HTTP-heading Authorization. This value is decoded and so we get user identifier. If any of the actions mentioned above is failed to be completed (for example, request does not contain HTTP-heading Authorization or this heading does not contain parameter ddauth_token, or parameter value is damaged or token expired, etc.) then error code 401 (Unauthorized) appears. If request contains incorrect ddauth_api_client_id, then error 401 (Unauthorized) appears.
2. User identifier leads to lots of boxes to which the user has access. This is the same set as returned by GetBoxesByAuthToken method.
3. Box identifier is taken from current request parameters. If box identifier does not belong to the set received on the previous step, then error code 403 (Forbidden) is returned.
4. Otherwise access is granted.
Operations suported
Authenticate
GetBoxesByAuthToken
GetBoxesByInnKpp
GetBoxInfo
GetNewEvents
GetEvent
GetMessage
GetEntityContent
PostMessage
PostMessagePatch
GenerateInvoiceDocumentReceiptXml
GenerateInvoiceCorrectionRequestXml
PostDraft
Moreover, command Help enables receiving actual list of all the operations supported by the service.
If you add suffix ?proto to the name of any command you will get actual decsription of all the data structures (see Data structures), necessary to use this command. For example, at request description of BoxInfo data structure will be given.
Authenticate
Resource name : /Authenticate
HTTP method: POST
Request string characteristics:
• login: user account name at authorization via login/password (may be absent);
• password: user account password at authorization by login/password (is obligatory if parameter login is present);
Request shall include HTTP heading Authorization with ddauth_api_client_id parameter (see Authorization).
If authorization requires certificate request body shall contain X.509 user certificate serialized in DER. Otherwise request body shall be empty.
In the case of successful request execition reply body contains authorization token. If authorization contains login/ password, reply body shall be interpretated as a string in UTF-8 coding. If authorization requires certificate then issued token will be encoded to user certificate. In this case reply body shall be interpreted as CMS EnvelopedData structure in DER – coding.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) – there is no HTTP heading Authorization in the request or heading does not contain parameter ddauth_api_client_id or developer key transferred in it is not registered in Diadoc;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GetBoxesByAuthToken
Resource name: /GetBoxesByAuthToken
HTTP method: GET
Request string characteristics:
• outputFormat: data output format, may be absent. Values possible: xml, protobuf (on default - protobuf).
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains list of all the boxes accessible by user – authorization token owner, serialized in the present format:
• if there is no outputFormat parameter in request string or its value is equal to protobuf – data is returned serialized to protobuffer BoxList;
• if outrutFormat parameter value in request string is equal to xml – data is returned in xml format, for example:
•
•
•
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GetBoxesByInnKpp
Resource name : /GetBoxesByInnKpp
HTTP method: GET
Request string characteristics:
• inn: company TIN;
• kpp: company KPP, may be absent;
• outputFormat: data output format, may be absent. Values possible: xml, protobuf (at default - protobuf).
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains list of all the boxes owned by companies with TIN and KPP settled in the present format:
• if there is no outputFormat parameter in request string or its value is equal to protobuf – data is returned serialized to protobuffer BoxList;
• if outrutFormat parameter value in request string is equal to xml – data is returned in xml format, for example:
•
•
•
If kpp parameter is absent in request string, list of all the boxes of all the companies with stated TIN wiil be given.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GetBoxInfo
Resource name: /GetBoxInfo
HTTP метод: GET
Request string characteristics:
• boxId: box identifier.
• outputFormat: data output format, may be absent. Values possible: xml, protobuf (at default - protobuf).
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains referenced data for box with identifier boxId serialized in the present format:
• if there is no outputFormat parameter in request string or its value is equal to protobuf – data is returned serialized to protobuffer BoxList;
• if outrutFormat parameter value in request string is equal to xml – data is returned in xml format, for example:
Possible HTTP return codes:
200 (OK) - operation completed successfully;
400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
404 (Not Found) – box with identifier stated is not found in the reference book;
405 (Method not allowed) - HTTP method used is not allowed;
500 (Internal server error) - unforseen error appeared while request processing.
GetNewEvents
Resource name : /GetNewEvents
HTTP method: GET
Request string characteristics:
• boxId: box identifier;
• afterEventId: identifier of the last event received (may be absent);
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains list of events in the box boxId following the afterEventId event chronologically. Event with identifier afterEventId is not in the list. The list is given in the form of serialized data structure BoxEventList. Content relating to the evens from the list is not saved in data structure, i.e. only metainformation on news is returned. Due to this reply to request will have predicrable and small size. If the list contains more than 100 items, then first 1000 items are returned in the reply and BoxEventList.TotalCount field contains total number of new events. If request contains no afterEventId parameter, then the method returns the oldest events from the box boxId.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GetEvent
Resource name : /GetEvent
HTTP method: GET
Request string characteristics:
• boxId: box identifier;
• eventId: event identifier;
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains event with identifier eventId from box boxId, serialized into protobuffer BoxEvent. All the content relating to the present event (in particular, attachment and signature bodies) is loaded to protobuffer, if possible. But if total attachment volume in requested event exceeds 1Mb, these attachments are not included into protobuffer (their Entity.Content.Data field will be equal to NULL). Other attachment bodies can be received with the help of GetEntityContent method.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 404 (Not Found) - there are no events with present identifier in the box stated;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GetMessage
Resource name : /V2/GetMessage
HTTP метод: GET
Request string characteristics:
• boxId: box identifier;
• messageId: message identifier;
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains message with identifier messageId from box boxId, serialized into protobuffer Message. Message structure includes entities of all the events relating to message messageId. All the content relating to the present message (in particular, attachment and signature bodies) is loaded to protobuffer, if possible. But if total attachment volume in requested event exceeds 1Mb, these attachments are not included into protobuffer (their Entity.Content.Data field will be equal to NULL). Other attachment bodies can be received with the help of GetEntityContent method.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 404 (Not Found) - there are no events with present identifier in the box stated;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GetEntityContent
Resource name : /GetEntityContent
HTTP method: GET
Request string characteristics:
• boxId: box identifier;
• messageId: message identifier;
• entityId: entity identifier;
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains entity content (for example, attachment body) with identifier entityId from the message with identifier message Id in the box boxId.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 404 (Not Found) – there is no message with identifier messageId in the box stated, or there is no entity with identifier entityId in the message stated;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
PostMessage
Resource name : /V2/PostMessage
HTTP method: POST
Request string characteristics: NONE
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Request body shall contain message sent serialized into MessageToPost ptorobuffer.
Reply body cintains message sent serialized into Message protobuffer.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 409 (Conflict) – trying to send copy of message;
• 500 (Internal server error) - unforseen error appeared while request processing.
Request processing algorithm:
1. MD5-hash from request body is calculated.
2. If hash is contained in cache of recently sent messages, than error code 409 (Conflict) is returned. This status code means that client tried to send one message several times because for example didn’t receive any answer from the server on first request.
3. Request body is deserializes into MessageToPost structure. If failed, then error code 400 (Bad Request) is returned.
4. If received structure MessageToPost fails to pass format and logic control, then error code 400 (Bad Request) is returned.
5. The message is being sent.
6. MD5-hash of request body is recorded to cache of recently sent messages.
7. A message sent is serialized into Message protobuffer and given to client.
PostMessagePatch
Resource name : /V2/PostMessagePatch
HTTP method: POST
Request string characteristics: NONE
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Request body shall contain patch to message sent serialized into MessagePatchToPost ptorobuffer.
Reply body cintains patch to message sent serialized into MessagePatch protobuffer.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 409 (Conflict) - trying to send copy of message;
• 500 (Internal server error) - unforseen error appeared while request processing.
Request processing algorithm is the same as in PostMessage method.
GenerateInvoiceDocumentReceiptXml
Resource name : /GenerateInvoiceDocumentReceiptXml
HTTP method: GET
Request string characteristics:
• boxId: box identifier;
• messageId: message identifier;
• attachmentId: document entity identifier, for which it is necessaty to issue receipt request;
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body contains XML-file with notice on receipt of attachmentId document from messageId message in the box boxId. File with notice is issued in the format complying with the requirements on documents receipt notice stipulated by e-invoices interchange procedure. Name of file with notice (required by the format stated) is transferred in standard HTTP-heading Content-Disposition.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
GenerateInvoiceCorrectionRequestXml
Resource name : /GenerateInvoiceCorrectionRequestXml
HTTP method: POST
Request string characteristics:
• boxId: box identifier;
• messageId: message identifier;
• attachmentId: invoice entity identifier, for which it is necessaty to issue correction request;
• errorMessage: main error message which shall be included into correction request;
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Reply body may contain additional data forinvoice correction request in the form of serialized structure InvoiceCorrectionInfo.
Reply body contains XML-file with invoice correction request attachmentId from messageId message in the box boxId. File with notice is issued in the format complying with the requirements on documents receipt notice stipulated by e-invoices interchange procedure. Name of file with notice (required by the format stated) is transferred in standard HTTP-heading Content-Disposition.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
PostDraft
Resource name : /PostDraft
HTTP method: POST
Request string characteristics:
• fromBoxId – sender box identifier;
• toBoxId – receipients box identifier (may be absent);
• draftId – existing draft identifier (may be absent, in this case ner draft will be created);
• attachmentType – attachment type (may be absent, value on default - Nonformalized),
Values possible: "Nonformalized", "Invoice";
• fileName – name of file;
• comment – comments to file (may be absebt);
• needRecipientSignature – if return signature required or not (may be absent);
Request shall contain HTTP-heading Authorization with data necessary for authorization.
Request body contains file content.
Reply body contains draft identifier as a string.
Possible HTTP return codes:
• 200 (OK) - operation completed successfully;
• 400 (Bad Request) - data from the request is in bad format or lacks obligatory chatacteristics;
• 401 (Unauthorized) - request lacks Authorization HTTP-heading or heading contains incorrect authorization data;
• 403 (Forbidden) - access to the box with stated authorization token is forbidden;
• 404 (Not found) - draft with identifier stated is not found;
• 405 (Method not allowed) - HTTP method used is not allowed;
• 500 (Internal server error) - unforseen error appeared while request processing.
Method creates new draft or adds file to already existing draft (if at processing of request parameter draftId is transferred).
Data structures
BoxList
Message
MessagePatch
Entity
BoxEvent
BoxEventList
MessageToPost
MessagePatchToPost
InvoiceCorrectionInfo
For serialization/ deserialization of data structure transferred in HTTP requests and replies composing Diadoc integration interface, Google Protocol Buffers mechanism is used. Description of Protocol Buffers language syntax is shown here.
There are ready libraries for various platforms and programming languages, solving the task of serialization/ deserialization of relative data structures into protobuffers. Here are some of them:
• C++, Java, Python – Google official realizatione;
• Microsoft® .NET – protobuf-net project ;
• And others – many references.
BoxList
message BoxList {
repeated BoxInfo Boxes = 1;
}
message BoxInfo {
required string BoxId = 1;
required string BoxName = 2;
required OrgInfo Org = 3;
}
message OrgInfo {
required string Name = 1;
required string Inn = 2;
required string Kpp = 3; // empty string if KPP is absent.
}
BoxInfo data structure contains information on one box in Diadoc: its identifier, readable name and information on company – box owner.
Message
message Message {
required string MessageId = 1;
required sfixed64 TimestampTicks = 2;
required sfixed64 LastPatchTimestampTicks = 3;
required string FromBoxId = 4;
required string FromTitle = 5;
required string ToBoxId = 6;
required string ToTitle = 7;
repeated Entity Entities = 8;
}
Message data structure is one message in Diadoc:
• MessageId - unique message identifier.
• TimestampTicks - message creation time mark. Is an integer number of tics (100-nanosecond intervals) passed from the time moment 00:00:00 01.01.0001. This mark is a time moment without taking into account time zone, i.e. it shall be considered as UTC-time. For example, to convert this mark to .NET-structure System.DateTime, it is possible to use the following code on C# language: new DateTime(TimestampTicks, DateTimeKind.Utc).
• LastPatchTimestampTicks – latest patch (attachment) creation time mark to the present message. Is an integer number of tics (100-nanosecond intervals) passed from the time moment 00:00:00 01.01.0001. This mark is a time moment without taking into account time zone, i.e. it shall be considered as UTC-time.
• FromBoxId – message sender box identifier.
• ToBoxId – message recipient box identifier.
• FromTitle - sender mailbox human readable name.
• ToTitle - recipient mailbox human readable name.
• Entities - list of entities composing present message (including entities from patches to it). Each entity is presented by structure of Entity type.
MessagePatch
message MessagePatch {
required string MessageId = 1;
required sfixed64 TimestampTicks = 2;
repeated Entity Entities = 3;
}
MessagePatch data structure is an attachment (patch) to message in Diadoc:
• MessageId – identifier of message with the present patch.
• TimestampTicks – patch creation time mark. Is an integer number of tics (100-nanosecond intervals) passed from the time moment 00:00:00 01.01.0001. This mark is a time moment without taking into account time zone, i.e. it shall be considered as UTC-time. For example, to convert this mark to .NET-structure System.DateTime, it is possible to use the following code on C# language: new DateTime(TimestampTicks, DateTimeKind.Utc).
• Entities – list of entities composing present patch to message. Each entity is presented by structure of Entity type.
Entity
message Entity {
required EntityType EntityType = 1;
required string EntityId = 2;
optional string ParentEntityId = 3;
optional Content Content = 4; // value is absent only when entity has no content
optional AttachmentType AttachmentType = 5 [default = Nonformalized];
optional string FileName = 6;
optional bool NeedRecipientSignature = 7 [default = false];
optional string SignerBoxId = 8;
}
message Content {
required sfixed32 Size = 1; // -1 is content size unknown
optional bytes Data = 2; // value is absent only when content is not included into protobuffer due to large size and may be received by GetEntityContent(...)method
}
enum EntityType {
Attachment = 1;
Signature = 2;
}
enum AttachmentType {
Nonformalized = 0;
Invoice = 1;
InvoiceReceipt = 2;
InvoiceConfirmation = 3;
InvoiceCorrectionRequest = 4;
AttachmentComment = 5;
DeliveryFailureNotification = 6;
//Unknown types shall be processed as Nonformalized
}
Entity data structure is one entity included into message or attachment to message:
• EntityType defines type of entity; variants possible: Attachment (file – attachment to the message), Signature (digital e-signature under attachment).
• EntityId - unique entity identifier.
• ParentEntityId – parent entity identifier. For example, for Signature entity it is identifier of corresponding Attachment entity.
• EntityType defines entity type; possible variants: Attachment (file – attachment to message), Signature (digital e-signature under attachment).
• AttachmentType defines type of attachment (is meaningful only for entities of Attachment type); variants possible: Nonformalized (nonformalized document), Invoice (invoice), InvoiceReceipt (invoice receipt notice, EDI supplier confirmation or invoice correction request), InvoiceConfirmation (EDI supplier confirmation), InvoiceCorrectionRequest (invoice correction request), AttachmentComment (text comments on other entity - attachment), DeliveryFailureNotification (delivery failure notification).
• Content – entity content. Content.Size field defines content size in bytes. This byte array shall be interpreted depending on EntityType type of entity and AttachmentType type of attachment. Content of Signature entity type is digital e-signature in CMS SignedData format DER-coding. For entity of Attachment type and attachment type Nonformalized – it is just binary content of initial file. Entities of Attachment type with attachments of Invoice, InvoiceReceipt, InvoiceConfirmation and InvoiceCorrectionRequest types are XML-files, interchanged by seller and buyer while issuing/ receipt of e-invoices in accordance with the procedure stated by Ministry of Finance of RF. Finally, for entities of Attachment type ane attachments of AttachmentComment or DeliveryFailureNotification types Content.Data byte array shall be interpreted as string in UTF-8 coding.
• FileName – for entity of Attachment type it is initial file name. For other entity types this field is empty.
• NeedRecipientSignature - flag showing request of recipient signature under this entity; is meaningful only for entities of Attachment type with Nonformalizes attachment type.
• SignerBoxId – for entity of Signature type it is signer box identifier. For other entity types this field is empty.
BoxEvent
message BoxEvent {
required string EventId = 1;
optional Message Message = 2;
optional MessagePatch Patch = 3;
}
BoxEvent data structure is one event in Diadoc box:
• EventId - unique event identifier.
• Message – structure of Message type, containing data on the event matching with appearance of new message in the box.
• Patch – structure of MessagePatch type containing data on the event matching with appearance of patches to corresponding message in the box.
In BoxEvent structure only one of Message and Patch fields may differ from NULL.
BoxEventList
message BoxEventList {
repeated BoxEvent Events = 1;
optional int32 TotalCount = 2;
}
BoxEventList data structure is the list of events BoxEvent, returned by GetNewEvents method. BoxEventList.TotalCount field contains total number of events satisfying the request.
MessageToPost
message MessageToPost {
required string FromBoxId = 1;
required string ToBoxId = 2;
repeated InvoiceAttachment Invoices = 3;
repeated NonformalizedAttachment Attachments = 4;
}
message InvoiceAttachment {
required SignedContent SignedContent = 1;
required string FileName = 2;
optional string Comment = 3;
}
message NonformalizedAttachment {
required SignedContent SignedContent = 1;
required string FileName = 2;
optional string Comment = 3;
optional bool NeedRecipientSignature = 4 [default = false];
}
message SignedContent {
required bytes Content = 1;
required bytes Signature = 2;
}
MessageToPost data structure is a message to be sent via Diadoc with the help of PostMessage method:
• FromBoxId – message sender box identifier.
• ToBoxId – message recipient box identifier. Shall differ from sender box identifier.
• Invoices – list of invoices in sending message.
• Attachments – list of non – formalized documents in sending message.
InvoiceAttachment data structure is an invoice in sending message:
• SignedContent - content of invoice file with digital e-signature under it. Digital e – signature shall be in CMS SignedData format DER-coding.
• FileName – invoice file name.
• Comment – optional text comments to invoice.
NonformalizedAttachment data structure is one non-formalized document in sending message:
• SignedContent - content of document file with digital e-signature under it. Digital e – signature shall be in CMS SignedData format DER-coding.
• FileName – sending document file name.
• Comment – optional text comments to the document.
• NeedRecipientSignature – flag showing request of recipient signature under sending document.
MessagePatchToPost
message MessagePatchToPost {
required string BoxId = 1;
required string MessageId = 2;
repeated ReceiptAttachment Receipts = 3;
repeated CorrectionRequestAttachment CorrectionRequests = 4;
repeated RequestedSignature RequestedSignatures = 5;
}
message ReceiptAttachment {
required string DocumentId = 1;
required SignedContent SignedContent = 2;
required string FileName = 3;
}
message CorrectionRequestAttachment {
required string InvoiceId = 1;
required SignedContent SignedContent = 2;
required string FileName = 3;
}
message RequestedSignature {
required string AttachmentId = 1;
required bytes Signature = 2;
}
message SignedContent {
required bytes Content = 1;
required bytes Signature = 2;
}
MessagePatchToPost data structure is patch to message to be sent via Diadoc with the help of PostMessagePatch method:
• BoxId - box identifier, where the initial message locates.
• MessageId - message identifier with patch sent.
• Receipts – list of document receipt notices to be sent, stipulated by e-invoices interchange procedure.
• CorrectionRequests – list of invoice correction requests to be sent, stipulated by e-invoice interchange procedure.
• RequestedSignatures – list of signatures requested for non-formalized documents.
ReceiptAttachment data structure is one document receipt notice in patch sent:
• DocumentId - identifier of document with notice. This is an identifier of corresponding entity from parent message (EntityId field in Entity structure).
• SignedContent - content of notice file with digital e-signature under it. Digital e – signature shall be in CMS SignedData format DER-coding.
• FileName – notice file name.
CorrectionRequestAttachment data structure is one invoice correction notice in patch sent:
• InvoiceId – identifier of invoice with notice. This is an identifier of corresponding entity from parent message (EntityId field in Entity structure).
• SignedContent – content of notice file with digital e-signature under it. Digital e – signature shall be in CMS SignedData format DER-coding.
• FileName – notice file name.
RequestedSignature data structure is one requested signature in patch sent:
• AttachmentId – identifier of the document with signature. This is an identifier of corresponding entity from parent message (EntityId field in Entity structure).
• Signature – is digital e-signature itself, in CMS SignedData format DER-coding.
InvoiceCorrectionInfo
message InvoiceCorrectionInfo {
optional string InfoMessage = 1;
repeated InvoiceErrorInfo Errors = 2;
}
message InvoiceErrorInfo {
required string ErrorMessage = 1;
optional string PathToBadElement = 2;
}
InvoiceCorrectionInfo data structure is initial data used to form invoice correction request using GenerateInvoiceCorrectionRequestXml method:
• InfoMessage – optional informational message.
• Errors – list of error messages.
InvoiceErrorInfo data structure is one error message in invoice:
• ErrorMessage –obligatory error message text.
• PathToBadElement – optional path to bad XML-element in invoice.
ActiveX component
List of objects
User – created objects
Diadoc.DiadocApi2
Diadoc.CryptApi
Diadoc.Api.MessageToPost
Diadoc.Api.InvoiceAttachment
Diadoc.Api.NonformalizedAttachment
Diadoc.Api.SignedContent
Diadoc.Api.MessagePatchToPost
Diadoc.Api.RequestedSignature
Diadoc.Api.ReceiptAttachment
Diadoc.Api.CorrectionRequestAttachment
Diadoc.Api.CorrectionInfo
Diadoc.Api.Drafts
Objects returned by API methods
BoxInfo
OrgInfo
BoxEventList
BoxEvent
Message
Entity
Content
MessagePatch
GeneratedFile
Certificate
ActiveX component DiadocApi.dll is designed to simplify integration with other products. It is a cover for operations realized by Diadoc API through HTTP protocol.
User – created objects
Diadoc.DiadocApi2
Main object for operation with API.
Methods:
• void Initialize(string apiClientId, string serverUrl)
Object initialization. This method shall be used in the beginning of work with object.
Characteristics:
• apiClientId: developer key
Type: string
• serverUrl: API server address
Type: string
Return value: none
• void SetProxyCredentials(string proxyUser, string proxyPassword)
Defines user name and password for proxy if required
Characteristics:
• proxyUser: user name
Type: string
• proxyPassword: password
Type: string
Return value: none
• void EnableSystemProxyUsage()
Enables usage of proxy – server (proxy is allowed on default). Characteristics are taken from Internet Explorer settings.
Characteristics: none
Return value: none
• void DisableSystemProxyUsage()
Forbids usage of proxy – server (proxy is allowed on default).
Characteristics: none
Return value: none
• string AuthenticateWithCertificate(string thumbprint)
Realizes authentication on the basis of certificate, returns token which further shall be transferred to all the methods.
Characteristics:
• thumbprint: user certificate thumbprint
Type: string
Return value: authentication token
• string AuthenticateWithPassword(string login, string password)
Authenticates on the basis of login/ password, returns token which further shall be transferred to all the methods.
Characteristics:
• login: user account name
Type: string
• password: user account password
Type: string
Return value: authorization token
• BoxInfo[] GetBoxes(string authToken)
Returns list of boxes available for the user
Characteristics:
• authToken: authentication token
Type: string
Return value: BoxInfo array
• BoxInfo[] GetBoxesByInnKpp(string inn, string kpp)
Search of information on stated company boxes. Authentication not required.
Characteristics:
• inn: string containing TIN of the company.
Type: string
• kpp: string containing KPP of the company.
Type: string
Return value: BoxInfo array
• BoxInfo GetBoxInfo(string boxId)
Gets information on the box on the basis of identifier.
Characteristics:
• boxId: box identifier
Type: string
Return value: BoxInfo
• BoxEventList GetNewEvents(string authToken, string boxId, string afterEventId)
Returns list of events happened in the box after the event with identifier stated.
Characteristics:
• authToken: authentication token
Type: string
• boxId: box identifier
Type: string
• afterEventId: event identifier
Type: string
Return value: BoxEventList
• BoxEvent GetEvent(string authToken, string boxId, string eventId)
Gets information on the event on the basis of its identifier.
Characteristics:
• authToken: authentication token
Type: string
• boxId: box identifier
Type: string
• eventId: event identifier
Type: string
Return value: BoxEvent
• void SaveEntityContent(string authToken, string boxId, string messageId, string entityId, string fileName)
Saves entity content (for example, document or digital e-signature) into file.
Characteristics:
• authToken: authentication token
Type: string
• boxId: box identifier
Type: string
• messageId: message identifier
Type: string
• entityId: entity identifier
Type: string
• fileName: name of file to save the content
Type: string
Return value: none
• Message PostMessage(string authToken, MessageToPost message)
Sends new message.
Characteristics:
• authToken: authentication token
Type: string
• message: initial message
Type: MessageToPost
Return value: Message sent
• MessagePatch PostMessagePatch(string authToken, MessagePatchToPost patch)
Sends new patch to message.
Characteristics:
• authToken: authentication token
• patch: patch to message.
Type: MessagePatchToPost
Return value: MessagePatch
• GeneratedFile GenerateInvoiceDocumentReceiptXml(string authToken, string boxId, string messageId, string attachmentId)
Generates file with document receipt request (invoice, supplier confirmation or correction request).
Characteristics:
• authToken: authentication token.
• boxId: box identifier.
• messageId: message identifier, содержащего вложение.
• attachmentId: attachment identifier receipt request to which it is necessary to generate.
Return value: GeneratedFile
• GeneratedFile GenerateInvoiceCorrectionRequestXml(string authToken, string boxId, string messageId, string attachmentId, string errorMessage, Diadoc.Api.CorrectionInfo correctionInfo)
Generates correction request file for attachment stated containing invoice.
Characteristics:
• authToken: authentication token.
• boxId: box identifier.
• messageId: message identifier, containing attachment with invoice.
• attachmentId: identifier of attachment with invoice for which correction request is generated.
• errorMessage: verbal description of error.
• correctionInfo: detailed information on errors in invoice file.
Type: Diadoc.Api.CorrectionInfo
Return value: GeneratedFile
• Message GetMessage(string authToken, string boxId, string messageId)
Returns message in a whole with all the patches on the basis of identifier.
Characteristics:
• authToken: authentication token
• boxId: box identifier
• messageId: message identifier
Return value: Message
• Guid PostDraft(string authToken, string fromBoxId, string toBoxId, Drafts drafts)
Creates new draft containing one or several files
Characteristics:
• authToken: authentication token
• fromBoxId: sender box identifier (obligatory)
• toBoxId: recipient box identifier (optional)
• drafts: object containing list of files to be included into draft (obligatory)
Type: Drafts
Return value: identifier of newly created draft
Diadoc.CryptApi
Object for operation with cryptography. It helps to create digital e-signature, verify signatures and get information on certificate of signer.
Methods:
• Certificate[] GetPersonalCertificates(bool onlyWithPrivateKey = false)
Method enabling to get list of certificated available in user certificate storage.
Characteristics:
• onlyWithPrivateKey: while transfer of true valuw method returns only certificates having privacy key.
Type: bool
On default: false
Return value: Certificate object array
• void Sign(string contentFilename, string thumbprint, string signatureFilename)
Realizes digital signing of stated file content. This method does not change content of files transferred to it.
Characteristics:
• contentFilename: name of file content of which it is necessary to sign.
Type: string
• thumbprint: thumbprint of the certificate used for signature.
Type: string
• signatureFilename: a file with signature will be created under this name. If such a file already exists its content will be rewritten.
Type: string
Return value: none
• Certificate Verify(string contentFilename, string signatureFilename)
Verifies digital signature for file stated and returns information on certificate used for signing. This method does not change content of files transferred to it.
Characteristics:
• contentFilename: name of file signature of which shall be verified.
Type: string
• signatureFilename: name of file containing the signature to be verified.
Type: string
Return value: Certificate object
Diadoc.Api.MessageToPost
Object transferred to PostMessage method. Is a cover for MessageToPost protobuffer.
Features:
• FromBoxId: sender box identifier.
Type: string
• ToBoxId: recipient box identifier.
Type: string
Methods:
• void AddInvoice(InvoiceAttachment invoice)
Adds attachment with invoice to message.
Characteristics:
• invoice: invoice
Type: InvoiceAttachment
Return value: none
• void AddAttachment(NonformalizedAttachment attachment)
Adds non-formalized attachment to message.
Characteristics:
• attachment: attachment
Type: NonformalizedAttachment
Return value: none
Diadoc.Api.InvoiceAttachment
Is a cover for InvoiceAttachment protobuffer.
Features:
• SignedContent: content of invoice file with signature.
Type: SignedContent
• FileName: invoice file name.
Type: string
• Comment: comments to attacnment.
Type: string
Diadoc.Api.NonformalizedAttachment
Is a cover for NonformalizedAttachment protobuffer.
Features:
• SignedContent: content of attachment with signature.
Type: SignedContent
• FileName: name of attachment file.
Type: string
• Comment: comments to attachment.
Type: string
• NeedRecipientSignature: flag stated in true by message sender when recipient signature is needed.
Type: bool
Diadoc.Api.SignedContent
Features: none
Methods:
• void LoadContentFromFile(string fileName)
Loads content from file stated.
Characteristics:
• fileName: name of file
Type: string
Return value: none
• void SaveContentToFile(string fileName)
Saves content in file stated.
Characteristics:
• fileName: name of file
Type: string
Return value: none
• void LoadSignatureFromFile(string fileName)
Loads signature from file stated.
Characteristics:
• fileName: name of file
Type: string
Return value: none
• void SaveSignatureToFile(string fileName)
Saves signature in file stated.
Characteristics:
• fileName: name file
Type: string
Return value: none
Diadoc.Api.MessagePatchToPost
This type of object is transferred to PostMessagePatch method. Is a cover for MessagePatchToPost protbuffer.
Features:
• BoxId: box identifier.
Type: string
• MessageIdGuid: identifier of initial message for which patch is designed.
Type: Guid
Methods:
• void AddReceipt(ReceiptAttachment receipt)
Adds attachment with receipt request.
Characteristics:
• receipt: receipt request
Type: ReceiptAttachment
Return value: none
• void AddCorrectionRequest(CorrectionRequestAttachment correctionRequest)
Adds attachment with correction request.
Characteristics:
• correctionRequest: correction request
Type: CorrectionRequestAttachment.
Return value: none
• void AddRequestedSignature(RequestedSignature signature)
Adds recipient signature to the message (if sender requested return signature while sending).
Characteristics:
• signature: signature
Type: RequestedSignature.
Return value: none
Diadoc.Api.RequestedSignature
Is a cover for RequestedSignature protobuffer.
Features:
• AttachmentIdGuid: identifier of the attachment with signature.
Type: Guid
Methods:
• void LoadFromFile(string fileName)
Loasd signature content from filed stated.
Characteristics:
• fileName: name of file from which signature content will be loaded
Type: string
Return value: none
Diadoc.Api.ReceiptAttachment
Is a cover for ReceiptAttachment protobuffer.
Features:
• DocumentIdGuid: identifier of attachment with receipt request.
Type: Guid
• SignedContent: signed request content.
Type: SignedContent
• FileName: name of receipt request file.
Type: string
Diadoc.Api.CorrectionRequestAttachment
Diadoc.Api.CorrectionRequestAttachment
Is a cover for CorrectionRequestAttachment protobuffer.
Features:
• InvoiceId: identifier of attachment containing invoice.
Type: string
• SignedContent: content of file containing correction request with signature.
Type: SignedContent
• FileName: correction request file name.
Type: string
Diadoc.Api.CorrectionInfo
Detailed information on errors in invoice file is transferred to GenerateInvoiceCorrectionRequestXml method. Is a cover for InvoiceCorrectionInfo protobuffer.
Features:
• InfoMessage: information message (optional).
Type: string
Methods:
• void AddErrorMessage(string message, string path)
Adds information on error into the list.
Characteristics:
• message: text with error message (obligatory).
Type: string
• path: пpath to error XML element in invoice file (optional).
Type: string
Return value: none
Diadoc.Api.Drafts
Auxiliary object for transfer to PostDraft method. Contains list of files to be included into created draft.
Features: none
Methods:
• void AddDraft(string attachmentType, string filePath, string fileName, string comment, bool needRecipientSignature)
Characteristics:
• attachmentType - Type of attachment
Type: string
Values possible: "Nonformalized", "Invoice"
• filePath – path to file in file system, which content will be added to the draft
Type: string
• fileName – name of file added to the draft. May be null – then name of file is based on path to file
Type: string
• comment – comment to file
Type: string
• needRecipientSignature – if return signature is necessary for file or not
Type: bool
Return value: none
Objects returned by API methods
BoxInfo
Object containing information on the box. Is a cover for BoxInfo protobuffer
Features:
• BoxId: unique box identifier.
Type: string
• BoxName: understandable box name.
Type: string
• Org: owner information.
Type: OrgInfo
OrgInfo
Information on the company – mailbox owner. Is a cover for OrgInfo protobuffer
Features:
• Name: company name.
Type: string
• Inn: string containing TIN of the company.
Type: string
• Kpp: string containing KPP of the company.
Type: string
BoxEventList
Object returned by GetNewEvents method. Is a cover for BoxEventList protobufer
Features:
• TotalCount: total number of events satisfying the request. This number can be greater than number of events in Events array, but cannot be less.
Type: int32
• EventsList: events array in the mailbox.
Type: BoxEvent array
BoxEvent
Contain information on event in the box. May contain Message or MessagePatch. Is a cover for BoxEvent protobuffer
Features:
• EventId: unique event identifier.
Type: string
• Message: information on new message receipt.
Type: Message
• Patch: information on patchs to message already existing in the box.
Type: MessagePatch
Message
This type of objects is returned by PostMessage, GetMessage methods, and can be a part of BoxEvent object. Is a cover for Message protobuffer
Features:
• MessageIdGuid: message identifier.
Type: Guid
• MessageId: message identifier as a string.
Type: string
• Timestamp: time of message creation.
Type: VT_DATE
• LastPatchTimestamp: time of latest patch (patch) applied to the present message.
Type: VT_DATE
• FromBoxId: sender mailbox identifier.
Type: string
• FromTitle: sender mailbox human readable name.
Type: string
• ToBoxId: recipient mailbox identifier.
Type: string
• ToTitle: recipient mailbox human readable name.
Type: string
• EntitiesList: list of entities contained in the present message.
Type: Entity array.
Entity
Is a cover for Entity protobuffer
Features:
• EntityType: Type of entity.
Type: lest of EntityType. Values possible: EntityType_Attachment, EntityType_Signature.
• EntityIdGuid: unique entity identifier.
Type: Guid
• ParentEntityIdGuid: parent entity identifier. Meaningful , for example, for entity being a signature as well as for some entities using in invoice interchange process.
Type: Guid
• Content: content of entity.
Type: Content.
• AttachmentType: Type of attachment (only if EntityType = Attachment).
Type: list of AttachmentType. Values possible: AttachmentType_Nonformalized, AttachmentType_Invoice, AttachmentType_InvoiceReceipt, AttachmentType_InvoiceConfirmation, AttachmentType_InvoiceCorrectionrequest, AttachmentType_AttachmentComment, AttachmentType_DeliveryFailureNotification.
• FileName: entity file name. Meaningful only for attachments.
Type: string
• NeedRecipientSignature: flag showing that sender requested recipient signature for attachment. Meaningful only for attachments of Nonformalized type
Type: bool
• SignerBoxId: signer mailbox identifier. Meaningful only for entities of Signature type
Type: string
Content
Is a cover for Content protobuffer
Features:
• Size: content size, -1 if size unknown.
Type: sfixed32
• Data: content itself. May be null, in this case to get content you shall use SaveEntityContent method.
MessagePatch
This type of objects is returned by PostMessagePatch method, and can be a part of BoxEvent object. Is a cover for MessagePatch protobuffer
Features:
• MessageIdGuid: message identifier.
Type: Guid
• Timestamp: patch creation time.
Type: VT_DATE
• EntitiesList: list of entities.
Type: Entity array.
GeneratedFile
Object returned by GenerateInvoiceDocumentReceiptXml and GenerateInvoiceCorrectionRequestXml methods.
Features:
• FileName: name of generated file.
Type: string
Methods:
• void SaveContentToFile(string path)
Characteristics:
• path: file name for content saving
Type: string
Return value: none
Certificate
Object containing information on certificate.
Features:
• Name: certificate owner name
Type: string
• Thumbprint: certificate thumbprint. Is transferred to AuthenticateWithCertificate method for authentication.
Type: string
• ValidFrom: certificate is valid from.
Type: VT_DATE
• ValidTo: certificate expiry date.
Type: VT_DATE
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- javascript api download
- esri javascript api 3 16
- esri api for javascript
- esri javascript api search
- arcgis javascript api 4 5
- esri javascript api 4
- microsoft api download
- unified communications managed api 4
- unified communications api 4 0
- unified communications managed api 2 0
- javascript api documentation
- javascript api reference