Common API Specification¶

Overview¶

The Common API provides shared utility endpoints including country lookups, web action tracking, and CAPTCHA verification.

Base Path: /common

Content Types: - Request: application/json - Response: application/json

Response Format¶

All endpoints return a TlinqApiResponse object:

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

Date Format: All dates are returned in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss)

Country Lookup Endpoints¶

GET /common/listCountriesByName¶

Lists countries matching the provided name part.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | namepart | string | No | Partial country name to search for | | pk | string | No | System session token | | session | string | No | User session token |

Request Example:

GET /common/listCountriesByName?namepart=United

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "countryId": 784,
      "countryName": "United Arab Emirates"
    },
    {
      "countryId": 826,
      "countryName": "United Kingdom"
    },
    {
      "countryId": 840,
      "countryName": "United States"
    }
  ]
}

POST /common/listCountriesByName¶

Lists countries matching the provided name part (POST version).

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | No | User session token | | namepart | string | No | Partial country name to search for |

Request Example:

{
  "session": "user-session-token",
  "namepart": "Emi"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": [
    {
      "countryId": 784,
      "countryName": "United Arab Emirates"
    }
  ]
}

Web Action Tracking¶

POST /common/wact¶

Registers a web action for tracking user behavior.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | actionType | string | Yes | Type of web action (PAGE_VIEW, CLICK, FORM_SUBMIT, etc.) | | actionData | string | No | Additional action data (JSON string) | | pageUrl | string | No | Current page URL | | referrerUrl | string | No | Referrer URL | | sessionId | string | No | Client session ID | | userId | integer | No | User ID if logged in | | userAgent | string | No | Browser user agent | | ipAddress | string | No | Client IP address |

Request Example:

{
  "actionType": "PAGE_VIEW",
  "actionData": "{\"page\":\"product-detail\",\"productId\":1001}",
  "pageUrl": "https://example.com/products/desert-safari",
  "referrerUrl": "https://example.com/products",
  "sessionId": "sess-abc123",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "actionId": 98765,
    "actionType": "PAGE_VIEW",
    "actionData": "{\"page\":\"product-detail\",\"productId\":1001}",
    "actionTime": "2025-06-15T10:30:00",
    "pageUrl": "https://example.com/products/desert-safari",
    "referrerUrl": "https://example.com/products",
    "sessionId": "sess-abc123",
    "ipAddress": "192.168.1.100",
    "factoryName": "NTSServiceFactory"
  }
}

CAPTCHA Verification¶

POST /common/gcas¶

Verifies a reCAPTCHA token using Google Cloud Assessment Service.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | token | string | Yes | reCAPTCHA token from client | | action | string | Yes | Expected action name |

Request Example:

{
  "token": "03AGdBq24PBCbwij5H8rVvRKPcXK...",
  "action": "login"
}

Response Structure:

href="#__codelineno-8-1">{ "apiStatus": { "errorCode": "OK", "errorMessage": "Success" }, "apiData": { "name": "projects/tourlinq/assessments/abc123xyz", "event": { "token": "03AGdBq24PBCbwij5H8rVvRKPcXK...", "siteKey": "6LdXXXXXAAAAANpMqcl_XXXXX", "expectedAction": "login" }, "riskAnalysis": { "score": 0.9, "reasons": [] }, "tokenProperties": { "valid": true, "action": "login", "hostname": "example.com", "createTime": "2025-06-15T10:29:55Z" } } }

Risk Score Interpretation: | Score Range | Interpretation | |-------------|----------------| | 0.9 - 1.0 | Very likely legitimate user | | 0.7 - 0.9 | Likely legitimate user | | 0.3 - 0.7 | Uncertain, may require additional verification | | 0.0 - 0.3 | Likely bot or automated traffic |

Response on Invalid Token:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "name": "projects/tourlinq/assessments/def456uvw",
    "event": {
      "token": "invalid-token...",
      "expectedAction": "login"
    },
    "riskAnalysis": {
      "score": 0.0,
      "reasons": ["AUTOMATION"]
    },
    "tokenProperties": {
      "valid": false,
      "invalidReason": "EXPIRED",
      "createTime": "2025-06-14T10:00:00Z"
    }
  }
}

Data Models¶

CCountry¶

Field	Type	Description
countryId	integer	Unique country identifier (ISO 3166-1 numeric)
countryName	string	Country name
countryCode	string	ISO 3166-1 alpha-2 code (optional)
countryCode3	string	ISO 3166-1 alpha-3 code (optional)

CWebAction¶

Field	Type	Description
actionId	integer	Unique action identifier
actionType	string	Type of action (PAGE_VIEW, CLICK, FORM_SUBMIT, SEARCH, ADD_TO_CART, PURCHASE)
actionData	string	Additional action data (JSON string)
actionTime	datetime	Timestamp of the action
pageUrl	string	Page URL where action occurred
referrerUrl	string	Referrer URL
sessionId	string	Client session identifier
userId	integer	User ID if authenticated
userAgent	string	Browser user agent
ipAddress	string	Client IP address
factoryName	string	Factory name for persistence

CRecaptchaAssessment¶

Field	Type	Description
name	string	Assessment resource name
event	object	Event details including token and action
riskAnalysis	object	Risk analysis with score (0.0-1.0) and reasons
tokenProperties	object	Token validity and properties