API docs by Redocly

edge-gateway API

Overview

The edge-gateway provides endpoints for edge systems to communicate with the Xpand Cloud. This API enables edge systems to:

  • Report system health and status
  • Synchronize product catalog data incrementally
  • Update inventory states for hives and totes
  • Retrieve and report order fulfillment status

Systems

System health and status reporting

System handshake

Initial handshake endpoint for edge systems to start their workflow with the cloud. A successful handshake requires the system's serial number to be known by the cloud. Otherwise the handshake fails and the system won't be able to make any API calls to the edge-gateway.

A successful handshake effectively exchanges the system's serial number with a cloud systemId. All other API calls require this systemId.

The edge system, represented by the orchestrator in this context, should continue attempting the handshake using some reasonable retry interval until successful if the handshake call fails.

Request Body schema: application/json
required
serialNumber
required
string

Unique system serial number

Responses

Request samples

Content type
application/json
{
  • "serialNumber": "A5YN2"
}

Response samples

Content type
application/json
{
  • "systemId": 42,
  • "siteId": 1
}

System heartbeat

This endpoint should be called regularly (at ~5s intervals) by the edge system following a successful handshake. This endpoint serves two purposes:

  • As a keep alive so that the cloud can assert that this system is both up and running and able to communicate with the cloud, i.e. its internet connection and VPN are working and it able to reach the cloud. This is referred to as "online".

  • As a keep alive from the system's point of view so it knows it is able to reach the cloud.

  • As a means to report the edge system state and status to the cloud. This state includes both health and current tasks.

The cloud should assume that a system is disconnected if is missed 3 consecutive heartbeats, in other words a system's online status has a 15s timeout if no heartbeats are received.

path Parameters
systemId
required
any
Example: 42

System ID

Request Body schema: application/json
required
healthy
required
boolean

Whether the system is operating normally

paused
required
boolean

Whether the system is paused

estop
required
boolean

Whether the system's EStop is engaged

required
object

List of currently enabled tasks

Responses

Request samples

Content type
application/json
{
  • "healthy": true,
  • "paused": true,
  • "estop": true,
  • "enabledTasks": {
    • "fulfillment": true,
    • "consolidation": true
    }
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": {
    • "en_US": "Payment failed",
    • "de_DE": "Zahlung fehlgeschlagen"
    },
  • "details": { }
}

Products

Product catalog synchronization

Get product updates

Retrieve product updates for incremental synchronization.

This is an incremental sync endpoint based on "index" - an atomic increasing only integer that is updated for each create or update operation.

The client should maintain the last currentIndex number it consumed successfully, and use it for the next API call. The server would then filter out and return only records with a higher index number, meaning those that were created or modified since the last call.

Note that given the pagination capability, it is expected that the server will return the products in their index order, and use the maximum index of the page if it is not the last. For the last page the atomic index counter should be used.

The edge-gateway should not return products in the pending state and should not return products of type bundle.

query Parameters
fromIndex
integer >= 0
Default: 0

Get products starting from this index. Use 0 or omit for initial sync. After the initial sync the currentIndex property returned by the server in each call should be used.

pageSize
integer [ 1 .. 100 ]
Default: 100

Maximum number of products to return

Responses

Response samples

Content type
application/json
[
  • {
    • "currentIndex": 1083,
    • "products": [
      • {
        • "id": 1234,
        • "name": {
          • "en_US": "Nature Valley Crunchy",
          • "de_DE": "Nature Valley Knusprig"
          },
        • "description": {
          • "en_US": "Crunchy granola bars made with whole grain oats, peanuts, and honey",
          • "de_DE": "Knusprige Müsliriegel aus Vollkornhafer, Erdnüssen und Honig"
          },
        • "brand": {
          • "en_US": "Nature Valley",
          • "de_DE": "Nature Valley"
          },
        • "identifiers": [
          • {
            • "type": "SKU",
            • "value": "016000275775"
            },
          • {
            • "type": "EAN",
            • "value": "16000275775"
            }
          ],
        • "barcodes": [
          • "016000275775",
          • "16000275775"
          ],
        • "imageUrl": "https://images.example.com/products/nature-valley-crunchy.jpg",
        • "volumeL": 0.18,
        • "weightKg": 0.252,
        • "lengthMm": 180,
        • "widthMm": 120,
        • "heightMm": 25,
        • "temperature": "ambient",
        • "pickingType": "manual"
        }
      ]
    }
]

Hives

Hive inventory state reporting

Report hive entering system

Report that a hive has entered the edge system. This updates the hive's location to be inside the specified system.

Request Body schema: application/json
required
hiveId
required
string

Hive ID of the hive

systemId
required
integer

System ID the hive is entering or exiting

Responses

Request samples

Content type
application/json
{
  • "hiveId": "A001",
  • "systemId": 1
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": {
    • "en_US": "Payment failed",
    • "de_DE": "Zahlung fehlgeschlagen"
    },
  • "details": { }
}

Report hive exiting system

Report that a hive has exited the edge system. This updates the hive's location to be outside the specified system.

Request Body schema: application/json
required
hiveId
required
string

Hive ID of the hive

systemId
required
integer

System ID the hive is entering or exiting

Responses

Request samples

Content type
application/json
{
  • "hiveId": "A001",
  • "systemId": 1
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": {
    • "en_US": "Payment failed",
    • "de_DE": "Zahlung fehlgeschlagen"
    },
  • "details": { }
}

