Financial transaction batch

This page provides a comprehensive reference for all parameters, endpoints, and behaviors of the Financial Transaction Batch API. Use this guide to understand request/response structures, validation rules, and integration best practices.

Purpose:
This API is used to import and manage batches of financial transactions within ERPx. It supports creating, updating, and deleting batches of financial transactions that can later be validated and imported using the import transactions (GL07) server process.

Base URL:
/v1/financial-transaction-batch

Authentication:
All APIs require Client ID and Client Secret. (Shared authentication details are documented globally.)

Supported Methods

HTTP Method	Endpoint Pattern	Description	Usage Notes / Limits
POST	`/v1/financial-transaction-batch`	Creates a new batch of financial transactions	Only 1 batch per call. Max 10,000 transaction details per batch (hard limit).
PUT	`/v1/financial-transaction-batch`	Modifies or adds transactions in existing batches	Only 1 batch per call. Max 10,000 details per modification. Total batch cannot exceed 200,000 lines.
DELETE	`/v1/financial-transaction-batch/{batchId}/{interfaceId}`	Deletes entries from an existing batch	Only 1 batch per call. Max 500,000 details recommended. Uses URL parameters, not JSON payload.

Swagger / Schema

Version v1

Method Details

Sample Payloads

Request:
The example below posts a simple two line GL transaction only including the currency amount and a single posting dimension with no tax. Note that the majority of the values provided in the individual properties are dependent on the specific setup (accounts, tax codes, posting dimensions, etc).

[
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202301,
            "transactionDate": "2023-01-06T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1110",
                    "accountingDimension1": "100"
                },
                "amounts": {
                    "currencyAmount": -500.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 1,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 1,
            "transactionType": "A1"
        }
    },
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202301,
            "transactionDate": "2023-01-06T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1115",
                    "accountingDimension1": "100"
                },
                "amounts": {
                    "currencyAmount": 500.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 2,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 1,
            "transactionType": "A1"
        }
    }
]

Validation Rules for POST Method

Scenario_001 - User not authorised

Element	Details
Scenario ID	POST_001
Scenario Name	User not authorised
HTTP Code	403
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	User does NOT have permissions
THEN	API is not reached; 403 Forbidden response is returned
Example Error Message	“User is not authorised.”

Scenario_002 - Missing mandatory fields

Element	Details
Scenario ID	POST_002
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	A mandatory field is missing
THEN	Batch is not posted; 422 response is returned
Example Error Message	“The {0} field is required.”

Scenario_003 - Invalid format of fields

Element	Details
Scenario ID	POST_003
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	Field format is invalid
THEN	Batch is not posted; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

Scenario_004 - Unsatisfied model restrictions

Element	Details
Scenario ID	POST_004
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	Field format violates model restrictions (length, range, numeric limits)
THEN	Batch is not posted; 422 response is returned
Example Error Message	“The date must be between {0} and {1}” / “The field {0} must be a string with max length {1}”

Scenario_005 - Unknown companyID

Element	Details
Scenario ID	POST_005
Scenario Name	Unknown companyID
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	Invalid companyID
THEN	Batch is not posted; 422 response is returned
Example Error Message	“Unknown {0}.”

Scenario_006 - Duplicate batchId / interface

Element	Details
Scenario ID	POST_006
Scenario Name	Duplicate batchId / interface
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	batchId / interface combination already exists
THEN	Batch is not posted; 422 response is returned
Example Error Message	“Invalid {0}. Already exists with combination {1}, {2} ({3}, {4}).”

Scenario_007 - Duplicated key values

Element	Details
Scenario ID	POST_007
Scenario Name	Duplicated key values
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	Duplicate keys in batch (client, batchId, interface, transactionNumber, sequenceNumber)
THEN	Batch is not posted; 422 response is returned
Example Error Message	“There is already a line within the batch with combination {0}, {1}, {2}, {3}, {4} ({5}, {6}, {7}, {8}, {9}).”

Scenario_008 - Mixed batchId / interface

Element	Details
Scenario ID	POST_008
Scenario Name	Mixed batchId / interface
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	Not all lines share same batchId / interface
THEN	Batch is not posted; 422 response is returned
Example Error Message	“All imported lines in the batch must have the same values in {0}.”

Scenario_009 - Exceeded 10,000 details

