ecos-edi API Requests

The ecos-edi microservice implements functionality from the enterprise-core service EcosEdiService.

When sending a request to send a package or documents, or to generate service documents, a record DAO with id edi-action is used.

To send a request via records, the mutate method must be used.

Request and response DTO:

public static class EdiActionRequest {
    private String requestType;
    private EdiProviderType providerType;
    private ObjectData requestData;
}

public static class EdiActionResult {
    private T data;
}

Where:

  • requestType - тип запроса, например “generatePrintForm“

  • providerType- тип провайдера, Контур, СБИС и т.д. для Диадока необходимо указывать “KONTUR“ (см. EdiProviderType enum).

  • requestData - request data; e.g. for print form generation, this is the document’s documentRef

Request example:

RecordAtts requestAtts = new RecordAtts();
requestAtts.setId("edi/edi-action@");
requestAtts.setAtt("requestType", "generatePrintForm");
requestAtts.setAtt("providerType","KONTUR");
requestAtts.setAtt("requestData", ObjectData.create().set("documentRef", RecordRef.valueOf("recordRef value")));
recordsService.mutate(requestAtts);

Various request types can be found in the EdiRequestRecords class of the ecos-edi microservice

Console request example:

var rec = Records.get('edi/edi-action@'); // важно @ в конце
rec.att("_self", {
                "requestType":"generatePrintForm",
                "providerType":"KONTUR",
    "requestData": {"documentRef":"emodel/edi-document@5d518efd-cef1-4ebf-b518-62ff9a620c9e"}

    });
var resp = await rec.save("?json");

List of currently supported requests:

Request

Description

Example

isCounterpartyExists
Request to check whether a connection with a counterparty exists for a specific organization.
requestData parameters:

  • clientBoxId — ID of the mailbox being checked

  • inn — counterparty TIN (INN)

  • kpp — counterparty KPP (tax registration reason code)

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"isCounterpartyExists",
                "providerType":"KONTUR",
                "requestData": {
                    "clientBoxId":"1312313-131331-1231",
                    "inn":"12334561234",
                    "kpp":"123652323"
                }

    });
var resp = await rec.save("json");

aquireCounterparty
Request to create a connection with a counterparty.
Parameters:

  • counterpartyRef - recordRef of the counterparty in ecos

  • clientBoxId - organization mailbox ID

  • invitationDocRef - recordRef of the invitation document (optional)

  • comment - Comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"aquireCounterparty",
                "providerType":"KONTUR",
                "requestData": {
                    "counterpartyRef":"emodel/counterparty@12311241-123123",
                    "clientBoxId":"123123-123123123-123213",
                    "invitationDocRef ":"emodel/invitationDoc@12311241-123123",
                    "comment": "commentText"
                }

    });
var resp = await rec.save("json");

breakWithCounterparty
Request to disconnect from a counterparty
Parameters:

  • counterpartyRef - recordRef of the counterparty in ecos

  • clientBoxId - organization mailbox ID

  • comment - comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"breakWithCounterparty",
                "providerType":"KONTUR",
                "requestData": {
                    "counterpartyRef":"emodel/counterparty@12311241-123123",
                    "clientBoxId":"123123-123123123-123213",
                    "comment": "commentText"
                }

    });
var resp = await rec.save("json");

sendPackageToCounterparty
Sending an outgoing package to the provider.
Parameters:

  • packageRef - recordRef of the package being sent

  • counterpartyRef - recordRef of the counterparty in ecos

  • counterpartyBoxId - counterparty boxId (optional, required if counterpartyRef is not specified)

  • legalEntityRef - recordRef of the legal entity in ecos

  • clientBoxId - legal entity boxId (optional, required if legalEntityRef is not specified)

  • fromDepartmentId - ID of the department in the provider on behalf of which the package is sent (Optional)

  • toDepartmentId - ID of the department in the provider to which the package is sent (Optional)

  • isInternal - whether the package is internal (circulation between departments of the same organization)

  • needSentSignature - whether the counterparty’s signature is required

  • packageNumber - Package number (Optional)

  • packageDate - Package date (Optional)

  • packageComment - Package comment (Optional)

  • signerRef - recordRef of the user who signed the documents in the package

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendPackageToCounterparty",
                "providerType":"KONTUR",
                "requestData": {
                    "packageRef":"emodel/edi-package@12311241-123123",
                    "counterpartyRef":"emodel/counterparty@12311241-123123",
                    "counterpartyBoxId ":"234623478246824623442374",
                    "legalEntityRef":"emodel/legal-entity@12311241-123123",
                    "clientBoxId":"2342342342342342424324",
                    "fromDepartmentId ":"3434444444444434343434",
                    "toDepartmentId":"242423423424242424242",
                    "isInternal":false,
                    "needSentSignature":true,
                    "packageNumber":"22551515252",
                    "packageDate":"2023/09/08",
                    "packageComment":"Test comment",
                    "signerRef": "emodel/person@12311241-123123"
                }

    });
