Skip to main content

EPOS Data

This section contains the REST version and Websockets version of the EPOS Data API.

The EPOS Data API offers two integration methods for connecting the EPOS system with Dojo: REST and Websockets. These methods can be used separately or in combination depending on your system architecture and data accessibility needs.

REST​

The REST API is ideal for centralized architectures where the EPOS data is hosted on a centralized server. Dojo can interact with the server using standard HTTP methods to access or modify data.

Recommended for:

  • Centralized EPOS data hosted on a server.
  • Stateless communication, where each API request is independent.
  • Asynchronous data access and batch processing.

Websockets​

Visit the getting started page for instructions on establishing a WebSockets connection.

The Websockets API is best for environments where EPOS data resides locally and must be shared with Dojo in real-time. It maintains a persistent connection between the EPOS and Dojo to enable low-latency, continuous data transmission without repeated polling.

Recommended for:

  • On-premise EPOS data that requires real-time synchronization.
  • Persistent, low-latency communication like live transaction updates.

Dojo API Key​

An API Key is required to access the EPOS Data API:

  • You need a key that starts with sk_sandbox_ to access to the sandbox environment.
  • You need a key that starts with sk_prod_ to access the production environment.

In the following examples, {{API_KEY}} is used as a placeholder for the actual API Key.

Registering capabilities​

Register your EPOS Data API endpoints as capabilities in the Dojo API so Dojo knows which functions are available:

You can view the currently registered capabilities using the following API call:

curl --location 'https://api.dojo.tech/epos/integrations' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}'

This will return a list of registered capabilities. If no capabilities are registered, the response will be empty:

{
    "restIntegrations": [],
    "wsIntegrations": []
}

Example: registering GetOrderById on REST​

To register a capability (e.g., GetOrderById), you can use the following command:

curl --location --request PUT 'https://api.dojo.tech/epos/integrations/rest' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}' \
--data '{
  "capabilities": [
    {
      "name": "GetOrderById",
      "version": "v1"
    }
  ],
  "auth": {
    "authType": "basic",
    "basic": {
      "username": "dojo",
      "password": "password"
    }
  },
  "url": " https://f815-86-22-100-52.ngrok-free.app/some/path/v1/orders/{orderID}"
}

This command registers the GetOrderById capability on the REST adapter, making it accessible through the provided URL with basic authentication.

Using the EPOS tester tool​

tip

The EPOS tester tool is used to verify your partner-hosted integration. Don't have access to the EPOS tester tool? Reach out to your Partnership Development Manager.

The API reference for the EPOS tester tool can be found here.

Once you have registered your capabilities, you can test the integration using the epos-tester-tool. This service allows you to test individual API methods or entire transaction flows. It’s designed to facilitate development by letting you trigger Dojo calls programmatically and verify their correctness in real-time.

For example, to list all available flows and their parameters, use the following request:

curl --location 'https://api.dojo.tech/epos-tester-tool/flows' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}'

One such flow is Get Order, which you can trigger using this command:

curl --location 'https://api.dojo.tech/epos-tester-tool/flows' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}' \
--data '{
  "flow": "Get Order",
  "params": {
    "orderId": "testOrderID"
  }
}

This will return a flow ID, which you can use to check the status of the flow:

d00aa12a-7fb8-46a2-a22d-f4b560298353

To check the status, run:

curl --location 'https://api.dojo.tech/epos-tester-tool/flows/d00aa12a-7fb8-46a2-a22d-f4b560298353' \
--header 'Accept: application/json' \
--header 'software-house-id: my-place-curl' \
--header 'Authorization: Basic {{API_KEY}}'

The response will detail the status of the flow and list every step it went through. If a capability like GetOrder was not registered, the response will indicate failure and suggest registering the method:

{
    "finishedAt": "2024-09-19T15:03:23.529Z",
    "flowID": "d00aa12a-7fb8-46a2-a22d-f4b560298353",
    "flowName": "Get Order through EPOS Data API",
    "startedAt": "2024-09-19T15:03:21.226Z",
    "status": "FAILURE",
    "steps": [
        {
            "additionalInformation": [
                "GetOrder method not found",
                "Please register the GetOrder method on an EPOS Data API adapter"
            ],
            "finishedAt": "2024-09-19T15:03:23.524Z",
            "name": "Check whether GetOrder has been registered",
            "startedAt": "2024-09-19T15:03:21.51Z",
            "status": "FAILURE"
        }
    ]
}
Last updated on