Element	Details
Scenario ID	POST_009
Scenario Name	Exceeded 10,000 details
HTTP Code	422
GIVEN	A batch of transactions needs to be imported
WHEN	Calling the POST method
BUT	JSON contains more than 10,000 details
THEN	Batch is not posted; 422 response is returned
Example Error Message	“This batch contains {0} details which exceeds the maximum allowed {1}.”

Sample Payloads

Request:
The example below works based on the assumption that the example in the POST section of this document was already run. In this example, the transaction that was already posted is modified, distributing the amount that was posted to account 1115 to two different accounting dimensions. In addition a second transaction was also introduced to the batch.

[
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202301,
            "transactionDate": "2023-01-06T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1110",
                    "accountingDimension1": "100"
                },
                "amounts": {
                    "currencyAmount": -500.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 1,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 1,
            "transactionType": "A1"
        }
    },
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202301,
            "transactionDate": "2023-01-06T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1115",
                    "accountingDimension1": "100"
                },
                "amounts": {
                    "currencyAmount": 300.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 2,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 1,
            "transactionType": "A1"
        }
    },
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202301,
            "transactionDate": "2023-01-06T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1115",
                    "accountingDimension1": "120"
                },
                "amounts": {
                    "currencyAmount": 200.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 3,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 1,
            "transactionType": "A1"
        }
    },
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202302,
            "transactionDate": "2023-02-15T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1150",
                    "accountingDimension1": "100"
                },
                "amounts": {
                    "currencyAmount": -320.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 1,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 2,
            "transactionType": "A1"
        }
    },
    {
        "batchInformation": {
            "batchId": "246810",
            "interface": "BI"
        },
        "transactionInformation": {
            "companyId": "EN",
            "period": 202302,
            "transactionDate": "2023-02-15T00:00:00Z",
            "transactionDetailInformation": {
                "accountingInformation": {
                    "account": "1140",
                    "accountingDimension1": "100"
                },
                "amounts": {
                    "currencyAmount": 320.0,
                    "currencyCode": "EUR"
                },
                "lineType": "GL",
                "sequenceNumber": 2,
                "taxInformation": {
                    "taxCode": "ZZ"
                }
            },
            "transactionNumber": 2,
            "transactionType": "A1"
        }
    }
]

Validation Rules for PUT Method

PUT_001 - User not authorised

Element	Details
Scenario ID	PUT_001
Scenario Name	User not authorised
HTTP Code	403
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	User does NOT have permissions
THEN	API is not reached; 403 response is returned
Example Error Message	“User is not authorised.”

PUT_002 - Missing mandatory fields

Element	Details
Scenario ID	PUT_002
Scenario Name	Missing mandatory fields
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	Mandatory field is missing
THEN	Data not updated; 422 response is returned
Example Error Message	“The {0} field is required.”

PUT_003 - Invalid format of fields

Element	Details
Scenario ID	PUT_003
Scenario Name	Invalid format of fields
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	Field format invalid
THEN	Data not updated; 422 response is returned
Example Error Message	“Invalid date time format…” / “Error converting value {0} to type ‘{1}’…”

PUT_004 - Unsatisfied model restrictions

Element	Details
Scenario ID	PUT_004
Scenario Name	Unsatisfied model restrictions
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	Field format violates model restrictions
THEN	Data not updated; 422 response is returned
Example Error Message	“The date must be between {0} and {1}” / “The field {0} must be a string with max length {1}”

PUT_005 - Unknown companyID

Element	Details
Scenario ID	PUT_005
Scenario Name	Unknown companyID
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	Invalid companyID
THEN	Data not updated; 422 response is returned
Example Error Message	“Unknown {0}.”

PUT_006 - Non-existing batchId / interface

Element	Details
Scenario ID	PUT_006
Scenario Name	Non-existing batchId / interface
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	BatchId / interface not found
THEN	Data not updated; 422 response is returned
Example Error Message	“Invalid {0}. No batch in system with {1}, {2}.”

PUT_007 - Duplicated key values

Element	Details
Scenario ID	PUT_007
Scenario Name	Duplicated key values
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	Duplicate keys in batch
THEN	Data not updated; 422 response is returned
Example Error Message	“There is already a line within the batch with combination…”

PUT_008 - Modification exceeds 10,000 details

Element	Details
Scenario ID	PUT_008
Scenario Name	Modification exceeds 10,000 details
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	More than 10,000 details in request
THEN	Data not updated; 422 response is returned
Example Error Message	“This modification exceeds maximum 10,000 details.”

PUT_009 - Total batch limit exceeded 200,000

