1. Overview
  2. RIPEye Validation UI
  3. API Integration

API Integration

Authentication

The authentication information for the Web-Frontend can be provided in two different ways, depending on how the application is being used:

Used in context of an ERP system

If the Web Frontend is used in context of an ERP system, it will most likely be started from the ERPs Workflow and the ERP will provide the User credentials as URL parameter (parameter “at” - encoded in case of https) in that case. The at parameter corresponds to the access token described below.

The AccessToken parameter will be appended to the application’s URL as follows: https://validation.bludelta.ai?at=accesstoken 

Used standalone

If the Web Frontend is used as standalone application without an ERP system, the user has to authenticate himself via a Username + Password combination. Therefore the Web Frontend will always start with a Login Page if the Access Token parameter has not been specified in the URL. The Login Page allows to store the provided authentication information in a cookie so simplify subsequent logons. Existing cookies will be overruled by an Access Token parameter which has been provided via the URL. The Access Token is then used again in all subsequent API calls as authentication token, similar as it would have been provided via the URL.

Input channels for documents

Upload via REST Interface 

Available and described below. Supported file types are tif, gif, jpeg, png, pdf, bmp and ico.

Email 

If email is used, the documents must be sent as an attachment in a supported file format. Please register your email-domains from which you want to send your documents to our inbox with the help of our support team. All documents coming from this domain will be associated to your customer, and they will be later on available in the validation tool.

Manual Upload

Available via the validation tool.

Web API for embedding process

The Web API  is available at https://validation.bludelta.ai/api .
An OpenAPI descriptions required to manage upload and download of documents can be found at: https://validation.bludelta.ai/api/openapi.

Create AccessToken

The Access token is used in all following API calls as authentication token.

Path: POST /create/accesstoken

Request:
Header Fields

-H 'Content-Type: application/json'
-H 'X-ApiKey: Your ApiKey' => For Partner Authentication
-H 'X-ApiIdentifier: Customer’s ApiIdentifier' => For Customer Authentication

Parameters – Json Format

{
	"Name": "Name of the User, just for Logging",	// Can be empty
	"Description": "Some optional description if needed, just for logging",
	"TimeoutSeconds": 180,			// Will be reset with every request
    "ApiIdentifiers": ["M1", "M2", "M3"]	// List of client api identifiers for which the token should be generated – corresponds to the last part of the ‘.’-split ApiIdentifier  - e.g. ‘customerIdentifier.M1’
}

Comment: The ApiIdentifiers list contains all clients, for which the accesstoken should be generated. To generate an AccessToken for all clients of one Customer (=APIIdentifier), you can either provide a list of all available clients or just leave the list empty. 

Response: Json Format
{
	"State": 0,			// 0 = Ok, 1 = Failed
    "Message": "",			// User-friendly message in case of an error
	"AccessToken": "xxxxxxxx-xxx…", // Unique Id (Guid)
}

Upload InvoiceContainer

The upload InvoiceContainer call is an additional input channel for the BLU DELTA Workflow. The uploaded container is processed the same way as documents coming from other input channels. The max size for an invoice container upload request is 100MB. When uploading a file of an invalid file type the call results in HTTP 415.

Path: POST /upload/invoiceContainer

Request:
Header Fields
-H 'Content-Type: application/json'
[Alternative 1]
-H 'X-ApiKey: Your ApiKey' => For Partner Authentication
-H "X-ApiIdentifier: Partners Customer
[Alternative 2]
-H 'X-AccessToken: Current AccessToken' => For Authentication   

// Either the APIKey + APIIdentifier or a valid AccessToken is required for authentication.

