Direct Integration - Validations and Error Handling

When integrating with Accounting as a Service, it's crucial to understand how the system validates incoming data and handles errors. This ensures that data integrity is maintained and that your requests are processed efficiently and correctly. Here's a detailed overview of the validation process and how to manage errors:

Initial Validation by AQI

AQI (Accounting Queue Interface) performs the first layer of validation for incoming requests. The process is as follows:

  • Mandatory Fields Check: AQI checks if all required fields are provided as specified in the API Explorer documentation. If any mandatory fields are missing, the system returns a 400 HTTP error, indicating that the data is incomplete or incorrect.
  • Field Length Validation: Each field has a defined maximum length. If a field's value exceeds this limit, AQI returns a 400 HTTP error response.
  • Allowed Values: Certain fields accept only specific predefined values. AQI verifies that the provided values match the allowed set. If there is a mismatch, a 400 error is returned.
  • System Availability and Credentials: If the AQI system is unavailable or if there are issues with API keys (e.g., incorrect or expired), a 500 HTTP error is returned.

For all 400 and 500 errors, the request is not saved or processed in AQI, and the client must correct the data and resend the request.

Example for 400 error: 

{
    "type" : "RequestBody",
    "title" : "IncorrectMessage",
    "code": 400,
    "description" :"Body of the request does not conform to the definition which is associated with the content type application/json. Path:billToAddress.email Message: String 'null' does not validate against format 'email'. Line: 1, Position: 134 SchemaId: #/components/schemas/BillToAddress/allOf/1/properties/email"
                        }

If the initial validations are successful, AQI returns a 200 HTTP response, indicating that the message has been received, but it has not yet been fully validated. Further validation occurs asynchronously in Accounting as a Service.

Asynchronous Validation in Accounting as a Service

Once AQI accepts a request, it undergoes further validation directly within the Accounting as a Service system. This validation covers:

  • Mandatory Fields Validation: Checks that all mandatory fields are filled, without validating the specific content of those fields.

    • In case of an error, the system indicates which mandatory field was missing.

  • Dependent Mandatory Fields: Some fields become mandatory based on specific conditions, such as payment methods or order types.

    • For example, a Direct Debit payment requires different data (e.g., IBAN) compared to a Credit Card payment.
    • If these dependent fields are missing, an error will be reported specifying the missing field.

  • Content Validations: Ensures that the values provided are unique and interpretable by the system. For example:

    • Currency codes must be valid.
    • Product types and order types must match expected values.
    • Payment methods must be correctly specified.

  • Field Length Checks: The system verifies field lengths against predefined limits. If a value is too long, it may be truncated based on whether the field is critical:

  • Error (Status "E"): For fields affecting downstream processes, exceeding the length results in an error, and the request will not be processed.

  • Warning (Status "W"): For non-critical fields, values exceeding the length are truncated, and the request is processed with a warning noted.

  • Duplicate Submissions: Each request must include a unique transactionId. If this transactionId is reused for a processed request, an error is returned to prevent duplicates.

  • Message Order: Requests must follow the correct sequence. For example, a return order cannot be processed if the initial order has not yet been received and processed in the system.

EDI Error Sent Notification

After validation, Accounting as a Service issues an EDI Error Sent notification, which provides feedback on the processed request:

Error Notification Example:

{
  "parameters": {
    "requestType": "GET_ORDER",
    "transactionId": "0a6b660174a3306898a924639688dffb",
    "details": {
      "orderNo": "ORDPL8100235158",
      "result": "ERROR_IN_FILE",
      "errorDetails": [
        {
          "fieldName": "LINEITEMSTATUS",
          "ErrorDescription": "Field LINEITEMSTATUS must not be empty."
        },
        {
          "fieldName": "BILLTOLANGUAGECODE",
          "providedValue": "PL",
          "ErrorDescription": "The content of field BILLTOLANGUAGECODE may only consist of lower case letters."
        }
      ]
    }

This notification includes the transactionId, orderNo, the result (ERROR_IN_FILE), and specific details about each error encountered. The client should correct the data and resend the request using the information provided in this notification.

Success Notification Example:

{
  "parameters": {
    "requestType": "GET_ORDER",
    "transactionId": "OR20240903100030",
    "details": {
      "orderNo": "996003767",
      "result": "OK",
      "errorDetails": [
        {
          "ErrorDescription": "The request was successfully validated."
        }
      ]
    }
  },
  "type": "accounting/EDIErrorSent"
}

A success message confirms that the data was correct, and no further action is needed. The client can mark the request as confirmed in their system.

General Information for the Interface

  • Request Types: Different request types include get_order (create order), get_cancellation (cancel order), get_goodwill (add goodwill), get_booking_confirmation (create invoice), get_return (return order), get_payment (create payment).
  • Environments: The DataSource specifies the environment (PreProd for UAT or Prod for Production).
  • Result Codes:
    • ERROR_IN_FILE: Indicates that the sent data needs correction and must be resent.
    • OK: Indicates successful validation without errors.

Handling Missing or Unacknowledged Responses

  • Unacknowledged Requests: If no response is received, or if a confirmation is not provided, the client should retry the request.
  • Escalation: If issues persist, a second-level support request can be opened to engage the operational team. They will review the case, ensure that the request is processed, or provide additional guidance.

Understanding and managing these validation processes and error responses are essential for a smooth integration with Accounting as a Service. Properly handling errors and resubmitting corrected data ensures that the business processes continue without disruption.