API REST – Document Manager (1.0)

Download OpenAPI specification:Download

DANAConnect: support@dannaconnect.com URL: https://www.danaconnect.com License: Apache 2.0

The REST Document Manager API is a web service that allows the administration, indexing, consultation, compression and download of document files associated with a record of a contact list and also makes it possible to later activate a conversation flow in DANAConnect using said data.

The Document Manager API is used for:

  • Consult documents stored in the repository using filters and file types, previously configured from the Document Manager interface on the DANAConnect platform.
  • Integration with shipments from the DANAConnect platform by activating a conversation.
  • Get historical download logs.
  • Perform compression of a folder in the Document Storage, or several folders or several files.
  • Get Short URLs or Long URLs to be able to download documents safely.

Considerations prior to using the API

  • The company that is going to use the API must have a valid username and password in the DANAConnect platform.
  • For security reasons, the user who is going to use the API must have a special permission. Your DANAConnect Account Manager must ensure that this permission is enabled.
  • This API works on Conversations (flows) that have previously been created and are active in the platform. This means that you must have the Conversation ID (conversationID) for this flow.
    What is the Conversation identification number (conversationID)?
    The conversation identification number in DANAConnect can be found on the activation reports page for each flow inside the Conversation Manager. It is important to mention that every time a conversation is reactivated, a new Conversation ID will be generated.
  • You must have previously configured the file types for indexing and filtering the search criteria of your documents in the Document Manager of the DANAConnect platform.- You must have an account with an active Document Storage document repository on DANAConnect.

How to find the Conversation ID

For most DANAConnect API requests, you will need to send the Conversation ID as a parameter. This conversation ID refers to the number assigned to the activation of the flow and can be found by logging into the DANAConnect platform and looking in the activation report for the conversation you need to refer to.
It is important to mention that every time a conversation is reactivated, a new Conversation ID will be generated.
Here is a video explaining how to find the conversation ID:

Authentication

basicAuth

The API uses the same user credential system that is used to enter the DANAConnect platform.
The method used for all DANAConnect APIs is HTTP BASIC AUTH, which is based on login and password authentication.
Login: The login consists of the username concatenated with an @ and followed by the company code.
Login example:

  • Platform username: myuser
  • Company code for the platform: mycompanycode
  • Login for DANAConnect API: myuser@mycompanycode
  • Password: The password you should use for API authentication is the same as you use for login to the DANAConnect platform
Security Scheme Type HTTP
HTTP Authorization Scheme basic

Document Sign

Operations involved in signing documents

Request a signed PDF

This service provides a signed PDF

Authorizations:
basicAuth
Request Body schema: application/json

JSON with the data required to sign a document

url
required
string non-empty

Document address inside DANAConnect Storage

isQR
required
boolean

Indicate true or false, if QR code needs to be added

idTypeHashAlignW
required
integer <int32> [ 1 .. 3 ]

Hash horizontal alignment Width

Value Alignment
1 Left
2 Center
3 Right
idTypeHashAlignH
required
integer <int32> [ 1 .. 3 ]

Hash horizontal alignment Height

Value Alignment
1 Up
2 Center
3 Down
idTypeQRAlignW
required
integer <int32> [ 1 .. 3 ]

QR horizontal alignment Width

Value Alignment
1 Left
2 Center
3 Right
idTypeQRAlignH
required
integer <int32> [ 1 .. 3 ]

QR horizontal alignment Height

Value Alignment
1 Up
2 Center
3 Down
idTypePage
required
integer <int32> [ 1 .. 3 ]

Page insertion type

Value Type
1 First
2 Last
3 All
info
required
string [ 3 .. 255 ] characters

Text up to 255 characters, that will show up in hash validation. Words written here can be used to validate the document

Responses

Request samples

Content type
application/json
Example
Unexpected page type
Unexpected page type
Unexpected alignment
Request without any warnings
Unexpected JSON structure
Nonexistent document
Wrong document type

Request with unexpected page type

{
  • "url": "s3://demos/ArchivoFactura1.pdf",
  • "isQR": true,
  • "idTypeHashAlignW": 2,
  • "idTypeHashAlignH": 3,
  • "idTypeQRAlignW": 1,
  • "idTypeQRAlignH": 3,
  • "idTypePage": 5,
  • "info": "Documento enviado a DEMO"
}

Response samples

Content type
application/json
Example
Unexpected document type
Unexpected document type
Document not found
Unexpected alignment value
Unexpected page type
File security error
Maximum character limit exceeded
Successful request result

Response when the document is not a pdf

{
  • "responseCode": "16",
  • "responseDescription": "Wrong document type"
}

Document Download

Operations involved in document downloads

Request the download url of a document(s) and starts a conversation

This service provides a URL to download a document and starts a conversation. The urls are sent through the conversation (They are not returned in the service response)

Authorizations:
basicAuth
Request Body schema: application/json

