Settle

This API generates a general structure to perform the settlement of records. The API allows the settlement of a great gamut of record structures, aggregations and settlement operations. Currently two aggregation and settlement operations are implemented, but further settlement and aggregation operations will be implemented in future versions. You can contact our development team through the Issues to ask for new settlement and aggregation operations to fit your use case.

API Specification

An abstraction API with all the settlement functionalities.

Settle

A settlement structure has the following parameters:

  • settleid : <string> - Unique identifier of the settlement structure
  • aggregates : <string > - Variables used as input for the aggregation operation.
  • primaryKey : <string> - Primary key used to aggregate metrics, build the common record and make the settlement.
  • aggregationType [1CDR / mcCounter] : <string > - Aggregation operation. This operation is triggered every time a new record is updated to the system.
  • settlementType [1CDR / none] : <string> - Settlement operation. It is triggered whenever a settlement operation is requested. It takes the status of the common record and generates a settled structure. The aggregation variables are cleared for a new round of settlement.
  • record : <string> - Sample record used to define the structure of records in the settlement structure. Also used as the main variable used to upload records.

Sample structure (Click to expand)

{
  "settleid": "settle",
  "aggregates": "['msg']",
  "aggregationType": "mcCounter",
  "primaryKey": "app",
  "settlementType": "string",
  "record": {}
}


API Methods

SettleAPI methods

Settlement methods (Click to expand)


POST - /settlement/create/

Creates a new settlement structure.

Input

  • settleid : <string> - Unique identifier of the settlement structure
  • aggregates : <string > - Variables used as input for the aggregation operation.
  • primaryKey : <string> - Primary key used to aggregate metrics, build the common record and make the settlement.
  • aggregationType [1CDR / mcCounter] : <string > - Aggregation operation. This operation is triggered every time a new record is updated to the system.
  • settlementType [1CDR / none] : <string> - Settlement operation. It is triggered whenever a settlement operation is requested. It takes the status of the common record and generates a settled structure. The aggregation variables are cleared for a new round of settlement.
  • record : <string> - Sample record used to define the structure of records in the settlement structure. Also used as the main variable used to upload records.

Sample structure (Click to expand)

{
  "record": {
   "app":  "4240e1f7-d287-46a9-8b92-f112510bd9f7",
   "op":  "CREATE",
   "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
  },
  "aggregates": ["op"],
  "aggregationType": "mcCounter",
  "settlementType": "none",
  "settleid": "testing",
  "primaryKey": "app"
 }

Output

  • settlementObject : <json>

Sample structure (Click to expand)

{
  "output": {
    "aggregationMetrics": [
      "op"
    ],
    "aggregationType": "mcCounter",
    "lastSettlement": 1565172714,
    "lastUpdate": {
      "operation": "Create",
      "timestamp": 1565172714,
      "user": "test:org1MSP"
    },
    "primaryKey": "app",
    "settleid": "testing",
    "settlementType": "none"
  }
}


GET - /settlement/{settleId}

Gets the current status of a settlement structure. It shows the current status of aggregates.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "aggregates": {
            "2344240e1f7-d287-46a9-8b92-f1232342431": {
                "op": "2"
            },
            "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
                "op": "1"
            }
        },
        "aggregationMetrics": [
            "op"
        ],
        "aggregationType": "mcCounter",
        "lastSettlement": 1565172714,
        "lastUpdate": {
            "operation": "Update",
            "timestamp": 1565172892,
            "user": "test:org1MSP"
        },
        "primaryKey": "app",
        "settleid": "testing",
        "settlementType": "none"
    }
}


GET - /settlement/{settleId}/history

Gets the history of changes over a settlement structure according to updated records.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": [
        {
            "aggregates": {
                "2344240e1f7-d287-46a9-8b92-f1232342431": {
                    "op": "2"
                },
                "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
                    "op": "1"
                }
            },
            "aggregationMetrics": [
                "op"
            ],
            "aggregationType": "mcCounter",
            "lastSettlement": 1565172714,
            "lastUpdate": {
                "operation": "Update",
                "timestamp": 1565172892,
                "user": "test:org1MSP"
            },
            "primaryKey": "app",
            "settleid": "testing",
            "settlementType": "none"
        },
        {
            "aggregationMetrics": [
                "op"
            ],
            "aggregationType": "mcCounter",
            "lastSettlement": 1565172714,
            "lastUpdate": {
                "operation": "Create",
                "timestamp": 1565172714,
                "user": "test:org1MSP"
            },
            "primaryKey": "app",
            "settleid": "testing",
            "settlementType": "none"
        }
    ]
}