Parameters
{
	"Name": "Name of the User, just for Logging",	// Can be empty
	"Description": "Some optional description if needed, just for logging",
	"FileName": "A1.pdf",			// Filename, the extension specifies the File type
    "File": Base64 encoded string,	// The container that should be uploaded, encoded as   
// base64 string
    "ClientAccessIdentifier": "Client1",	//only required when uploading an invoice container for a non-master-data-client; last part of the apiIdentifier of the client – eg: ‘Client1’ if the full api identifier is ‘Customer1.Client1’
    "AdditionalProperties": [	// List of key value pairs which are passed through; The following keys are predefined: ClientId, EmailMessageId, EmailReceivedDateTime, EmailSubjectText, EmailSenderEmail, EmailAttachmentCount, SenderEmail, ReceiverEmail; additional properties can be added and will be passed through!
{"ClientId": "ClientMasterDataClientId1"}, //ClientId from ClientMasterData
{"EmailMessageId": ""} //contains email message id, so that the customer can associate the document to a mail, if he has sent several document attachments from a mail
{"EmailReceivedDateTime": ""}, // contains received time of the mail
{"EmailSubjectText": ""}, // contains subject text of the mail, as it is sent from customer/supplier
{"EmailSenderEmail": ""}, // contains the mail address of the customer/supplier, who has sent the mail
{"EmailAttachmentCount": "1"}, // contains the number of attachments in the original email
{"SenderEmail": "Email Address"}, // contains the mail address of the customer/supplier, who has sent the mail. Visible in the validation view.
{"ReceiverEmail": "Email Address"}, // contains the mail address of the customer, who has received the mail. Visible in the validation view.
…
]	
}

Response:
{
	"State": 0
    "Message": "",			// User-friendly message in case of an error
    “InvoiceContainerId”: “GUID”	// Unique Id which identifies the uploaded container
}

Download a document

The download document call returns a single invoice together with the DetectInvoiceResponse. The client should repeat this call until the property Available = false.
 
Downloading the same invoice more than three times without confirming it results in HTTP 429 (Too Many Requests). This behaviour exists to avoid cyclic client calls that download the same invoice over and over without confirming it, which is indicative of an error on the calling client's side. If you receive HTTP error code 429 from this endpoint contact our support to resolve the issue.
 

/download/invoice/next endpoint: returns response with DetectInvoiceResponse, which only has Invoice Detail Types in range of integer only. To determine which Invoice Detail Types are supported for this response version, please see the latest API version https://api.bludelta.ai/v1-17/metadata  and limit the types in range of 0 to 1073741824 and -2147483648.

/v2/download/invoice/next endpoint:

returns response with DetectInvoiceResponse, which has Invoice Detail Types in range of 0 to 70368744177664

Path: GET /download/invoice/next?includeResultPdf={true}
Request:
Header Fields
-H 'Content-Type: application/json'
-H 'X-AccessToken: Current AccessToken' => For Authentication
Parameters
‘includeResultPdf’: An optional boolean that determines whether the response should include the result pdf. Default value is false.
Response:
{
"State": 0,
"Message": "",			// User-friendly message in case of an error
"Available": true,		// Specifies if the current response contains a result
"InvoiceId": "xxxxxxxx-xxx…", // Unique Id (Guid)
"InvoiceContainerId": "xxxxxxxx-xxx…", // Unique Id (Guid)
“UploadedTimestamp”: “2021-03-28T23:46:33.363Z” //The timestamp of when the invoice 
container was uploaded
“ClientAccessIdentifier”: “Client1”	// last part of the apiIdentifier of the client – eg: ‘Client1’ if the full api identifier is ‘Customer1.Client1’; is empty when invoice belongs to a non-client customer
"FileName": "A1.pdf",			// Filename, the extension specifies the File type
"File": Base64 encoded string,		// The invoice file itself, encoded as base64 string,
“ResultPdf”: Base64 encoded string,	// Base64 encoded byte array of the ResultPdf for the, can be null if no ResultPdf was able to be generated during processing
// invoice, if we were able to successfully create one
//Limitation: For tiffs with more than 10 pages the result //pdf will always only contain the first 10 pages
"AdditionalProperties": [	// List of key value pairs which have been   
passed through or which have been determined by BLU DELA; The following keys are predefined: ClientId, SupplierId, SenderEmail, ReceiverEmail, EmailMessageId, EmailReceivedDateTime, EmailSubjectText, EmailSenderEmail, EmailAttachmentCount

{"ClientId": "Value"},	//ClientId from ClientMasterData
{"SupplierId": "Value"},
{"SenderEmail": "Email Address"},
{"ReceiverEmail": "Email Address"},
…
],

// If the origin of the request is email, then the following additional properties are added:
{"EmailMessageId": ""} //contains email message id, so that the customer can associate the invoice to a mail, if he has sent several invoice attachments from a mail
{"EmailReceivedDateTime": ""}, // contains received time of the mail
{"EmailSubjectText": ""}, // contains subject test of the mail, as it is sent from customer
{"EmailAttachmentCount": ""}, // contains the number of attachments in the original email
{"EmailSenderEmail": ""}, // contains the mail address of the customer, who has sent the mail

“StateBeforeRelease”: “Validated’”,	//The last state the invoice had before it was released – possible values are: ‘Validated’, ‘Autoprocessed’, ‘Error’ and ‘Deleted’ (if deleted invoices are configured to be automatically released for the customer)
"DetectInvoiceResponse": {		// The result of an invoice detection: See 
// https://api.bludelta.ai/v1-14/metadata  for a detailed description
	}
}

