Skip to main content

Operation Definitions

The following topics define the endpoints and data models for Pipeline API operations.

Endpoints

GET /api/failed-messages

Summary

The failed messages functionality allows the integrator to track which entities have not been sent to the target address within a particular service. The endpoint, described below, returns information about those orders, drawers, and deposits that have not been transformed successfully according to the service logic or, after three automatic attempts, could not be sent to the target address, such as any errors received from the target address.

The data should be accessible with integrator tokens.

Request Parameters

In

Field Name

Type

Required

Description

header

CONTENT-TYPE

string

Yes

application/json

header

AUTHORIZATION

string

Yes

The integrator token created previously

header

X-COMPANY-ID

string

Yes

The company identifier in our system. The request can be for one company only.

For the integrator tokens, the company token should be the same one received in this parameter.

header

X-SITE-ID

string

Yes

The site identifier in our system. The request can be for one site only and the site should belong to the received company.

query

business_date

string

Yes

The business date for which the erroneous records failed to be transported or transformed.

The date should be sent in a YYYY-MM-DD format or ISO8601 format ('YYYY-MM-DDTHH:MM:SS.SSSZ'), otherwise, an error is logged and returned in the response with readable text.

query

entity

string

Yes

The name of the entity queried. The request can be for one entity only.

The available values are as follows:

  • order

  • drawer

  • deposit

query

target_service

string

No

The name of the target third-party integration service for which our system failed to send, deliver, and transform this record.

If this parameter is received and it is not empty, only those records are retrieved from the storage that contain received service in the corresponding field. Otherwise, this parameter is ignored during the data retrieval.

query

response_type

string

No

This field identifies the format in which data should be retrieved from MongoDB. The format can be identifiers only or full documents.

If this parameter is received and the value is identifier, the result response body will contain an array of identifiers only, which include the following:

  • order.id

  • drawer.event.id

  • deposit.id

Otherwise, the result response will contain full documents from MongoDB.

Sample Request Body

curl --location --request GET 'https://qa-pipeline-api.xenial.com/
failed-messages?business_date=2023-11-02&amp\
--header 'x-company-id: 63da4601b5c13514ecaeac0a' \
--header 'x-site-id: 63da4653b5c13514ecaeac0f' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer token'

Response Examples

The response is in OData format. If a GET request is received with response_type = ids, a list of only unique identifiers found based on the received filters is returned in response.

A Response Example for the Request without the response_type Query Parameters

{
    "items": [
        {
            "_id": "615576e80e5c350011d87296",
            "entity": "deposit",
            "company_id": "5bc702110a9eae001b5813fa",
            "site_id": "5c0e4e894552060017a71a27",
            "business_date": "2021-01-12T00:00:00.000Z",
            "target_service": "altametrics",
            "error_code": 500,
            "error_text": "Internal Server Error",
            "is_processed": false,
            "created_at": "2021-09-30T08:35:52.661Z",
            "updated_at": "2021-09-30T08:35:52.661Z",
            "deposit_id": "1efe2534-569c-41e6-a1b6-73dd6f4869cd"
        }
    ],
    "top": 100,
    "skip": 0,
    "page_size": 1
}

A Response Example for the Request with response_type=ids

{
    "ids": [
        "1efe2534-569c-41e6-a1b6-73dd6f4869cd"
    ]
}

Response Codes

Code

Message Text

Description

200

Success

See Response Examples

400

Validation Error

The response body contains only a readable text of the error received in response

401

Unauthorized

The response body contains only a readable text of the error received in response

500

Error while data processing

The response body contains only a readable text of the error received in response

GET /api/businessdateupdates/orders

Summary

Request order information received during the End of Day (EOD) processes.

Note

See the POST /api/order/v1/publish-external endpoint for information about resending requests.

Request Parameters

In

Field Name

Type

Required

Description

header

CONTENT-TYPE

string

Yes

application/json

header

AUTHORIZATION

string

Yes

The integrator token created previously

header

X-COMPANY-ID

string

Yes

The company unique identifier (UID) in our system:

  • Only one valid 24-digit hexadecimal string at a time.

  • The company UID in this parameter must match the one in the token.

header

X-SITE-IDs

string