var resp = await rec.save("json");

signPackage
Sending signed documents in a package to the provider.
Parameters:

  • packageRef – recordRef of the package with EDI documents

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"signPackage",
                "providerType":"KONTUR",
                "requestData": {
                    "packageRef ":"emodel/edi-package@12311241-123123"
                }

    });
rec.save("json");

pointwiseSync
Point-to-point synchronization with the provider for a single package.
Parameters:

  • clientBoxId - ID of the mailbox with which synchronization is configured

  • systemPackageId - ID of the package for which synchronization is required

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"pointwiseSync",
                "providerType":"KONTUR",
                "requestData": {
                    "clientBoxId":"12315116136163241231",
                    "systemPackageId":"1321312312312321312312"
                }

    });
rec.save("json");

signDocuments
Sending document signatures to the provider.
Parameters:

  • documentRefs - list of signed documents for which signatures need to be sent

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"signDocuments",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

signDocumentsAndBuyerTitles
Sending signatures for formal documents to the provider.
Parameters:

  • documentRefs - list of signed informal documents for which signatures need to be sent.

  • invoicesRefs - list of signed formal documents for which signatures need to be sent

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"signDocumentsAndBuyerTitles",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ],
                    "invoicesRefs":[
                                    "emodel/edi-document@ref3",
                                    "emodel/edi-document@ref4"
                                    ]
                }

    });
rec.save("json");

sendReconciliationActSigns
Sending signatures for reconciliation acts.
Parameters:

  • documentRefs - list of signed informal documents for which signatures need to be sent

  • signerRef - recordRef of the user who signed the documents

  • signerJobTitle - job title of the user who signed the documents

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendReconciliationActSigns",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ],
                    "signerRef":"emodel/person@ref-1",
                    "signerJobTitle":"Директор тест"
                }

    });
rec.save("json");

rejectPackage
Sending a signed rejection of document signatures in a package.
Parameters:

  • packageRef - recordRef of the package with EDI documents

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"rejectPackage",
                "providerType":"KONTUR",
                "requestData": {
                    "packageRef ":"emodel/edi-package@12311241-123123"
                }

    });
rec.save("json");

rejectDocuments
Sending a signed rejection of document signatures.
Parameters:

  • documentRefs - list of documents for which a rejection needs to be sent

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"rejectDocuments",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

sendReconciliationActRejects
Sending signed signature rejections for reconciliation acts.
Parameters:

  • documentRefs - list of reconciliation acts for which a rejection needs to be sent

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendReconciliationActRejects",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

acceptRevocationRequests
Sending signed annulment requests for documents.
Parameters:

  • documentRefs - list of documents for which annulment was signed

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"acceptRevocationRequests",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

declineRevocationRequests
Sending signed rejections of annulment requests for documents.
Parameters:

  • documentRefs - list of documents for which an annulment rejection was signed

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"declineRevocationRequests",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

sendRevocationRequests
Sending signed annulment requests for documents.
Parameters:

  • documentRefs - list of documents for which an annulment request was signed

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendRevocationRequests",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

sendCorrectionRequests
Sending signed correction requests for documents.
Parameters:

  • documentRefs - list of documents for which a correction request was signed

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendCorrectionRequests",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

sendBuyerTitles
Sending signed buyer titles for formal documents.
Parameters:

  • documentRefs - list of documents for which a buyer title was signed

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendBuyerTitles",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
rec.save("json");

generatePrintForm
Generate a print form for a document; returns the print form content
Parameters:

  • documentRef - recordRef of the document for which the print form needs to be generated

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generatePrintForm",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1"
                }

    });
var res = rec.save("json");

generatePrintFormWithDetails
Generate a print form for a document; returns the print form content plus additional parameters (document ID, print form generation status at the provider, possible errors)
Parameters:

  • documentRef - recordRef of the document for which the print form needs to be generated

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generatePrintFormWithDetails",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1"
                }

    });
var res = rec.save("json");

needUpdateMainContentByPrintForm
Whether print form generation is required for the document
Parameters:

  • documentRef - recordRef of the document for which generation requirement clarification is needed

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"needUpdateMainContentByPrintForm",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1"
                }

    });
var res = rec.save("json");

generateRejectionXml
Generate a signature rejection XML for a document.
Parameters:

  • documentRef – recordRef of the document for which a signature rejection XML needs to be generated

  • signerRef - recordRef of the user who will sign the rejection

  • comment - rejection comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateRejectionXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1",
                    "signerRef":"emodel/person@ref-1",
                    "comment":"Test comment"
                }

    });
var res = rec.save("json");