Confirm a document

The confirm invoice call confirms the reception of an invoice document. The Server marks the invoice as transferred and removes it from the list of validatable/downloadable invoices. If an invoice is not confirmed by the ERP System, it will be moved to the end of the downloadable invoices-list and then provided again.

Path: POST /confirm/invoice
Request:
Header Fields
-H 'Content-Type: application/json'
-H 'X-AccessToken: Current AccessToken' => For Authentication
Parameters
{
"InvoiceId": "xxxxxxxx-xxx…", // Unique Id (Guid)
}

Response:
{
"State": 0
"Message": "",			// User-friendly message in case of an error
}

Upload ClientMasterData / SupplierMasterData / other resources

The upload resource call is an optional function to provide additional data for BLU DELTA, e.g. master data about clients and suppliers. The uploaded file will be stored in the BLU DELTA database.

Please visit our Resource API documentation.

Deprecated endpoint

The following endpoint is deprecated:

Path: POST /upload/resource
Request:
Header Fields
-H 'Content-Type: application/json’
-H 'X-AccessToken: Your AccessToken=> For Partner Authentication

Parameters
{
"Name": "Name of the User, just for Logging",  // Can be empty
"Description": "Some optional description if needed, just for logging",
"Type": "Resource Type",	// “ClientMasterData”, “SupplierMasterData” are predefined
"FileName": "resource.csv",		// Filename, the extension specifies the File type
"File": Base64 encoded string,	// The data that should be uploaded, encoded as   
// base64 string
}

Response:
{
"State": 0
"Message": "",			// User-friendly message in case of an error
}

Csv Format ClientMasterData: ClientId, Name, Street+No, ZipCode, City, Country, Ustids, Ibans

Csv Format SupplierMasterData: SupplierId, Name, Street+No, ZipCode, City, Country, Ustids, Ibans, Emails-Addresses, ClientId, SenderEmailAddresses (optional)

Values must be quoted, quotes are escaped by using double quotes Separator for fields: [TAB] Delimiter for multiple values: | IBAN format: uppercase, no spaces – e.g.: ‘AT1234500000009012345’ UID format: uppercase, no spaces – e.g.: ‘ATU12312312’

SenderEmailAddresses is an optional value (meaning the column does not need to exist in the uploaded csv file) which is compared with the additional properties of an uploaded invoice container. If one of the values matches the value of the additional property with the key “SenderEmail” the corresponding supplier receives a higher score.

Check the number of documents in a specific state