GET - /settlement/{settleId}/settled

Gets all settlements performed over a specific settleId.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "aggregates": {
            "2344240e1f7-d287-46a9-8b92-f1232342431": {
                "op": "2"
            },
            "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
                "op": "1"
            }
        },
        "timestamp": 1565186196
    }
}


POST - /settlement/{settleId}/update

It uploads a new record to a settlement structure updating the status of aggregates according to the aggregationType defined for the settling structure.

Input

  • settlementObject : <json>

Sample structure (Click to expand)

{
  "record": [
    {
        "app":  "4240e1f7-d287-46a9-8b92-f112510bd9f7",
        "op":  "CREATE",
        "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
        },
    {
        "app":  "2344240e1f7-d287-46a9-8b92-f1232342431",
        "op":  "CREATE",
        "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
        },
    {
        "app":  "2344240e1f7-d287-46a9-8b92-f1232342431",
        "op":  "DELETE",
        "corr":  "AUS-b8727fc3-dfc1-4c37-b6d6-d6897ed10ddd"
        }
  ]
}

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
  "output": {
    "aggregates": {
      "2344240e1f7-d287-46a9-8b92-f1232342431": {
        "op": "2"
      },
      "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
        "op": "1"
      }
    },
    "aggregationMetrics": [
      "op"
    ],
    "aggregationType": "mcCounter",
    "lastSettlement": 1565172714,
    "lastUpdate": {
      "operation": "Update",
      "timestamp": 1565172892,
      "user": "test:org1MSP"
    },
    "primaryKey": "app",
    "settleid": "testing",
    "settlementType": "none"
  }
}


POST - /settlement/{settleId}/settle

Settles a given settlement structure. It aggregates according to the current status of aggregates and the aggregationType defined for the settlement structure.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "2344240e1f7-d287-46a9-8b92-f1232342431": {
            "op": "2"
        },
        "4240e1f7-d287-46a9-8b92-f112510bd9f7": {
            "op": "1"
        }
    }
}


POST - /settlement/{settleId}/clear

Clears a settlement structure. It removes the current status of the aggregates. This may be used when unconsistent updates have been performed or errors have been detected in the updating of records.

Input

  • settleId : <string>

Output

  • newSettlementObject : <json>

Sample structure (Click to expand)

{
    "output": {
        "aggregationMetrics": [
            "op"
        ],
        "aggregationType": "mcCounter",
        "lastSettlement": 1565186196,
        "lastUpdate": {
            "operation": "Clear",
            "timestamp": 1565186640,
            "user": "test:org1MSP"
        },
        "primaryKey": "app",
        "settleid": "testing",
        "settlementType": "none"
    }
}


Architecture of the project

The project is based on the open-source programming language: Golang. An abstraction of its skeleton is depicted in the diagram below.

coren-tokenapi
├── api
      ├── handler           // HTTP logic
      ├── model             // models used by the application
      ├── service           // Usecases logic
      ├── util              // Tools used by the application
          ├── log           // Logger tool
          ├── http          // Http util
          └── Config        // Tool to load the configuration from yaml files
      └── app.go            // Router application
├── config
      └── config.yaml       // Config file
├── docs
      └── docs.go           // Swagger doc file
├── postman                 // Postman collection and environment to test the API
      ├── collection    
      └── environment
├── vendor                  // Package discovery folder
├── docker-compose.yaml     // Instructions to build docker container
├── Dockerfile              // Instructions to build docker image
├── init.sh                 // Script with global environment variables
└── main.go                 // Main app

How we run the application

As you could see in the Architecture module, all the applications are running on cloud. Through Kubernetes orchestration system the application deployment, scaling and management is an easy and automated task.

Testing the Application

In postman folder there are the collection and environment to interact and test with the API methods. It is only needed to import them into postman application and know to use the coren-settleapi module

Also you can download the files in the links below:

- Postman collection
- Postman environment

Errors management

Settle API errors are managed through the following nomenclature SETTLE-XX which corresponds to:

Code Description
SETTLE-00 Service is down
SETTLE-01 Error parsing any data structure
SETTLE-02 Error of some kind of functionality