Skip to main content

FAQ (Frequently Asked Questions)

Authentication & Security​

Why does the AccessToken become invalid after 24 hours?

  • Explanation: Due to security policies, tokens are generated with an expiration time (default 24 hours).
  • Solution: Store the expiry value locally; check it before each request and obtain a new token if it has expired.
  • Tip: Always perform comparisons based on UTC to avoid issues caused by server time differences.

I am getting “401 Unauthorized”; what are the typical reasons?

  • Reasons

    • Missing/incorrect Authorization header format: not Bearer <token>
    • Token has expired
    • Wrong environment token (Demo token → Prod request)

  • Solution

    • Header example Authorization: Bearer eyJhbGciOi… Content-Type: application/json
    • Refresh the token and resend the request.

How can I set up an automatic token refresh flow?

  • Recommended Flow

    • Store the token + expiry locally
    • Before each request, check nowUtc < expiry - skew (skew ~5 min)
    • If needed, refresh via /auth/api/token/connect, then retry the original request Note: Performing a one-time automatic refresh-retry when a 401 is returned is a good practice.

What does “403 Forbidden” mean and how is it resolved?

  • Meaning: No license/service permission or the service is disabled.

  • Checklist

    • Is the CAT API license active?
    • Is the endpoint enabled under “Service Permissions”?
    • Is there a block due to minute/request limits? (0 = unlimited)

What are the requirements for TLS and secure headers?

  • Requirements: TLS 1.2+; all requests over HTTPS.
  • Headers
  • Authorization: Bearer ...Content-Type: application/json
  • If needed, use X-Request-Id to ensure idempotency/traceability.

Listing, Pagination, and Filtering​

Can I fetch all data at once with “GET /CurrentAccountTransaction”?

  • Answer: No. For performance reasons, pagination is mandatory.
  • Defaults: page=1, pageSize=10 (max usually recommended as 100).
  • Example: GET /cat/cat/list?page=1&pageSize=98

Single query or paginated list? How to decide?

Rule

  • Single: If Id or ErpCode is provided, only that record is returned.
  • List: If Id/ErpCode is not provided, a paginated result is returned using page/pageSize.
  • Error: If both are empty and pagination is not provided, a 400 may be returned.

Why is an empty list returned?

Possible Reasons

  • Parameter names are case-sensitive (e.g., ErpCode ≠ erpcode).
  • The filter value is incorrect or no matching record exists. Recommendation: Use parameter names exactly as documented.

How can I improve performance?

Tips

  • Do not send unnecessary filters or large pageSize values.
  • Use indexed fields such as ErpCode/currentAccountErpCode when possible.
  • Split large queries using date ranges.

Agent (Dealer/Customer) and Data Accuracy​

Why is AgentErpCode important and how is it validated?

  • Importance: It is the unique key of the agent (dealer/customer) associated with the transaction.
  • Validation: It must exactly match the code registered in the portal (case sensitivity, punctuation).

What is the difference between currentAccountErpCode and AgentErpCode?

Difference

  • AgentErpCode: the agent performing/associated with the transaction
  • currentAccountErpCode: the current account to which the debt is linked Note: In multi-branch structures, these may differ; it can be sent as an array.

I get “404 Not Found” but the current account exists; why?

Possible Causes

  • The account is inactive/deleted
  • Environment mismatch (exists in Demo, not in Prod)
  • Typo/formatting error Solution: Verify the active status and the correct environment; check parameter names.

Why do conflicts (duplicates) occur?

  • Cause: Attempting to create a record a second time with the same erpCode.
  • Behavior: 409 Conflict.
  • Solution: Use PUT for updates or generate a unique erpCode.

What should be done in case of currency (currencyId) mismatches?

  • Rule: Use ISO codes (TRY, USD, EUR) and ensure they are defined in the system.
  • Error Example
  { 
    "status": "error", 
    "message": "Invalid currencyId", 
    "messageCode": "404" 
  }

Solution: Send values that match the currencies defined in the portal/configuration.

Payments, Refunds, and Debt Notification​

How is notification triggered for overdue debts?

  • Endpoint: POST cat/cat/SendCATDebtInfoMail

  • Conditions

    • PaidAmount ≤ Amount
    • DueDate < now
    • Current account and debt owner are active/not deleted

Response Example

  {  
      "status": "success",  
      "message": "Debt notification contents have been sent"  
  }

If the notification is not sent, what should I check?

  • Is the notification template (Transaction Debt Notification) active?
  • Is email/phone information available?
  • Are user permissions appropriate?
  • Are the record conditions (due date, payment ratio) satisfied?

Where is Mail/SMS priority determined?

  • Answer: In the template rules on the portal side. The API works by applying these rules; the body is sent empty.

The debt is not visible; why?

  • Possible Reasons

    • Record is soft-deleted/inactive
    • Filtering error
    • Querying a different environment

  • Solution: Verify status fields and query parameters.

Any recommendations to reduce notification load?

Recommendations

  • Scheduled triggering (cron) and pre-checking conditions
  • Logging + error/success reporting
  • Pay attention to rate limits (send in intervals to avoid 429)