If you would like to check the number of documents in a specific state e.g. to show a user in your ERP system if new documents need to be validated you can do so using the following endpoint. ATTENTION: Whether documents are available for download should not be checked with this endpoint since the necessary information is provided by the download endpoint.

Path: GET /count/invoices?state={state}
Request:
Header Fields
-H 'Content-Type: application/json'
-H 'X-AccessToken: Current AccessToken' => For Authentication

Parameters
state = New | Autoprocessed | NeedForAction | Validated | Released | Downloaded | Confirmend | Error or combinations like e.g. “NeedForAction,Autoprocessed,Error" to count three types at once.

Response:
{
"State": 0,	
"Message": "",			// User-friendly message in case of an error
"Count": 10			// Currently 10 invoices are either in the state needForAction or 
Autoprocessed or Error
}

Comments:

  • To look up the number of all invoices for all clients of one customer, generate a separate AccessToken limited only to the ApiIdentifier, but not to clients.
  • The count is cached for 60 seconds – only then will an updated result be returned.

Get the state history for document containers

This endpoint can be used to get a state history for a list of invoice containers and the invoices contained within them. The maximum number of invoice containers for which a state history can be requested is 100. We will return an error message if more than 100 containers are contained within the request.

Path: GET /invoiceContainer/state?containerIds=a2c2378d-1090-eb11-a870-d0c5d372cac4,a6c2378d-1090-eb11-a870-d0c5d372cac4,…
Request:
Header Fields
-H 'Content-Type: application/json’
-H 'X-AccessToken: Your AccessToken=> For Partner Authentication

Parameters
{
"ContainerIds": "A comma separated list of invoice container ids for which the state history is 
requested”
}

Response:
{
"InvoiceContainerStates": [
		{
			"DocumentContainerId": "9aba5d6c-0890-eb11-a870-d0c5d372cac4",
			"DocumentContainerStates": [
				{
					"State": "SplitIntoDocuments",
				"Timestamp": "2021-03-28T22:59:05.187Z"
			},
			{
				"State": "New",
				"Timestamp": "2021-03-28T22:56:03.48Z"
			}
		],
		"DocumentStateReports": [
			{
				"DocumentId": "aaba5d6c-0890-eb11-a870-d0c5d372cac4",
				"DocumentStates": [
					{
						"State": "Confirmed",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
					{
						"State": "Downloaded",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
					{
						"State": "Released",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
					{
						"State": "Autoprocessed",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
					{
						"State": "New",
						"Timestamp": "2021-03-28T22:59:04.55Z"
					}
				]
					},
					{
				"DocumentId": "abba5d6c-0890-eb11-a870-d0c5d372cac4",
				"DocumentStates": [
					{
						"State": "Confirmed",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
					{
						"State": "Released",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
					{
						"State": "Autoprocessed",
						"Timestamp": "2021-03-26T22:59:05.233Z"
					},
						{
							"State": "New",
							"Timestamp": "2021-03-28T22:59:04.55Z"
						}
					]
				}
			]
		},
		{
"DocumentContainerId": "92ba5d6c-0890-eb11-a870-d0c5d372cac4",
			"DocumentContainerStates": [
				{
					"State": "New",
					"Timestamp": "2021-03-28T22:56:03.48Z"
				}
			],
			"DocumentStateReports": []
		}, …
],
"State": 0,
"Message": null 
}

Possible states of a document

The following figure shows the possible states and state flow a container can get.

Error state

Error invoices can be released in order for them to leave the workflow. If so defined in the customer configuration invoices that end up in the error state are automatically released and thus can be downloaded from the GET download/invoice/next endpoint. The property ‘StateBeforeReleased’ contained in the response of the endpoint can be used to check whether the invoice was released due to an error.

In the case of manual releasing the error invoice can be validated like any other invoice via the UI. The state that is returned by the ‘StateBeforeReleased’ property then becomes ‘Validated’ - even for error invoices.

Error invoices are returned with an empty DetectInvoiceResponse.

Last updated 22 April 2024
Was this article helpful?