Yes

The site UID in our system.

Only one valid 24-digit hexadecimal string at a time.

query

business_date

string

Yes

Only one date at a time and in the YYYY-MM-DDTHH:MM:SS.SSSZ format

query

terminal_id

string

No

The UID for this parameter is provided inside the EOD notifications.

Only one valid 24-digit hexadecimal string at a time.

Example of the terminal_id

{
	"data": {
		"company_id": "60ace72bacb1540007d34630",
		"notification_datetime": "2024-09-07T04:15:34.305Z",
		"site_id": "64f087cb8f45455ca8a7dfe0",
		"store_business_date": "2024-09-07T00:00:00.000Z",
		"store_number": "4851",
		"terminals": [
			{
				"new_business_date": "2024-09-07T00:00:00.000Z",
				"old_business_date": "2024-09-06T00:00:00.000Z",
				"terminal_id": "60c7491a77744e17cf1c5384", <-- this one
				"terminal_name": "Drive Thru Cashier",
				"terminal_number": "4"
			}
		]
	},
	"entityName": "TerminalEOD"
}

Sample Request Body 

curl --location --request GET
'https://qa-pipeline-api.xenial.com/
businessdateupdates/orders?business_date=2024-09-09T00:00:00
.000Z&terminal_id=5a5901f0fcacfe00019a7fda' \
--header 'Content-Type: application/json' \
--header 'x-company-id: 5ee35ad4653fed0009c8ff56' \
--header 'x-site-ids: 5ee35af39c0d910009207773' \
--header 'Authorization: Bearer 
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ…'

Responses

Code

Description

Schema

200

All non-deleted documents are returned in response.

The general response structure:

Field Name

Description

items

An array that contains a list of all found documents based on the received query parameters:

  • Each record represents a unique combination of terminal ID + business date.

  • The orders_by_state object contains a list of orders received from the point of sale (POS) grouped by their state at this specific terminal during the EOD.

total

The total number of found records regardless of the page size

Message: OK

GetBusinessUpdatesOrdersResponseBody

400

Received if the headers or query parameters are invalid.

Message: Bad Request

401

Received if no token is received or if the received token is expired or incorrect.

Message: Unauthorized

403

Received if the supported token does not have the required permissions or if the company does not match the one in the token.

Message: Forbidden

500

Received if any processing errors are received during the request processing.

Message: Internal Server Error

POST /api/order/v1/publish-external

Summary

This request triggers a data resend. If the request is successful, each found order is transformed and sent to the target address separately.

Request Parameters

In

Field Name

Type

Required

Description

header

CONTENT-TYPE

string

Yes

application/json

header

AUTHORIZATION

string

Yes

The integrator token created previously

header

X-COMPANY-ID

string

Yes

The company unique identifier (UID) in our system

header

X-SITE-IDs

string

Yes

The target site UID in our system.

Only one site at a time can be requested.

body

body

PostOrderPublishExternalRequestBody

Yes

The request information

Sample Request Body

curl --location --request POST 'https://order.xenial.com/order/v1/
publish-external' \ --header 'Content-Type: application/json' 
\ --header 'x-company-id: 60ace72bacb1540007d34630' \ --header 
'x-site-ids: 669556fd452a4f5af6de83b0' \ --header 'Authorization: 
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InhwcnQifQ…' \ --data-raw '{ 
"business_date": "2023-10-01", 
"target_service": "dataStream", 
"ignore_deduplication": true, 
"extended_response": true, 
}'

Republish All Orders for a Given Day, for a Given Site, and for All Data Stream Endpoints Configured for this Site

curl --location 'https://order.xenial.com/order/v1/publish-external'
--header 'authorization: Bearer STRING' \
--header 'x-company-id: COMPANY_ID' \
--header 'x-site-ids: SITE_ID' \
--header 'Content-Type: application/json' \
--data '{
    "target_service": "dataStream",
    "business_date": "2025-07-18T00:00:00.000Z",
    "ignore_deduplication": true
}'

Republish Some Orders for a Given Day, for a Given Site, and for All Data Stream Endpoints Configured for this Site

