Skip to main content

Reference Data

Introduction

The Connector API for "Reference & Historize Data" allows external payment gateways to interact with the SOClass-based Customs system to exchange Reference and Historize tables.

Search Reference Data

This method allows the caller system to get paginated and filtered Reference or Historize data. When the data have been successfully retrieved, in the response body two values will appear: pageableId and checksum. The pageableId is used to manage further requests, e.g. which page caller to be retrieved. If some of the values of the request are changed, the pagableId will become invalid. The checksum value is used by the Connector endpoint to check if the already calculated data hash of the requested Reference or Historize table is valid (unchanged) or not. If it is valid, the requested pagination will be processed. If it is not valid, the Connector will reload the Reference|HT table, calculate the new checksum and then create a new pagination. The newly created pageableId and checksum will be included in the response with the refreshed data. The both old pageableId and checksum will become invalid.

Example: A certain reference table is retrieved and the following "checksum" is present in the response: "c4f0362db5e1df834853c5f9c59a02ba". After a certain period of time, a new request is sent to the Connector with the same parameters - same binder, table name and type (ARef or not). The request contains a new pagableId (which is normal) but the same checksum like the one in the previous request. This means that during this period no changes have been made in this Reference or Historize table according to the given request parameters.

Reference & HT Plugin Configuration

The following properties can be configured in order to achieve a certain behavior:

Clean period

solink.pageable.refdata.manager.clean.period=600000

A period of time (in milliseconds) after which the Ref&HT Data Managers will be cleaned. This is the period during which the Ref&HT Data endpoint can get next and previous pages. The default value is 10 minutes represented in milliseconds.

Checksum expiration period

solink.refdata.refresh.period=86400000

A period of time (in milliseconds) after which the previously calculated checksum of the Ref or HT Table will be removed and become invalid. The default value is a one day represented in milliseconds.

Checksum Hash Algorithm

solink.refdata.hash.algorithm=SHA3-256

The hash algorithm which will be used to calculate the Ref or HT Table checksum. The default value is "MD5".

Document Modules Configuration

To enable the Ref&HT Data Plugin the following configuration should be set in the current document module descriptor:

- enabled: <true | false>
  pluginName: <DocName>/ref/<Table alias>
  className: com.so.solink.app.apiimpl.core.plugin.generic.ReferenceServicePlugin
  binderName: <Binder name>
  startOperation: <Operation name>
  tableName: <Reference or Historize table name>
  shortcutId: <Optional shortcut ID>
  requestPojoClass: com.so.solink.app.api.refdata.RefRequestPojo
  responsePojoClass: com.so.solink.app.api.refdata.RefDataPageResults

Examples of the Demo Multipages module

- enabled: true
  pluginName: multipages/ref/Country
  className: com.so.solink.app.apiimpl.core.plugin.generic.ReferenceServicePlugin
  binderName: so.demo DemoMultiPages
  startOperation: New
  tableName: CTY_TAB
  shortcutId: 28
  requestPojoClass: com.so.solink.app.api.refdata.RefRequestPojo
  responsePojoClass: com.so.solink.app.api.refdata.RefDataPageResults
 
- enabled: true
  pluginName: multipages/ht/Products
  className: com.so.solink.app.apiimpl.core.plugin.generic.ReferenceServicePlugin
  binderName: so.demo DemoMultiPages
  startOperation: New
  tableName: PRO_TAB_HISTO1
  shortcutId: 28
  requestPojoClass: com.so.solink.app.api.refdata.RefRequestPojo
  responsePojoClass: com.so.solink.app.api.refdata.RefDataPageResults
 
- enabled: true
  pluginName: multipages/ht/ProductsARef
  className: com.so.solink.app.apiimpl.core.plugin.generic.ReferenceServicePlugin
  binderName: so.demo ArefDemoMultiPages
  startOperation: New
  tableName: PRO_TAB_HISTO1
  shortcutId: 30
  requestPojoClass: com.so.solink.app.api.refdata.RefRequestPojo
  responsePojoClass: com.so.solink.app.api.refdata.RefDataPageResults

Historize Tables

ParameterDescription
HTTP REQUESThttps://solink/api/v1/doc/:binder/ht/:tableName/
VERBGET
HEADER
 		Header: Authorization: Bearer <TOKEN>
Accepted Format: [JSON]

ARGUMENTS

