Custom 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 requests similar to GET https://customer.api/rest/kpi?customerId={id} where {id} is an identifier of a specific customer/company.

NB: Only a GET request with customerId query parameter is supported so the endpoint has to be based on that.

The customerId parameter value passed from ITX may contain any of the following identifiers (configurable in ITX):

• Primary key ID
• Entity ID (Social Security Number or Organization Number)
• ITX Customer Number
• Primary Phone Number

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.

Since some of the supported identifiers (Primary key ID, Entity ID, ITX Customer Number, Primary Phone Number) are already known to ITX natively, no prior integration or synchronization with the external information system is strictly required. ITX simply adds the {id} value corresponding to the currently opened customer/company card to the request, using whichever identifier type has been configured. The exception is the external identifier (third party system ID), which assumes that integration / synchronization between ITX and the external information system (whatever it is) was performed beforehand, so that ITX already has the matching external identifier on file.

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]