curl --location 'https://order.xenial.com/order/v1/publish-external'
--header 'authorization: Bearer STRING' \
--header 'x-company-id: COMPANY_ID' \
--header 'x-site-ids: SITE_ID' \
--header 'Content-Type: application/json' \
--data '{
    "target_service": "dataStream",
    "business_date": "2025-07-18T00:00:00.000Z",
    "order_numbers": ["809822","9028212"],
    "ignore_deduplication": true
}'

Republish All Orders for a Given Day, for a Given Site, and for Only One Data Stream Endpoint

curl --location 'https://order.xenial.com/order/v1/publish-external'
--header 'authorization: Bearer STRING' \
--header 'x-company-id: COMPANY_ID' \
--header 'x-site-ids: SITE_ID' \
--header 'Content-Type: application/json' \
--data '{
    "target_service": "dataStream",
    "business_date": "2025-07-18T00:00:00.000Z",
    "data_stream_endpoint_id": "63da4653b5c13514ecaeac0d",
    "ignore_deduplication": true
}'

Republish Only Voided Orders for a Given Day, for a Given Site, and for Only One Data Stream Endpoint

curl --location 'https://order.xenial.com/order/v1/publish-external'
--header 'authorization: Bearer STRING' \
--header 'x-company-id: COMPANY_ID' \
--header 'x-site-ids: SITE_ID' \
--header 'Content-Type: application/json' \
--data '{
    "target_service": "dataStream",
    "business_date": "2025-07-18T00:00:00.000Z",
    "order_states": ["voided"],
    "data_stream_endpoint_id": "63da4653b5c13514ecaeac0d",
    "ignore_deduplication": true
}'

Responses

Code

Description

Schema

200

Success.

If at least one order based on the received filters is found, the resend process starts. The following message will be returned in the response body: Found [N] orders, publication was started, where [N] is the number of found orders that will be resent.

If the extended_response query parameter is received with the true value, then the response body contains the additional orders array with details about all the orders found based on the received filters in request.

If no orders are found, the following message is returned in the response body: Found 0 orders, nothing to publish. If the extended_response query parameter is received with the true value, then the response body contains the additional empty orders array.

Message: OK

PostOrderPublishExternalResponseBody

400

One or more parameters from the headers and/or body failed in the validation.

Message: Bad Request

Sample response body:

{ 
    "error": { 
        "status": 400, 
        "detail": 
"Body/ignore_deduplication 
must be boolean", 
        "message": 
"Incorrect format of the 
provided body" 
    } 
}

401

A token is absent, incorrect, or expired.

Message: Unauthorized

403

The token provided does not have the required permissions to perform this action for this company and site.

Message: Forbidden

500

Received if any processing errors are received during the request processing.

Message: Internal Server Error

Data Models

GetBusinessUpdatesOrdersResponseBody

Field Name

Type

Description

items

items Array

An array that contains a list of all found documents based on the received query parameters

total

number

The total number of found records regardless of the page size

items Array

Field Name

Type

Description

_id

string

The unique identifier (UID) for the order

terminal_id

string

The terminal ID

business_date

string

The business date in the YYYY-MM-DDTHH:MM:SS.SSSZ format

orders_by_state

object

The object contains a list of orders received from the point of sale (POS) grouped by their state at this specific terminal during the End of Day (EOD) processes.

See States Array General Structure for the state array items.

States Array General Structure

Field Name

Type

Description

_id

string

The unique identifier (UID) for the order

order_number

string

The order number for the state

net_sales

number

The total number of net sales for the state

gross_sales

number

The total number of gross sales for the state

Order Information Received during EOD Sample Response Code

Received Business Date Only Response Body Example

