Diadoc.Api.CorrectionRequestAttachment

grapedraughtSoftware and s/w Development

Dec 2, 2013 (3 years and 6 months ago)

420 views

Diadoc API

Table of contents

Basic notions



User



certificate

owner
,
subject

of

athorization

process
.



Company


in Diad
oc
-

legal entity (or sole propr
ietor) 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

wa
nt
s

to

control

work

of

his

subordinates

from

various

departments
.




Several users may have access to one box. Various users pro
cess information from the box wo
rking in
different shifts.


Authori
zation

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

me
thods

shall

include

so

called


developer

key



unique

string

integrator

identifier
.
You can receive it by sending a request to

diadoc
-
api@skbkontur.ru
.
I
ntegrator 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 character
ized 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
:

Authorizati
on: DiadocAuth

ddauth_api_client_id=testClient
-
8ee1638deae84c86b8e2069955c2825a,

ddauth_token=3IU0iPhuhHPZ6lrlumGz4pICEedhQ1XmlMN1Pk8z0DJ51MXkcTi6Q3CODCC4xTMsjPFfh
K6XM4kCJ4JJ42hlD499/Ui5WSq6lrPwcdp4IIKswVUwyE0ZiwhlpeOwRjNrvUX1yPrxr0dY8a0w8ePsc1D
G8HAlZce8a0
hZiWylMqu23d/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

Authorizatio
n
shall include developer key received while registration.
Corresponding HTTP
-
request is the following
:

POST https://diadoc
-
api.kontur.ru/Auth
enticate HTTP/1.1

Host: diadoc
-
api.kontur.ru

Authorization: DiadocAuth ddauth_api_client_id=testClient
-
8ee1638deae84c86b8e2069955c2825a

Content
-
Length: 1252

Connection: Keep
-
Alive


<
Binary

DER
-
presentation of
X.509
-
certificate to the user
>



Positive serve
r reply looks like th
e following
:

HTTP/1.1 200 OK

Content
-
Length: 598


<
Binary

DER
-
presentation

of encoded authorization token
>



To

receive

authorization

token

the

client

shall

decode

Authenticate

command reply body by pr
i
vacy key
corresponding to user certificate. Received byte array shall be encoded into

Base64
-
string
.
Further, it is
necessary to add HTTP heading Au
thorization with parameters
ddauth_api_client_id=<
developer key
>
and

ddauth_token=<
stated

Base64
-
string
>

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
:

P
OST https://diadoc
-
api.kontur.ru/GetBoxesByAuthToken HTTP/1.1

Host: diadoc
-
api.kontur.ru

Authorization: DiadocAuth ddauth_api_client_id=testClient
-
8ee1638deae84c86b8e2069955c2825a,ddauth_token=3IU0iPhuhHPZ6lrlumGz4pICEedhQ1XmlMN1
Pk8z0DJ51MXkcTi6Q3CODCC4xTM
sjPFfhK6XM4kCJ4JJ42hlD499/Ui5WSq6lrPwcdp4IIKswVUwyE0Ziw
hlpeOwRjNrvUX1yPrxr0dY8a0w8ePsc1DG8HAlZce8a0hZiWylMqu23d/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 conta
in HTTP
-
heading Aut
horization or

this heading does not contain
parameter ddauth
_token,
or parameter value is damaged

o
r 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.

B
ox identifier

is taken fr
om current request parameters. If

box ide
n
tifier

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

PostMessagePatc
h

GenerateInvoiceDocumentReceiptXml

GenerateInvoiceCorrectionRequestXml

PostDraft

Moreover, command

Help

enable
s

receiving

actual list of all the operations supported by the service.


If

you

add

suffix

?proto

to the name of a
ny command you will get actual decsription of all the data structures
(see

Data structures
),
necessary to

use this command. For

example
,
at

request

https
://diadoc
-
api.kontur.ru/GetBoxInfo?proto

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 requ
est processing
.


