commspace-api-client

Commspace API

• API version: 1.1.2

  • Build date: 2021-09-15T08:32:32.372Z[GMT]

  Authentication In order to use this API you'll need two things to authenticate: - an account_id which identifies which Commspace account (tenant) you're integrating into. This is provided in the url of all api methods /accounts/{account_id}/... - an API Key which authenticates your access to the account. This is provided as a header as described below # Mapping master data Commspace relies on master data (clients, products, intermediaries) supplied by consumer systems in order to do revenue management. We've chosen to implement a consumer-supplied key system to minimize the data mapping burden for consumers. This means that for all master data entities, the consumer supplies their own unique identifier for each entity. Commspace will store that identifier internally and link any subsequent requests with the same identifier to that same entity. In the specification you can easily spot these identifier fields as all fields named with the pattern <entity>_id e.g. client_id, product_id, intermediary_id, etc. Some key mappings (providers, product categories, commission types) have to be pre-configured by the Commspace team ahead of time. We will take responsibility for creating the necessary mappings of your identifiers for each of these entities to their Commspace equivalents - all we require is a full list of the values that you will send. # Generating-Reports Reports can be generated through the methods exposed at the reports root. Because reports can take a long time to generate this API does not support blocking calls i.e. wait until the report is generated before returning a response. This API supports two patterns for non-blocking / asynchronous generation of reports: - Callback pattern. The consumer provides a callback URL to post the report to. This is the preferred pattern. - Polling pattern. The consumer repeatedly polls an endpoint to retrieve the report. ## Callback pattern To make use of this pattern, simply specify a callback_url in the request to /accounts/{account_id}/reports. When the report has been generated, Commspace will submit a POST to the provided URL with the following: - report-token is the report token returned by the createReport call - filename contains a suggested filename. - content is a base64 encoded string of the binary data of the report ## Polling pattern When a report is successfully requested, the API responds with a report_token in the response. Consumers can use this token to poll the endpoint /accounts/{account_id}/reports/{report_token}. If the report isn't available yet, a 202 response will be returned. If the report is available a 200 response including the report will be returned.

Automatically generated by the Swagger Codegen

Requirements

Building the API client library requires:

1. Java 1.7+
2. Maven/Gradle

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>za.co.commspace</groupId>
  <artifactId>commspace-api-client</artifactId>
  <version>1.1.2</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "za.co.commspace:commspace-api-client:1.1.2"

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