ParameterTypeMandatoryHeader/URL/JSON PayloadDescription
access_tokenStringmandatoryHeaderAccess token to connect to the Connector API.
pageableIdStringoptionalURLPagination identifier. If it is empty, a new one will be created or the corresponding one will be used.
checksumStringoptionalURLHistorize table snapshot checksum.
sizeIntoptionalURLNumber of entries returned per page.
pageIntoptionalURLThe ranking number of the first entry on the page.
dateString (Datetime ISO 8601 format)optionalJSONSnapshot date and time.
arefBooleanoptionalURLDetermines if the reference is to ARef or not. Default value or if missing is false.
sortStringoptionalURLThe sort column name.
ascendingBooleanoptionalURLThe sort direction. Default value or if missing is true.
targetStringoptionalJSONThe target column to search for by the keyword.
keywordStringoptionalJSONString representing the words used by the user for filtering the results.

BODY

The body is optional. If specified, it defines the filtering parameters.

Historize Data Body

{
    "date": "2006-02-17T23:00:00.000+0230",
    "target": "Name",
    "keyword": "Bu"
}

Example Request

Request

curl http://solink/api/v1/doc/multipages/ht/Products?page=1&size=25&sort=PRO_COD&aref=false&ascending=false \
-H 'Authorization: Bearer bsdcojzT-9i4q-TaNE-0T8u-gEBcXE2U8jtu'

Response HTTP/1.1 200 OK

{
    "exceptions": [],
    "errors": [],
    "results": {
        "content": [
            {
                "columns": [
                    {
                        "columnName": "PRO_INT",
                        "value": {
                            "type": "String",
                            "content": "01"
                        }
                    },
                    {
                        "columnName": "VALID_FROM",
                        "value": {
                            "type": "Date",
                            "content": "2006-01-17T13:30:00.000+00:00"
                        }
                    },
                    {
                        "columnName": "VALID_TO",
                        "value": {
                            "type": "Date",
                            "content": "2006-03-30T12:30:00.000+00:00"
                        }
                    },
                    {
                        "columnName": "PRO_COD",
                        "value": {
                            "type": "String",
                            "content": "Cheese"
                        }
                    },
                    {
                        "columnName": "PRO_PRI",
                        "value": {
                            "type": "String",
                            "content": "100"
                        }
                    }
                ]
            },
            {
                "columns": [
                    {
                        "columnName": "PRO_INT",
                        "value": {
                            "type": "String",
                            "content": "02"
                        }
                    },
                    {
                        "columnName": "VALID_FROM",
                        "value": {
                            "type": "Date",
                            "content": "2006-01-17T13:30:00.000+00:00"
                        }
                    },
                    {
                        "columnName": "VALID_TO",
                        "value": {
                            "type": "Date",
                            "content": "2006-03-30T12:30:00.000+00:00"
                        }
                    },
                    {
                        "columnName": "PRO_COD",
                        "value": {
                            "type": "String",
                            "content": "Bread"
                        }
                    },
                    {
                        "columnName": "PRO_PRI",
                        "value": {
                            "type": "String",
                            "content": "200"
                        }
                    }
                ]
            }
        ]
    },
    "pageableId": "0b63158b-e3e0-48b5-8e39-3cede712740e",
    "checksum": "c4f0362db5e1df834853c5f9c59a02ba",
    "refreshAfter": "2021-03-11T15:53:05.755+00:00",
    "createdOn": "2021-03-11T15:51:05.755+00:00",
    "changed": false,
    "pageSize": 25,
    "pageNumber": 1,
    "totalPages": 1,
    "totalElements": 2,
    "numberOfElements": 2,
    "sortColumn": "PRO_COD",
    "last": true,
    "firs": true
}

Reference Tables

ParameterDescription
HTTP REQUESThttps://solink/api/v1/doc/:binder/ref/:tableName/
VERBGET
HEADER
 		Header: Authorization: Bearer <TOKEN>
Accepted Format: [JSON]

ARGUMENTS

ParameterTypeMandatoryHeader/URL/JSON PayloadDescription
access_tokenStringmandatoryHeaderAccess token to connect to the Connector API.
pageableIdStringoptionalURLPagination identifier. If it is empty, a new one will be created or the corresponding one will be used.
sizeIntoptionalURLNumber of entries returned per page.
checksumStringoptionalURLReference table checksum.
pageIntoptionalURLThe ranking number of the first entry on the page.
sortStringoptionalURLThe sort column name.
ascendingBooleanoptionalURLThe sort direction. Default value or if missing is true.
arefBooleanoptionalURLDetermines if the reference is to ARef or not. Default value or if missing is false.
targetStringoptionalJSONThe target column to search for by the keyword.
keywordStringoptionalJSONString representing the words used by the user for filtering the results.

BODY

The body is optional. If specified it defines the filtering parameters.

Reference Data Body

{
    "target": "Name",
    "keyword": "Bu"
}

Example Request

Request

curl http://solink/api/v1/doc/multipages/ref/Country?page=1&size=25&sort=Name&aref=false \
-H 'Authorization: Bearer bsdcojzT-9i4q-TaNE-0T8u-gEBcXE2U8jtu'

Response HTTP/1.1 200 OK

{
    "exceptions": [],
    "errors": [],
    "results": {
        "content": [
            {
                "columns": [
                    {
                        "columnName": "Id",
                        "value": {
                            "type": "String",
                            "content": "BG"
                        }
                    },
                    {
                        "columnName": "Name",
                        "value": {
                            "type": "String",
                            "content": "Bulgaria"
                        }
                    }
                ]
            },
            {
                "columns": [
                    {
                        "columnName": "Id",
                        "value": {
                            "type": "String",
                            "content": "BF"
                        }
                    },
                    {
                        "columnName": "Name",
                        "value": {
                            "type": "String",
                            "content": "Burkina Faso"
                        }
                    }
                ]
            },
            {
                "columns": [
                    {
                        "columnName": "Id",
                        "value": {
                            "type": "String",
                            "content": "BI"
                        }
                    },
                    {
                        "columnName": "Name",
                        "value": {
                            "type": "String",
                            "content": "Burundi"
                        }
                    }
                ]
            }
        ]
    },
    "pageableId": "bb517739-6d7c-48eb-be46-d7d0a39af49f",
    "checksum": "a80302e3873e932131bbe38f6c9466a4",
    "refreshAfter": "2021-03-11T15:53:05.755+00:00",
    "createdOn": "2021-03-11T15:51:05.755+00:00",
    "changed": false,
    "pageSize": 25,
    "pageNumber": 1,
    "totalPages": 1,
    "totalElements": 3,
    "numberOfElements": 3,
    "sortColumn": "Name",
    "last": true,
    "firs": true
}

Receive Notification of Reference Data Updates from Connector API

Connector API can send a notification about new data being created or updated in the SOClass Server. In particular the external system can subscribe to receive notification events containing information about reference data.

The following section describes the JSON payload sent by the Connector application.

Notifications are sent using a common JSON payload object called Event, which is defined as follows.

Event Object

FIELDS

NameTypeMandatoryDescription
idStringmandatoryUnique identifier for the event object.
typeStringDescription of the event (e.g., data.created or data.modified).
dataEvent Data objectEvent Data Object that contains either the document, or other objects related to the event.
createdAtStringTime at which the object was created.

Possible events are:

  • cuotab.created;
  • cuotab.modified;
  • cmptab.created;
  • cmptab.modified;
  • etc.

Event Data Object

FIELDS

NameDescription
cuotabCustoms Table Data
cmptabCompany Table Data
ParameterDescription
HTTP REQUESThttps://external-system/api/v1/reference-data
VERBPOST
HEADERAccepted Format: [JSON]

ARGUMENTS

Refer to the Event object, which is the payload used in this web service.

This Event object contains all relevant information about what happened, including the type of event and the data associated with that event. The Connector application sends the Event object via an HTTP POST request.

The external system must define an endpoint in order to receive events, configure the Connector application so that it can send events via POST, verify that the endpoint is valid, and confirm that the endpoint receives events successfully.

To acknowledge receipt of an event, the CAP endpoint must return an HTTP 2xx status code.

The endpoint is disabled if it is unreachable for several consecutive days. All response codes outside of 2xx, including 3xx codes, indicate to the Connector application that the external system did not receive the event.

Example

Request

curl https://external-system/api/v1/reference-data \
-H "SOLink-Signature: t=1492774677,v1=4237a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0cedsgfd435,v0=4gdbb59b2300aae63f272406069a9788598b792a944a07aba816b039gdsgdfg" \
-X POST \ 
-d ' {    
   "id": "xkjh_9238467948273",
   "type": "cuotab.created",
   "createdAt":"2018-01-01Z",
   "dataObjectType": "CUOTAB",
   "dataObject": { 
      "entryId": "3428374",
      "cuoCod":"CUO12",
      "cuoNam": "Customs Office 12", 
      "cuoPhone": "23432423423"
   } 
 }
'

Response HTTP/1.1 200 OK