GetBoxesByAuthToken

Resource name
: /
GetBoxesByAuthToken

HTTP

method
:
GET

Request

string

c
haracteristics
:



outputFormat:
data

out
put

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
r
equest

string

or its value is equal to

protobuf


data is
returned serialized to protobuffer

BoxList
;



if outrutFormat parameter value in
r
equest

string

is equal to
xml


data is returned in

xml

format, for
example
:



<boxes>




<box id="
box ident
ifier
" name="
box name
"
orgName="
company name
"
orgInn="
company TIN
" orgKpp="
company KPP
"/>




<box id="
box identifier
2" name="
box name2
" orgName="
company
name2
" orgInn="
company TIN2
" orgKpp="
company KPP2
"/>

</boxes>

Possible HTTP return codes
:



200 (OK)
-

ope
ration 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 appear
ed while request processing
.


GetBoxesByInnKpp

Resource name
: /
GetBoxesByInnKpp

HTTP

method
:
GET

Request

string

characteristics
:



inn:
company TIN
;



kpp:
company KPP, may be absent
;



outputFo
rmat:
data output format, may be absent
.
Values possible
: xml, protobuf (
at default

-

protobuf).

Request

shall contain
HTTP
-
heading

Authorization
with data necessary for

authori
zation
.

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
r
equest

string

or its value is equal to

protobuf


data is
returned serialized to protobuffer

BoxList
;



if outrutFormat parameter value in
r
equest

string

is equal to
xml


data is returned in

xml

format, for
example
:




<boxes>




<box id="
box identifier
" name="
box name
" orgName="
com
pany name
"
orgInn="
company TIN
" orgKpp="
company KPP
"/>




<box id="
box identifier
2" name="
box name
2" orgName="
company
name
2" orgInn="
company TIN
2" orgKpp="
company KPP
2"/>

</boxes>

If

kpp

parameter

is

absent

in

r
equest

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 Authori
zation 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
r
equest

string

or its value i
s equal to

protobuf


data is
returned serialized to protobuffer

BoxList
;



if outrutFormat parameter value in
r
equest

string

is equal to
xml


data is returned in

xml

format, for
example
:

<box id="
box identifier
" name="
box name
" orgName="
company name
"
orgInn="
company TIN
" orgKpp="
company KPP
"/>

Possible HTTP return codes
:

200 (OK)
-

operation completed successfully
;

400 (Bad Request)
-

data from the request
is in bad

format or lacks ob
ligatory chatacteristics
;

401 (Unauthorized)
-

request lacks Authorization HTTP
-
heading or heading contains incorrect authorization
data
;

404 (Not Found)


box with identifier stated is n
o
t found in the reference book
;

405 (Method not allowed)
-

HTTP metho
d used is not allowed
;

500 (Internal server error)
-

unforseen error appeared while request processing
.


GetNewEvents

Resource name
: /GetNewEvents

HTTP
method
: GET

Request

string

characteristic
s
:



boxId:
box identifier
;



afterEventId:
identifier of the last event received (may be absent)
;

Request

shall contain
HTTP
-
heading

Authorization
with data necessary for

authoriz
ation
.

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

retur
n
ed
.
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 proces
sing
.


GetEvent

Resource name
: /GetEvent

HTTP
method
: GET

Request

string

characteristics
:



boxId:
box identifier
;



eventId:
event identifier
;

Request

shall contain
HTTP
-
heading

Authorization
with da
ta 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 an
d 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.


Po
ssible 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 incor
rect
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 (Int
ernal server error)
-

unforseen error appeared while request processing
.


GetMessage

Resource name
: /
V
2/
GetMessage

HTTP

метод
:
GET

Request

string

characteristics
:



boxId:
box identifier
;



messageI
d:
message identifier
;

Request

shall contain
HTTP
-
heading

Authorization
with data necessary for

authorization
.

Reply body contains message with identifier message
Id
from box

