Epc State Transition - Integration

1. Overview

These APIs are part of a system for:

1. Fetching Realm Mappings (e.g., store/location information) when using realm-based integration.
2. Creating a mapping from a store ID to a specific realm (if needed).
3. Updating EPC States under the selected context (realm-based or external store-based).

Additionally, an Exponential Backoff retry strategy is suggested for handling transient failures.

2. Integration Mechanism

The system supports multiple ways to indicate the context under which you want to update EPC states:

• Realm-Based:
  • Uses the X-REALM-SELECTED-URN header for context switching.
  • Example value: tenant:brand:countrycode:external-store-number (e.g., gdynamite:grg:ca:ca0294).
  • This approach typically requires calling GET /userRealms to find or confirm the correct realmNetworkNamespace.
• External Store ID-Based:
  • Uses the X-EXTERNAL-STORE-ID header for context switching.
  • Example value: US0001.
  • Realm mapping is not required for this integration; you do not need to call /userRealms.
• External Store Number-Based:
  • Uses the X-EXTERNAL-STORE-NUMBER header for context switching.
  • Example value: 0001.
  • Realm mapping is not required for this integration; you do not need to call /userRealms.

3. Authentication

• Mechanism: Basic Authentication
• Header:

  Authorization: Basic <encoded-credentials>

  where <encoded-credentials> is a Base64-encoded string of username:password.
• No Preemptive Authentication: The token/credential is cached for service accounts.

4. Environments and Base URLs

Use the appropriate base URL depending on your environment:

• QA (Testing)

  https://qc-gdynamite.dev.kalama.cloud/gStore/api/v0.2

• Production

  https://production-gdynamite.kalama.cloud/gStore/api/v0.2

5. Sequence Diagrams

Below are example workflows depending on which integration mechanism is used to set the context.

5.1 Realm-Based Sequence Diagram

5.2 External Store ID-Based Sequence Diagram

5.3 External Store Number-Based Sequence Diagram

Key Points:

• For Realm-Based integration, retrieving the realmNetworkNamespace via GET /userRealms is typically required.
• For External Store ID and External Store Number integrations, no realm mapping (and no /userRealms call) is needed.
• The Exponential Backoff retry logic applies regardless of which header is used for context switching.

6. EPC State Transition

6.1 Endpoint

POST /epcs/states

Full URL (QA Example):

POST https://qc-gdynamite.dev.kalama.cloud/gStore/api/v0.2/epcs/states

6.2 Description

This endpoint updates the state of one or more EPCs under the chosen context (realm-based or external store-based).

6.3 Request Headers

Depending on the integration method, one of these headers is used:

• X-REALM-SELECTED-URN: <realmNetworkNamespace>
  Example: gdynamite:grg:ca:ca0294
• X-EXTERNAL-STORE-ID: <storeId>
  Example: US0001
• X-EXTERNAL-STORE-NUMBER: <storeNumber>
  Example: 0001

And in all cases:

• Authorization: Basic <encoded-credentials>

6.4 Request Body

Content-Type: application/json

Sample Request Body:

[
  {
    "epcId": "30340c19e0286080178ffb02",
    "state": "LOCKED",
    "reasonShortText": "Damaged",
    "updatedAt": "2024-04-23T18:25:43.511Z"
  },
  {
    "epcId": "30340c19e0286080178ffb03",
    "state": "FREE",
    "reasonShortText": "Available",
    "updatedAt": "2024-04-23T18:25:43.511Z"
  }
]

6.5 Responses

• 202 Accepted – No Body (indicates the EPC state update was accepted for processing).

7. Realm Mappings (Realm-Based Only)

This section applies only if you are using realm-based integration with X-REALM-SELECTED-URN.

7.1 Endpoint

GET /userRealms

Full URL (QA Example):

GET https://qc-gdynamite.dev.kalama.cloud/gStore/api/v0.2/userRealms

7.2 Description

Retrieves a list of realms (store locations or other realm types) available to the authenticated user.

7.3 Request Headers

• Authorization: Basic <encoded-credentials>

7.4 Response Body

Sample Response:

[
  {
    "realmNetworkNamespace": "gdynamite:grg:ca:ca0294",
    "displayName": "Store#294 GRG | Yorkdale Shopping Centre Toronto On",
    "description": "Store#294 GRG | Yorkdale Shopping Centre Toronto On",
    "isSelected": false,
    "formattedAddress": "3401 Dufferin Street, Yorkdale Shopping Centre, North York, ON, M6A 2T9, Canada",
    "countryCode": "CA",
    "brand": "Garage",
    "type": "STORE",
    "realmLineages": [],
    "storeId": "CA0317",
    "assignedPlaceRealms": []
  }
]

8. HTTP Retry Mechanism with Exponential Backoff

For transient errors (e.g., network timeouts, 5xx responses), use an Exponential Backoff strategy. A common formula is:

RetryInterval = FixedDelay + (BackOffMultiplier * 2^(RetryCount))

• FixedDelay: A base waiting period (e.g., 5 seconds).
• BackOffMultiplier: An additional time factor (e.g., 5 seconds).
• RetryCount: The current attempt number (starting at 1, 2, 3, ...).

8.1 Example: 1-Hour Calibration

Suppose we want to allow retries for up to ~1 hour. Let’s set:

• FixedDelay = 30 seconds
• BackOffMultiplier = 15 seconds
• Maximum retries: Enough attempts so the cumulative wait is near 1 hour (3600 seconds).

By the 7th retry, you are already exceeding 1 hour of total wait time. In a production scenario, you might configure a maximum number of retries or a maximum cumulative wait time (whichever comes first).

Tip: Fine-tune FixedDelay, BackOffMultiplier, and maximum retries based on your application’s SLA and tolerance for delayed processing.

Alternative Calibration Example

9. Summary of Endpoints

9.1 EPC State Transition

• Method: POST
• URL: /epcs/states
• Headers (choose one based on integration method):
  • X-REALM-SELECTED-URN
  • X-EXTERNAL-STORE-ID
  • X-EXTERNAL-STORE-NUMBER
• Body: JSON array of EPC state objects
• Success: 202 Accepted (no body)

9.2 Realm Mappings

• Method: GET
• URL: /userRealms
• Body: None
• Success: 200 OK (returns a JSON array of realm objects)
• Required only if using X-REALM-SELECTED-URN integration.

10. Additional References

• API Headers: Refer to your internal documentation for requirements on headers like Authorization, X-REALM-SELECTED-URN, X-EXTERNAL-STORE-ID, and X-EXTERNAL-STORE-NUMBER.
• Base URL: Refer to Environments and Base URLs above for the correct endpoint.

End of Documentation

For further clarifications on error codes, rate limits, or advanced usage (e.g., bulk updates, filters, partial updates), please contact the API maintainers.