generateRejectionsXml
Generate signature rejection XML for documents
Parameters:

  • documentRef – recordRef of the document for which a signature rejection XML needs to be generated

  • signerRef - recordRef of the user who will sign the rejection

  • comment - rejection comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateRejectionsXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ],
                    "signerRef":"emodel/person@ref-1",
                    "comment":"Test comment"
                }

    });
var res = rec.save("json");

generateRevocationXml
Generate an annulment request XML for a document
Parameters:

  • documentRef – recordRef of the document for which an annulment request XML needs to be generated

  • signerRef - name of the user who will sign the annulment request

  • comment - annulment request comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateRevocationXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1",
                    "signerName":"admin",
                    "comment":"Test comment"
                }

    });
var res = rec.save("json");

generateRevocationsXml
Generate annulment request XML for documents.
Parameters:

  • documentRef – recordRef of the documents for which annulment request XML needs to be generated

  • signerRef - name of the user who will sign the annulment request

  • comment - annulment request comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateRevocationsXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ],
                    "signerName":"admin",
                    "comment":"Test comment"
                }

    });
var res = rec.save("json");

generateInvoiceCorrectionRequestXml
Generate a correction XML for a document.
Parameters:

  • documentRef – recordRef of the document for which a correction XML needs to be generated

  • signerRef - name of the user who will sign the correction

  • comment - comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateInvoiceCorrectionRequestXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1",
                    "signerName":"admin",
                    "comment":"Test comment"
                }

    });
var res = rec.save("json");

isNeedSignTitle
Check whether a buyer title signature is required for the document
Parameters:

  • documentRef - recordRef of the document for which the check is required

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"isNeedSignTitle",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1"
                }

    });
var res = rec.save("json");

generateBuyerTitle
Generate a buyer title XML for a document
Parameters:

  • documentRef – recordRef of the document for which a buyer title needs to be generated

  • signerName - name of the user who will sign the buyer title

  • factArrivalDate - actual date of goods transfer

  • comment - comment

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateBuyerTitle",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1",
                    "signerName":"admin",
                    "factArrivalDate ":"2023/09/08",
                    "comment":"Test comment"
                }

    });
var res = rec.save("json");

generateReceiptXml
Generate a receipt acknowledgment XML for a document
Parameters:

  • documentRef – recordRef of the document for which a receipt acknowledgment needs to be generated

  • signerName - name of the user who will sign the receipt acknowledgment

  • signerPosition - user’s job title

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateReceiptXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1",
                    "signerName":"admin",
                    "signerPosition":"DirectorTest"
                }

    });
var res = rec.save("json");

generateReceiptsXml
Generate receipt acknowledgment XML for documents
Parameters:

  • documentRefs – recordRef of the documents for which receipt acknowledgments need to be generated

  • signerName - name of the user who will sign the receipt acknowledgment

  • signerPosition - user’s job title

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"generateReceiptsXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ],
                    "signerName":"admin",
                    "signerPosition":"DirectorTest"
                }

    });
var res = rec.save("json");

sendReceiptsXml
Sending signed receipt acknowledgment XML for documents.
Parameters:

  • documentRefs - recordRef of the documents for which receipt acknowledgments need to be sent

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendReceiptsXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRefs":[
                                    "emodel/edi-document@ref1",
                                    "emodel/edi-document@ref2"
                                    ]
                }

    });
var res = rec.save("json");

sendReceiptXml
Sending signed receipt acknowledgment XML for a document (to be optimized in the future)
Parameters:

  • documentRef - recordRef of the document for which a receipt acknowledgment needs to be sent

 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"sendReceiptXml",
                "providerType":"KONTUR",
                "requestData": {
                    "documentRef":"emodel/edi-document@ref1"
                }

    });
var res = rec.save("json");

addDocumentsToSystemPackage
Adding a document to the edi-package system package.
The parameters include the ref of the system package and a list of documents to be added to that package.
If the package ref is not specified, a new EDI package will be created and the provided documents will be added to it.
Documents can be of the edi-document type and its subtypes, as well as any other type not related to EDI
If a document that is not of the edi-document type or its subtype is provided, a corresponding edi-document type document is created for each such document.
The edi-document is added to the package and can then be sent to the provider.
The edi-document and the added custom document are linked via the ediDoc:systemDocumentLink association
Parameters:

  • packageRef - recordRef of the EDI package to which documents are added; can be null, in which case a new package is created

  • documentRefs – documents to be added to the package

The response returns the recordRef of the package
 
var rec = Records.get('edi/edi-action@');
rec.att("_self", {
                "requestType":"addDocumentsToSystemPackage",
                "providerType":"KONTUR",
                "requestData": {
                        "packageRef":"emodel/edi-package@packageId", //id системного пакета для добавления документов (может быть null, тогда будет создан новый пакет
                        "documentRefs":["emodel/doc-type@doc-id"] // список документов для добавления в системный edi пакет
                }
});
var resp = await rec.save("json");