b
oxId,
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 part
icular, 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).
Othe
r attachment bodies can be received
with the help of
GetEntityContent

method.



Possible HTTP return codes
:



200 (OK)
-

operation completed successfully
;



400 (Bad Requ
est)
-

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 cont
ain
HTTP
-
heading

Authorization
with data necessary for

authorization
.

Reply body contains entity content (for example, attachment body) with identifier entityId from the messa
ge
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 A
uthorization 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, t
han 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

MessageToP
ost

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 g
iven to client
.


PostMessagePatch

Resource name
: /
V
2/
PostMessagePatch

HTTP

method
:
POST

Request

string

characteristics
:
NON
E

Request

shall contain
HTTP
-
heading

Authorization
with data necessary for

authorization
.

Request body shall contain patch to message sent serialized into
Message
Patch
ToPost

ptorobuffer.


Reply body cintains patch to message sent ser
ialized into

Messag
ePatch

protobuffer.


Possible HTTP return codes
:



200 (OK)
-

operation completed successfully
;



400 (Bad Request)
-

data from the request
is in bad

format or lacks obl
igatory 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 metho
d 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

characteris
tics
:



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 notic
e is issued in the format compl
ying
with the
requirements on documents rec
e
ipt
notice stipul
ated 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
.


GenerateInvoiceC
orrectionRequestXml

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

c
orrection request
;



errorMessage:
main error message which shall be included into correction request
;

Request

shall contain
HTTP
-
heading

Authorization
with data necessary for

aut
horization
.

Reply body may contain additional data forinvoice correction request in the form of serialized structure

InvoiceCorrectionInfo
.

Reply body conta
ins
XML
-
file with invoice correction request
attachmentId
from

messageId
message in the box

boxId.
File with notic
e is issued in the format compl
ying
with the
requirements on documents rec
e
ipt 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 ob
ligatory 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 meth
od used is not allowed
;



500 (Internal server error)
-

unforseen error appeared while request processing
.


PostDraft

Resource name
: /
PostDraft

HTTP

method
:
POST

Request

string

characteristics
:



fro
mBoxId


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

-

Nonformal
ized),

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 dat
a 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 l
acks 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 o
f 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

me
chanism is used. Description of Protocol B
uffers language
syntax is shown

here
.

There are ready libraries for various platforms and programming languages, solving the tas
k of serialization/
deserialization of relative data structures into protobuffers. Here are some of them
:



C++, Java, Python


Google official realization
e
;



Microsoft® .NET


protobuf
-
ne
t project

;



And others



many references
.


BoxList

message BoxList {


repeated BoxInfo Boxes = 1;

}


message BoxInfo {


required string BoxId = 1;


required string BoxName = 2;


require
d 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 stri
ng 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
-

messa
ge 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

conve
rt

this

mark
to
.NET
-
structure

System.DateTime
,
it is possible to use the following code on

C#

language
: new
DateTime(TimestampTicks, DateTimeKind.Utc)
.



LastPatchTimesta
mpTicks


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
.
i
t 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

composin
g

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 ma
rk. Is an integer number of tic
s (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, DateTime
Kind.Utc).



Entities


list

of

entities

composing

present

patch

to

message
.
Each entity is presented by structure of
Entity

type.


En
tity

message

Entity

{


required EntityType EntityType = 1;


required string EntityId = 2;


optional string ParentEntityId = 3;


op
tional Content Content = 4;

//
value

is

absent

only

when

entity has
no content


optional AttachmentType AttachmentType = 5 [d
efault = Nonformalized];


optional string FileName = 6;


optional bool NeedRecipientSignature = 7 [default = false];


optional string SignerBoxId = 8;

}


message Content {


req
uired sfixed32 Size = 1;

//
-
1
is content size unknown


optional bytes Data = 2;

//
value is abse
nt only w
hen 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;


In
voiceReceipt = 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 attach
ment 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 ex
ample, 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
).



Att
achmentType
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 o
r

invoice correction request)
, InvoiceConfirm
ation (
EDI supplier
confirmation
)
, InvoiceCorrectionRequest (
invoice correction request
), AttachmentComment (
text
comments on other entity
-

attachment
)
, DeliveryFailureNotification (
delivery failure notification
).