{
	"items": [
		{
			"_id": "61fd9895703a8e0009c09a33",
			"terminal_id": "5a5901f0fcacfe00019a7fda",
			"business_date": "2024-09-09T00:00:00.000Z"
			"orders_by_state": {
				"closed": [
					{
					"_id": "434891a2-2f88-410d-913d-7887caa0e85d",
					"order_number": "200074",
					"net_sales": 26.78,
					"gross_sales": 29.74
					},
					{
					"_id": "c5e7d62d-fb33-43d2-86a3-fd18f19754d0",
					"order_number": "200075",
					"net_sales": 40.17,
					"gross_sales": 44.60
					},
					{
					"_id": "6f04221a-7982-4e6a-acd4-eb88fa99389b",
					"order_number": "200076",
					"net_sales": 26.78,
					"gross_sales": 29.74
					}
				],
				"deleted": [
					{
					"_id": "46ab0bc3-38ab-41a5-bf6e-091d969c6930",
					"order_number": "200082",
					"net_sales": 0.00,
					"gross_sales": 0.00
					}
				],
				"saved": [
					{
					"_id": "5c0f9deb-f178-43b5-909b-3523e758eed3",
					"order_number": "200077",
					"net_sales": 0.00,
					"gross_sales": 0.00
					},
					{
					"_id": "4fa8f23d-c518-4843-b9c5-470548a1846d",
					"order_number": "200078",
					"net_sales": 0.00,
					"gross_sales": 0.00
					},
					{
					"_id": "5a92b4b9-cfaa-447c-a42b-848933fa3830",
					"order_number": "200079",
					"net_sales": 0.00,
					"gross_sales": 0.00
					},
					{
					"_id": "a9802902-6cce-4132-a0a7-5be0ae3f5948",
					"order_number": "200080",
					"net_sales": 0.00,
					"gross_sales": 0.00
					},
					{
					"_id": "726bcf05-9f5b-4f44-900c-79aa49f9ed01",
					"order_number": "200081",
					"net_sales": 0.00,
					"gross_sales": 0.00
					}
				]
			}
		},
		{
			"_id": "602a566518e0a50001aa900e",
			"terminal_id": "5e3407b6d5897d000a7e325b",
			"business_date": "2024-09-09T00:00:00.000Z",
			"orders_by_state": {
				"closed": [
					{
					"_id": "2e6a1cfd-88bb-48a8-95e4-6490894ab5d1",
					"order_number": null,
					"net_sales": 0.00,
					"gross_sales": 0.00
					},
					{
					"_id": "f26007e4-8351-4b15-a70e-a6ceddfe6293",
					"order_number": "200007",
					"net_sales": 1.69,
					"gross_sales": 1.89
					},
					{
					"_id": "2270c3d6-9a4f-44aa-88e5-7b8eb2c6ee89",
					"order_number": "200023",
					"net_sales": 53.56,
					"gross_sales": 59.46
					},
					{
					"_id": "570aa304-596a-4f3f-841b-cc2a0349f097",
					"order_number": "200025",
					"net_sales": 26.78,
					"gross_sales": 29.74
					},
					{
					"_id": "dee9afb8-f59b-4883-8483-78d6832ef6f1",
					"order_number": "200026",
					"net_sales": 26.78,
					"gross_sales": 29.74
					},
					{
					"_id": "ce0ba606-c540-4adb-a298-dbfa8a1e60a3",
					"order_number": "200027",
					"net_sales": 26.78,
					"gross_sales": 29.74
					},
					{
					"_id": "96724c10-20a2-4d21-b4af-11e5e1278789",
					"order_number": "200028",
					"net_sales": 26.78,
					"gross_sales": 29.74
					},
					{
					"_id": "4e5611d7-2dc2-4e81-8d31-a15ffed6d71f",
					"order_number": "200029",
					"net_sales": 26.78,
					"gross_sales": 29.74
					}
				],
				"unknown": [
					{
					"_id": "976bcf05-9f5b-4f44-900c-79aa49f9ed01",
					"order_number": null,
					"net_sales": 0.00,
					"gross_sales": 0.00
					}
				]
			}
		}
	],
	"total": 2
}

Received Business Date and Terminal ID Only Response Body Example