Totes

Tote inventory state reporting

Report tote entering system

Report that a tote has entered the edge system. This updates the tote's location to be inside the specified system and returns the list of products currently in the tote.

Request Body schema: application/json
required
toteId
required
string

Tote ID of the tote

systemId
required
integer

System ID of the system the tote is entering

Responses

Request samples

Content type
application/json
{
  • "toteId": "0184",
  • "systemId": 1
}

Response samples

Content type
application/json
{
  • "products": [
    • {
      • "productId": 123,
      • "quantity": 2
      },
    • {
      • "productId": 456,
      • "quantity": 3
      }
    ]
}

Report tote product quantity

Report the stock level (quantity) of the product productId inside the tote toteId

path Parameters
toteId
required
string

Tote ID of the tote

productId
required
integer

Product ID of the product

Request Body schema: application/json
required
quantity
required
integer

The product quantity in the tote

Responses

Request samples

Content type
application/json
{
  • "quantity": 13
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": {
    • "en_US": "Payment failed",
    • "de_DE": "Zahlung fehlgeschlagen"
    },
  • "details": { }
}

Report tote exiting system

Report that a tote has exited the edge system. This updates the tote's location to be outside the specified system.

Request Body schema: application/json
required
toteId
required
string

Tote ID of the tote

systemId
required
integer

System ID of the system the tote is exiting

hiveId
required
string or null

Hive ID of the hive the tote is in if exiting inside a hive

position
required
string or null

Position within the hive where the tote is located if exiting inside a hive

Responses

Request samples

Content type
application/json
{
  • "toteId": "0184",
  • "systemId": 1,
  • "hiveId": "A001",
  • "position": "1.0"
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": {
    • "en_US": "Payment failed",
    • "de_DE": "Zahlung fehlgeschlagen"
    },
  • "details": { }
}

Orders

Order fulfillment management

Get all relevant orders

Returns all orders relevant to this edge system.

This is an opinionated endpoint for a specific contract between the edge gateway and the edge system, to fulfill various needs of the edge system.

For now, this endpoint should return all orders allocated to this system (based on systemId of the order) with deliveryDate of today.

This will allow the edge system to perform various tasks in relation to these "relevant" orders: display them on UIs, prepare for them based on their product requirements, raise flags if they cannot be fulfilled, and so on.

This definition of "relevant" can change in the future based on specific needs of the edge systems.

path Parameters
systemId
required
integer

System ID of the system

Responses

Response samples

Content type
application/json
[
  • {
    • "id": 842,
    • "status": "queued",
    • "products": [
      • {
        • "productId": 123,
        • "quantity": 2
        },
      • {
        • "productId": 546,
        • "quantity": 1
        }
      ],
    • "priority": 1,
    • "displayCode": 7465,
    • "pinCode": 5364,
    • "user": {
      • "locale": "en_US",
      • "phoneNumber": "+1234567890"
      }
    }
]

Get next order

Retrieve the next order that should be fulfilled by this edge system. The response is idempotent and deterministic for a given cloud state, so the edge system can safely poll this endpoint.

Once an order is returned, the edge system should call PUT /orders/{id} with status fetched to acknowledge receipt. At which point this endpoint should stop returning it, and if called again should return the next order based on its scheduling policy.

If the cloud has no order to provide to the edge system, the response should be a 200 with an empty body.

path Parameters
systemId
required
integer

ID of the edge system requesting the next order

Responses

Response samples

Content type
application/json
{
  • "id": 842,
  • "status": "queued",
  • "products": [
    • {
      • "productId": 123,
      • "quantity": 2
      },
    • {
      • "productId": 546,
      • "quantity": 1
      }
    ],
  • "priority": 1,
  • "displayCode": 7465,
  • "pinCode": 5364,
  • "user": {
    • "locale": "en_US",
    • "phoneNumber": "+1234567890"
    }
}

Update order status

Reports status updates of this order back to the cloud.

The information relevant to the cloud about the order is its status, and the collected quantity of the products in the order.

path Parameters
orderId
required
integer

Order ID

Request Body schema: application/json
required
status
string (EdgeOrderStatusUpdate)
Enum: "fetched" "collecting" "collected" "delivering" "delivered" "error"

The order status transitions that the edge system is allowed to report are:

  • fetched: Order has been fetched by the edge system but has not yet started collection.
  • collecting: Order is currently being fulfilled (collected) by the edge system.
  • collected: Order has been fulfilled (collected) by the edge system.
  • delivering: Order is currently being delivered (pickup) to the user.
  • delivered: Order has been delivered (pickup) to the user.
  • error: An error occurred and processing of the order has stopped, but it might be retried.
Array of objects (EdgeOrderProductUpdate)

Product fulfillment details (required for READY status)

error
string or null

Description of the error that occurred in the edge system when trying to fulfill this order.

This property should only appear when the edge is reporting error status.

Responses

Request samples

Content type
application/json
{
  • "status": "collecting",
  • "products": [
    • {
      • "productId": 123,
      • "quantity": 1
      },
    • {
      • "productId": 546,
      • "quantity": 0
      }
    ]
}

Response samples

Content type
application/json
{
  • "error": "string",
  • "message": {
    • "en_US": "Payment failed",
    • "de_DE": "Zahlung fehlgeschlagen"
    },
  • "details": { }
}