Content


entity

content
.
Content.Size
f
ield

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 Non
formalized


it is just binary content of initi
al file. Entities
of
Attachment

type with attachments of

Invoice, Invoi
ceReceipt, InvoiceConfirmation
and

InvoiceCorrectionRequest
types are
XML
-
files, interchanged by seller and buyer while issuing/ receipt of
e
-
invoices in accordance with the procedure s
tated 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

Attachm
ent

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

o
f

Attachment

type

with

Nonformalizes

attachment

type
.



Si
gnerBoxId



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 corres
ponding 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 Nonformalized
Attachment {


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 Signat
ure = 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 re
cipient
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
:



Signed
Content
-

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 documen
t

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 Req
uestedSignatures = 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;

}



MessagePatchToPo
st
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
.



Messag
eId
-

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
proce
dure
.



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 e
ntity 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 struct
ure 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

Enti
ty

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 identifie
r 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 InvoiceC
orrectionInfo {


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 t
o 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.Api.ComDiadocApi2

Diadoc
.
Api
.
ComCryptApi

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 desi
gned to simplify integration with other products. It is a cover for
operations realized by Diadoc API through HTTP protocol.


User


created objects

Diadoc.Api.ComDiadocApi2

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 na
me

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 val
ue
:
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
,
retur
ns

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

ba
sis

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 au
thToken)

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:
authent
ication 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 valu
e
:
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.

Charact
eristics
:



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 confirmati
on 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.A
pi.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
.



attac
hmentId:
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, stri
ng 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

(obli
gatory)



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.Api.ComCryptApi

Object

for

operation

with

cryptography
.
It

helps

to

create

digital

e
-
signature
,
verify

signatures

and

get

information

on

certificate

of

sign
er
.

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

c
ertificates

having

privacy

key
.

Type
: bool

On default
: false

Return value
:
Certificate

object array



void Sign(string contentFilename, string thumbprint, string signatureFi
lename)

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



thum
bprint:
thumbprint of the c
ertificate 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, st
ring 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 attach
ment with invoice to message
.

Characteristics
:



invoice:
invoice

Type
:
InvoiceAttachment


Return value
:
none



void AddAttachment(NonformalizedAttachm
ent attachment)

Adds non
-
formalized attachment to message
.

Characteristics
:



attachment:
attachment

Type
:
NonformalizedAttachment


Retur
n 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
.

Typ
e
: string


Diadoc.Api.NonformalizedAttachment

Is a cover for

NonformalizedAttachment

protobuff
er.

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 fil
e

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 state
d
.

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 identi
fier
.

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
.

Characte
ristics
:



correctionRequest:
correction
request

Type
:
CorrectionRequestAttachment
.

Return value
:
none



void AddRequestedSignatur
e(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 LoadFr
omFile(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.Cor
rectionRequestAttachment

Is a cover for

CorrectionRequestAttachment

protobuffer.


Features
:



InvoiceId:
identifier of attachment containing invoice
.

Type
: string



Si
gnedContent
:
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:
informatio
n

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 invoic
e 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 base
d 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:
uniqu
e 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
: st
ring



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

MessagePa
tch
.
Is a cover for

BoxEvent

protobuffer


Features
:



EventId:
unique event identifier
.

Type
: string



Message:
information on new message receipt
.

Type
:
Message




Patch:
information

on

patch
s

to

message already

existing

in

the

box
.

Type
:
MessagePat
ch



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



Tim
estamp:
time of message creation
.

Type
: VT_DATE



LastPatchTimestamp:
time of latest patc
h (
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

read
able

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 entit
y 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



NeedRecipie
ntSignature:
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

itsel
f
.
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 identifi
er
.

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