Reverse Integration

Reverse integration allows external clients to pull data from Sooperwizer using authenticated REST API calls.

This guide covers obtaining an access token from KeyCloak, discovering the reports available to your account, and fetching report data.

Prerequisites

• Integration credentials (username and password) provided by WiMetrix — contact support to request access.
• Network access to {API_URL} and {KEYCLOAK_URL}.
• cURL or an equivalent HTTP client.

Flow Diagram

Step 1 — Obtain an access token

Authenticate with KeyCloak using your integration credentials.

The access_token returned must be sent as a Bearer token in all subsequent API requests.

Endpoint: POST {KEYCLOAK_URL}/realms/wimetrix/protocol/openid-connect/token

curl -X POST "{KEYCLOAK_URL}/realms/wimetrix/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=frontend" \
  -d "scope=openid" \
  -d "username={USERNAME}" \
  -d "password={PASSWORD}"

Step 2 — List available reports

Retrieve the reports available to your account along with the filter schema for each one. Use this to determine which ReportID values you can request and which filters each report requires.

Endpoint: GET {API_URL}/report/get-integrations

Query param	Type	Required	Description
id	number	No	Filter results to a specific ReportID
name	string	No	Search reports by name (partial match)

curl -X GET "{API_URL}/report/get-integrations" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

Each item in the response array has this shape:

Field	Type	Description
ReportID	number	Unique identifier for the report
ReportName	string	Internal report name
DisplayName	string	Human-readable report name
Description	string | null	Optional description
Filters	Record<string, { type, required }>	Filter schema for this report

Each key in Filters is a filter name. The value describes how to provide it in the next step:

type	Value to pass in filters
"single"	A single string — e.g., "2025-01-01"
"list"	An array of strings — e.g., ["BR01", "BR02"]

Filters where required is true must be included in the request body of the next step.

Step 3 — Fetch report data

Submit a data request using the ReportID from the previous step and a filters object constructed from the report’s Filters schema.

Endpoint: POST {API_URL}/report/get-data

curl -X POST "{API_URL}/report/get-data" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ReportID": 1,
    "filters": {
      "StartDate": "2025-01-01",
      "EndDate": "2025-01-31",
      "BranchCode": ["BR01", "BR02"]
    }
  }'

The response is Array<Record<string, unknown>>. Column names and types are determined by the report’s underlying query and vary between reports.

Note

Identical requests (same ReportID and filters) are served from cache. The endpoint returns all matching rows in a single response — there is no pagination.

Error Reference

Status	Endpoint	Cause
403	Both	Missing, invalid, or expired Authorization header
400	get-integrations	Authenticated user lacks the report:integration:get role
400	get-data	Invalid or malformed request body / missing required fields