{
	"items": [
		{
			"_id": "61fd9895703a8e0009c09a33",
			"terminal_id": "5a5901f0fcacfe00019a7fda",
			"business_date": "2024-09-09T00:00:00.000Z",
			"orders_by_state": {
				"closed": [
					{
						"_id": "434891a2-2f88-410d-913d-7887caa0e85d",
						"order_number": "200074",
						"net_sales": 26.78,
						"gross_sales": 29.74
					},
					{
						"_id": "c5e7d62d-fb33-43d2-86a3-fd18f19754d0",
						"order_number": "200075",
						"net_sales": 40.17,
						"gross_sales": 44.60
					},
					{
						"_id": "6f04221a-7982-4e6a-acd4-eb88fa99389b",
						"order_number": "200076",
						"net_sales": 26.78,
						"gross_sales": 29.74
					}
				],
				"deleted": [
					{
						"_id": "46ab0bc3-38ab-41a5-bf6e-091d969c6930",
						"order_number": "200082",
						"net_sales": 0.00,
						"gross_sales": 0.00
					}
				],
				"saved": [
					{
						"_id": "5c0f9deb-f178-43b5-909b-3523e758eed3",
						"order_number": "200077",
						"net_sales": 0.00,
						"gross_sales": 0.00
					},
					{
						"_id": "4fa8f23d-c518-4843-b9c5-470548a1846d",
						"order_number": "200078",
						"net_sales": 0.00,
						"gross_sales": 0.00
					},
					{
						"_id": "5a92b4b9-cfaa-447c-a42b-848933fa3830",
						"order_number": "200079",
						"net_sales": 0.00,
						"gross_sales": 0.00
					},
					{
						"_id": "a9802902-6cce-4132-a0a7-5be0ae3f5948",
						"order_number": "200080",
						"net_sales": 0.00,
						"gross_sales": 0.00
					},
					{
						"_id": "726bcf05-9f5b-4f44-900c-79aa49f9ed01",
						"order_number": "200081",
						"net_sales": 0.00,
						"gross_sales": 0.00
					}
				]
			}
		}
	],
	"total": 1
}

No Records Were Found Response Body Example

{
	"items": [],
	"total": 0
}

PostOrderPublishExternalRequestBody

Field Name

Type

Required

Description

business_date

string

Yes

The target business date for the resend sent in the YYYY-MM-DD format

target_service

string

Yes

If the Data Stream Service is used for the integration with our system, then always use the dataStream value for this field.

For other services, please contact our support team to confirm the correct service name used for the integration.

ignore_deduplication

boolean

Yes

A flag which indicates whether to ignore the duplication. The value is always true.

order_numbers

array of strings

No

If a list of order numbers that should be resent is known, it should be sent here. This parameter should be used only for a specific list of orders, not the entire business day.

If a resend of all orders for the entire business date is needed, ignore this option and use only the necessary body parameters.

Note

Orders with states or types that are not allowed values for the target service are not resent even if their order numbers are received in the request.

order_ids

array of strings

No

A list of order unique identifiers (UIDs) that should be resent.

Same as for the order_numbers array.

extended_response

boolean

No

This parameter regulates whether a short version of the successful response or an extended one with information about all found orders is resent

order_states

array of strings

No

This field is useful for those cases when a resend is required only of orders in a specific state from the whole array of allowed states for the target service.

Example: "order_states":["closed","voided-post-payment"]

order_types

array of strings

No

The same logic as described for the order_states array.

Example: "order_types":["order"]

data_stream_endpoint_id

string

No

This parameter allows data resends only to a specific Data Stream endpoint.

The UID of the endpoint can be found in the endpoint configuration under the Genius Portal → Data Stream → Endpoints Configuration section.

PostOrderPublishExternalResponseBody

Field Name

Type

Description

message

string

The response message

orders

orders Array

A list of the order items returned in the response. This array is returned in response exclusively when the extended_response query parameter is received with the true value.

orders Array

Field Name

Type

Description

_id

string

The unique identifier (UID) for the order

order_number

string

The order number

Order Resend Sample Response Code

Sample Response Body with Orders

  "message": "Found 3 order(s), publication was started", 
  "orders": [ 
       { 
           "_id": "6f444697-636a-4268-b207-f0d501d65b7c", 
           "order_number": "2284206" 
       }, 
       { 
           "_id": "0cf85ba0-f218-40fb-b236-8e3aae0baca3", 
           "order_number": "2284207" 
       }, 
       { 
           "_id": "0b5d5765-102d-4522-9daa-4a0941d7a627", 
           "order_number": "2284208" 
       } 
   ] 
}

Sample Response Body with No Orders

{ 
   "message": "Found 0 order(s), nothing to publish", 
   "orders": [] 
}
See also: