AIM-POS API Integration Guide: Authentication & Product Fetching

This guide provides a step-by-step process to authenticate with and fetch product data from the AIM-POS API using a paginated approach.

---

1. Authentication Overview

AIM-POS API access requires a two-step OAuth authentication flow to obtain the necessary tokens for subsequent requests.

Prerequisites:

• Your unique APIKey
• An AppId (an identifier for your application/integration)
• Valid AIM user credentials (UserName and Password)

---

2. Step 1: Obtain the OAuth Endpoint & Token

This initial request retrieves the correct API endpoint domain and an OAuthToken required for the next step.

• Method: GET
• URL: https://aim-ae.com/aeservices30/api/GetEndPoint
• Headers:
  • APIKey: <Your_APIKey>
  • AppId: <Your_AppId>

Example Response:

{
  "NewEndpointDomain": "https://your-unique-endpoint.aim-ae.com",
  "OAuthToken": "your_oauth_token_here",
  "Status": {
    "StatusCode": "Ok"
  }
}

• Note: Extract and save the NewEndpointDomain and OAuthToken values from this response.

---

3. Step 2: Request the Access Token

Use the endpoint and token from Step 1 to request a final access Token.

• Method: POST
• URL: {NewEndpointDomain}/Api/Security
• Headers:
  • APIKey: <Your_APIKey>
  • OAuthToken: <OAuthToken_from_Step_1>
• Query Parameters:
  • AppId=<Your_AppId>
  • UserName=<Your_Username>
  • Password=<Your_Password>

Example Response:

{
  "Token": "your_final_access_token_here",
  "Status": {
    "StatusCode": "Ok"
  }
}

• Note: This Token is required for all subsequent data requests. Manage its lifecycle according to the API's expiration policy.

---

4. Step 3: Fetch Products with Pagination

To retrieve products, use the GetActiveE3Party endpoint. The API implements pagination; you must loop through the data by adjusting the startOffset parameter until all records are fetched.

Pagination Logic:

• Set recordCount=150 (the maximum recommended records per call).

• Start with startOffset=0.

• If the number of Records returned is less than 150, you have reached the last page.

• If 150 records are returned, increment the startOffset by 150 and make the next request (e.g., startOffset=150, then 300, etc.).

• Method: GET

• URL: {NewEndpointDomain}/api/GetActiveE3Party

• Headers:

  • APIKey: <Your_APIKey>
  • OAuthToken: <OAuthToken_from_Step_1>
  • AppId: <Your_AppId>
  • Token: <Token_from_Step_2>

• Query Parameters:

  • InventoryType=Inventory
  • WebCategory=null (or a specific category if needed)
  • recordCount=150
  • startOffset=<Offset_Value>

Example Request (cURL):

curl --location 'https://your-unique-endpoint.aim-ae.com/api/GetActiveE3Party?InventoryType=Inventory&WebCategory=null&recordCount=150&startOffset=0' \
--header 'APIKey: YOUR_API_KEY' \
--header 'OAuthToken: OAUTH_TOKEN_FROM_STEP_1' \
--header 'AppId: YOUR_APP_ID' \
--header 'Token: ACCESS_TOKEN_FROM_STEP_2'

Example Response:

{
    "StartOffset": 0,
    "RecordCount": 1,
    "Records": [
        {
            "Sku": "1001",
            "Desc": "Bronze Widget",
            "Barcode": "873750123456",
            "Our_Price": 49.0,
            "Qty_Available": 0.0
        }
    ],
    "Status": {
        "StatusCode": "Ok"
    }
}

---

5. Implementation Notes

• Error Handling: Always check the Status.StatusCode in the response before processing data. Implement robust error handling for network issues, authentication failures, and rate limiting.
• Token Management: The Token from Step 2 may have a limited lifespan. Implement logic to detect an expired token (e.g., via an HTTP 401 error) and re-authenticate from Step 1 without manual intervention.
• Performance: Adhere to the pagination limit of 150 records per request to ensure optimal performance and avoid being rate-limited by the API server.