JSON with the data required to get the download URL of a document(s) and to start a conversation

configServiceType
required
integer <int32>

Identifier indicating Document Manager's service configuration type in DANAConnect platform

isStrict
required
boolean

If set to true, then the search will be strict, and will abort the process if no result is found for document url. If false, every document found will be processed, and those not found will be indicated.

isZip
required
boolean

If set to true, all found files will be zipped, otherwise only the individual list download URL is generated

urlType
required
integer <int32> [ 1 .. 3 ]
Value Type
1 Short URL
2 Long URL
3 Short and Long URL
idConversation
required
integer <int32> >= 1

Conversation id

values
required
string

This should be a JSON object in which keys are the field identifier inside that the contact list that is related to the conversation. And as values the content that will be inserted in that field.
EXAMPLE:

{"FIELD_1":"VALUE_1",
"FIELD_2":"VALUE_2",
...}
Array of objects (DocumentDTO)

Responses

Request samples

Content type
application/json

Request the url of a document to be downloaded

{
  • "configServiceType": 1,
  • "isStrict": false,
  • "isZip": false,
  • "urlType": 1,
  • "documentList": [
    ],
  • "idConversation": "165245",
  • "values": {
    }
}

Response samples

Content type
application/json

Successful Response without any warnings

{
  • "codResponse": "00",
  • "desResponse": "OK."
}

Request the download url of documents that match given filters

This service provides URLs to download documents matching the given filters

Authorizations:
basicAuth
Request Body schema: application/json

JSON with the data required to get the download URL of a document(s)

id_document_type
integer <int32>

Document Manager Service's configuration Unique ID number in DANAConnect platform

type_filter_1
string
Enum: "none" "equals" "contains" "ends" "begins"

Filter method that will be used for filter_1

filter_1
string

First filter applied when searching for documents

type_filter_2
string
Enum: "none" "equals" "contains" "ends" "begins"

Filter method that will be used for filter_2

filter_2
string

Second filter applied when searching for documents

type_filter_3
string
Enum: "none" "equals" "contains" "ends" "begins"

Filter method that will be used for filter_3

filter_3
string

Third filter applied when searching for documents

conditional
string
Enum: "and" "or"

Indicates if filters will be inclusive or exclusive

Responses

Request samples

Content type
application/json
Example
Request with unexpected conditional
Request with unexpected conditional
Request without filters
Request without any warnings

Request with unexpected conditional value

{
  • "id_document_type": 0,
  • "type_filter_1": "none",
  • "filter_1": "Test Name",
  • "type_filter_2": "none",
  • "filter_2": "Test Lastname",
  • "type_filter_3": "none",
  • "filter_3": "Test Lastname",
  • "conditional": "zzz"
}

Response samples

Content type
application/json
Example
No filter was selected
No filter was selected
Successful request result
Unexpected conditional type

At least one filter is expected

{
  • "responseCode": "00",
  • "responseDescription": "You must choose at least one option as a filter"
}

Request the download url of a document(s)

This service provides a URL to download a document

Authorizations:
basicAuth
Request Body schema: application/json

JSON with the data required to get the download URL of a document(s)

configServiceType
required
integer <int32>

Identifier indicating Document Manager's service configuration type in DANAConnect platform

isStrict
required
boolean

If set to true, then the search will be strict, and will abort the process if no result is found for the document url. If false, every document found will be processed, and those not found will be indicated.

isZip
required
boolean

If set to true, all found files will be provided as a zip file, otherwise only the individual list download URL is generated

urlType
required
integer <int32> [ 1 .. 3 ]
Value Type
1 Short URL
2 Long URL
3 Short and Long URL
filter1
string

Value that will find the files that were added to the document manager with that keyword in filter1

filter2
string

Value that will find the files that were added to the document manager with that keyword in filter2

filter3
string

Value that will find the files that were added to the document manager with that keyword in filter3

Array of objects (DocumentDTO)

Responses

Request samples

Content type
application/json
Example
Exceeded the maximum number of files to be compressed
Exceeded the maximum number of files to be compressed
Request without any warnings
Exceeded the maximum number of documents allowed

Exceeded the maximum number of files to be compressed (folder with more than 100 documents) (default value is 100)

{
  • "configServiceType": 1,
  • "isStrict": false,
  • "isZip": true,
  • "urlType": 1,
  • "documentList": [
    ],
  • "filter1": "88",
  • "filter2": "Demo",
  • "filter3": "2021"
}

Response samples

Content type
application/json
Example
Exceeded the maximum number of files to be compressed
Exceeded the maximum number of files to be compressed
Successful request result
Exceeded the maximum number of documents allowed

Exceeded the maximum number of files to be compressed (default value is 100)

{
  • "codResponse": "09",
  • "desResponse": "Exceeded the maximum number of files to be compressed"
}
Next to API REST – Validate MailBox