• target/commspace-api-client-1.1.2.jar
• target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        UUID reportToken = new UUID(); // UUID | Unique identifier of the report to retrieve
        try {
            ReportResponse result = apiInstance.accountsAccountIdReportsReportTokenGet(accountId, reportToken);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#accountsAccountIdReportsReportTokenGet");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        Page body = new Page(); // Page | 
        try {
            apiInstance.accountsAccountIdTransactionsPost(accountId, body);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#accountsAccountIdTransactionsPost");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        LoadClientsRequest body = new LoadClientsRequest(); // LoadClientsRequest | 
        try {
            apiInstance.postAccountClients(accountId, body);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#postAccountClients");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        CreateReportRequest body = new CreateReportRequest(); // CreateReportRequest | 
        try {
            ReportToken result = apiInstance.postAccountCreateReport(accountId, body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#postAccountCreateReport");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        LoadIntermediariesRequest body = new LoadIntermediariesRequest(); // LoadIntermediariesRequest | 
        try {
            apiInstance.postAccountIntermediaries(accountId, body);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#postAccountIntermediaries");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        TemporaryTokenRequest body = new TemporaryTokenRequest(); // TemporaryTokenRequest | 
        try {
            TemporaryToken result = apiInstance.postAccountSsoTemporaryToken(accountId, body);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#postAccountSsoTemporaryToken");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        String clientId = "clientId_example"; // String | unique identifier by which this client is known at consumer
        try {
            Client result = apiInstance.retrieveClient(accountId, clientId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#retrieveClient");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        String intermediaryId = "intermediaryId_example"; // String | unique identifier by which this intermediary is known at consumer
        try {
            Intermediary result = apiInstance.retrieveIntermediary(accountId, intermediaryId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#retrieveIntermediary");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        String reportId = "reportId_example"; // String | identifier of report to retrieve
        String intermediaryId = "intermediaryId_example"; // String | unique identifier by which the intermediary is known at consumer
        LocalDate startDate = new LocalDate(); // LocalDate | earliest date for which to retrieve report data
        LocalDate endDate = new LocalDate(); // LocalDate | latest date for which to retrieve report data
        String format = "format_example"; // String | desired format of the report
        String productId = "productId_example"; // String | unique identifier by which the product is known at consumer
        String clientId = "clientId_example"; // String | unique identifier by the client is known at consumer
        try {
            ReportResponse result = apiInstance.retrieveIntermediaryReport(accountId, reportId, intermediaryId, startDate, endDate, format, productId, clientId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#retrieveIntermediaryReport");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        String productId = "productId_example"; // String | unique identifier by which this product is known at consumer
        try {
            Product result = apiInstance.retrieveProduct(accountId, productId);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#retrieveProduct");
            e.printStackTrace();
        }
    }
}
import za.co.commspace.*;
import za.co.commspace.auth.*;
import za.co.commspace.api.model.*;
import za.co.commspace.api.DefaultApi;

import java.io.File;
import java.util.*;

public class DefaultApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();

        // Configure API key authorization: ApiKeyAuth
        ApiKeyAuth ApiKeyAuth = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyAuth");
        ApiKeyAuth.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyAuth.setApiKeyPrefix("Token");

        DefaultApi apiInstance = new DefaultApi();
        String accountId = "accountId_example"; // String | unique identifier for account
        String reportId = "reportId_example"; // String | identifier of report to retrieve
        LocalDate startDate = new LocalDate(); // LocalDate | earliest date for which to retrieve report data
        LocalDate endDate = new LocalDate(); // LocalDate | latest date for which to retrieve report data
        String format = "format_example"; // String | desired format of the report
        try {
            ReportResponse result = apiInstance.retrieveReport(accountId, reportId, startDate, endDate, format);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling DefaultApi#retrieveReport");
            e.printStackTrace();
        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://qaapi.commspace.co.za

Class	Method	HTTP request	Description
DefaultApi	accountsAccountIdReportsReportTokenGet	GET /accounts/{account_id}/reports/{report_token}	retrieve report
DefaultApi	accountsAccountIdTransactionsPost	POST /accounts/{account_id}/transactions	Submit revenue transactions
DefaultApi	postAccountClients	POST /accounts/{account_id}/clients	create or update clients
DefaultApi	postAccountCreateReport	POST /accounts/{account_id}/reports	create report
DefaultApi	postAccountIntermediaries	POST /accounts/{account_id}/intermediaries	create or update intermediaries
DefaultApi	postAccountSsoTemporaryToken	POST /accounts/{account_id}/sso/temporarytoken	create temporary sso token
DefaultApi	retrieveClient	GET /accounts/{account_id}/clients/{client_id}	retrieve a client
DefaultApi	retrieveIntermediary	GET /accounts/{account_id}/intermediaries/{intermediary_id}	retrieve an intermediary
DefaultApi	retrieveIntermediaryReport	GET /accounts/{account_id}/intermediaries/{intermediary_id}/reports/{report_id}	retrieve a report for an intermediary
DefaultApi	retrieveProduct	GET /accounts/{account_id}/products/{product_id}	retrieve a product
DefaultApi	retrieveReport	GET /accounts/{account_id}/clients/reports/{report_id}	retrieve a report

Documentation for Models

• Agreement
• AgreementComplianceStatus
• Client
• CreateReportRequest
• ImportError
• ImportErrorList
• Intermediary
• IntermediarySplit
• LoadClientsRequest
• LoadIntermediariesRequest
• Page
• Product
• ProviderCode
• ReportFilter
• ReportResponse
• ReportToken
• TemporaryToken
• TemporaryTokenRequest
• Transaction
• TransactionClientDetails
• TransactionIntermediaryDetails
• TransactionProductDetails

Documentation for Authorization

Authentication schemes defined for the API:

ApiKeyAuth

• Type: API key
• API key parameter name: X-API-Key
• Location: HTTP header

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

api@commspace.co.za