Generic KPI API

This document describes a 'reverse' web API that is to be provided to ITX to display custom information in the Contact Center's KPI panel. The displayed information is supposed to be a list of documents (e.g. orders or invoices) containing records about sold or bought products or services. However, the documents might contain arbitrary information. They just need to have the required structure.

The API is to respond to the requests similar to GET https://customer.api/rest/kpi?customerId={id} where {id} value is the identifier of a specific company. Exact URL / path is arbitrary and might contain other fixed parameters (e.g. authentication tokens) if needed. The response should be in JSON format of the structure described below.

It is supposed that the integration / synchronization between ITX and the external information system (whatever it is) was performed beforehand, so ITX already has information about companies' external identifiers. If so, ITX adds the {id} value corresponding to the currently opened company card to the request.

The API definition in OpenAPI (Swagger) format is provided and can be used with Swagger Codegen to generate server code stubs. The example response included in the definition is displayed in ITX like that:

Response format

Name	Type	Description	Notes
sections	[KpiSectionDTO]	List of KPI panel sections.	[optional]

KpiSectionDTO

Name	Type	Description	Notes
title	String	Section title, like 'Orders' or 'Invoices'.
message	String	Error or any other message for the section, like 'No data available'.	[optional]
documents	[KpiDocumentDTO]	Documents to be shown in the panel. Documents are supposed to be of the kind represented by the section title.

KpiDocumentDTO

Name	Type	Description	Notes
documentNumber	String	Unique document identifier (number), mandatory.
documentDate	Date	Document timestamp in ISO 8601 format, UTC timezone. Use yyyy-MM-dd'T'HH:mm:ss'Z' format.
externalUrl	String	The document's URL in an external system, e.g. in e-commerce.	[optional]
trackingUrl	String	The corresponding URL in a logistics provider's system.	[optional]
status	KpiStatusDTO		[optional]
amount	Number	Order sum with .00 precision.	[optional]
currency	String	Order currency.	[optional]
lines	[KpiDocumentLineDTO]	Document lines.	[optional]
fields	[KpiCustomFieldDTO]	Custom fields.	[optional]

KpiStatusDTO

Name	Type	Description	Notes
name	String	Status text.
colorCode	String	One of the supported color codes. If absent, NORMAL is supposed.	[optional]
updatedDate	Date	Status modification timestamp in ISO 8601 format, UTC timezone. Use yyyy-MM-dd'T'HH:mm:ss'Z' format.	[optional]

Color Codes

• NORMAL
• GREEN
• ORANGE
• RED

KpiDocumentLineDTO

Name	Type	Description	Notes
name	String	Item (supposedly, a product or service) name.
quantity	Number	Total quantity bought or sold.	[optional]
delivered	Number	Delivered quantity.	[optional]
url	String	Product or service URL in an external system, e.g. in e-commerce.	[optional]
fields	[KpiCustomFieldDTO]	Custom fields	[optional]
expandableFields	[KpiExpandableDTO]	Additional expandable info section.	[optional]

KpiCustomFieldDTO

Name	Type	Description	Notes
name	String	Custom field name. Nameless fields are allowed only in KpiDocumentDTO.	[optional]
value	String	Custom field value.

KpiExpandableDTO

Name	Type	Description	Notes
columns	[String]	Property names.
fields	[KpiCustomFieldDTO]	Custom fields.	[optional]