Element	Details
Scenario ID	PUT_009
Scenario Name	Total batch limit exceeded 200,000
HTTP Code	422
GIVEN	Want to modify existing batch
WHEN	Calling the PUT method
BUT	Inserts push batch beyond 200,000
THEN	Data not updated; 422 response is returned
Example Error Message	“The batch id/interface {0}, {1} contains {2} new details which, added to {3}, exceeds the maximum allowed {4}.”

Sample Payloads

Request:

DELETE /v1/financial-transaction-batch/246810/BI

Validation Rules for DELETE Method

DEL_001 - User is not authorised

Element	Details
Scenario ID	DEL_001
Scenario Name	User is not authorised
HTTP Code	403
GIVEN	Entries of the existing batch need deletion
WHEN	Calling the DELETE method
BUT	User not authorised
THEN	API not reached; 403 response is returned
Example Error Message	“User is not authorised.”

DEL_002 - Missing required parameters

Element	Details
Scenario ID	DEL_002
Scenario Name	Missing required parameters
HTTP Code	404
GIVEN	Entries of the existing batch need deletion
WHEN	Calling the DELETE method
BUT	Required parameter is missing
THEN	API not reached; 404 response is returned
Example Error Message	“No HTTP resource was found matching {0}”

DEL_003 - Non-existing batch

Element	Details
Scenario ID	DEL_003
Scenario Name	Non-existing batch
HTTP Code	404
GIVEN	The whole batch needs deletion
WHEN	Calling the DELETE method
BUT	batchId / interface does not exist
THEN	No deletion; 404 response is returned
Example Error Message	“Entity with [{0}: ‘{1}’, {2}: ‘{3}’] was not found.”

DEL_004 - Non-existing transaction

Element	Details
Scenario ID	DEL_004
Scenario Name	Non-existing transaction
HTTP Code	404
GIVEN	Transaction within the batch needs deletion
WHEN	Calling the DELETE method
BUT	Transaction does not exist
THEN	No deletion; 404 response is returned
Example Error Message	“Entity with parameters [{0}, {1}, {2}] was not found.”

DEL_005 - Non-existing transaction line

Element	Details
Scenario ID	DEL_005
Scenario Name	Non-existing transaction line
HTTP Code	404
GIVEN	Line within the transaction batch needs deletion
WHEN	Calling the DELETE method
BUT	Sequence number is not found
THEN	No deletion; 404 response is returned
Example Error Message	“Entity with parameters [{0}, {1}, {2}, {3}, {4}, {5}, {6}, {7}, {8}, {9}] was not found.”

DEL_006 - Unprocessable entity

Element	Details
Scenario ID	DEL_006
Scenario Name	Unprocessable entity
HTTP Code	400
GIVEN	Entries need deletion
WHEN	Calling the DELETE method
BUT	Incomplete parameters
THEN	No deletion; 400 response is returned
Example Error Message	“The following parameters: {0} must be entered together.”

Best Practices

Only send one batch per call to avoid partial failures.
Respect hard limits:
- POST/PUT: Maximum 10,000 details per call
- PUT: Total batch maximum 200,000 details
- DELETE: Recommended maximum 500,000 details
Use Swagger UI for testing and schema validation before production calls.
Handle error codes gracefully; implement retry/backoff according to global rate limits.
Always check for deprecation alerts on this endpoint version.
Validate IDs and payloads before sending DELETE requests to avoid unintentional data loss.

ERPx

ERPx

U4 ERPx

Financial transaction batch

This page provides a comprehensive reference for all parameters, endpoints, and behaviors of the Financial Transaction Batch API. Use this guide to understand request/response structures, validation rules, and integration best practices.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Payloads

Validation Rules for POST Method

Sample Payloads

Validation Rules for PUT Method

Sample Payloads

Validation Rules for DELETE Method

Best Practices

Action APIs

Query APIs (Read-Only)

U4 ERPx

Financial transaction batch

This page provides a comprehensive reference for all parameters, endpoints, and behaviors of the Financial Transaction Batch API. Use this guide to understand request/response structures, validation rules, and integration best practices.

Supported Methods

Swagger / Schema

Version v1

Method Details

Sample Payloads

Validation Rules for POST Method

Sample Payloads

Validation Rules for PUT Method

Sample Payloads

Validation Rules for DELETE Method

Best Practices

Related endpoints

Action APIs

Financial transaction

Registered financial transaction

Query APIs (Read-Only)

Object financial transaction batch

Object financial transaction batch validation batches

Object financial transaction batch validation trans details

Object financial transaction batch validation transes