invoices/aggregation/new

To combine two or more invoices into one aggregated invoice

The aggregation is done on a selected set of IDs provided, and grouped by Currency and VAT

URL

(POST) /api/invoices/aggregation/new

PARAMETERS

The URL takes no parameters

The request BODY should be a JSON object with these properties:

ids	An array of integer ids, each belonging to an Invoice For example: [1, 23, 456] See detailed description further down.	object[], Mandatory
periodFrom	Start date of the financial period for invoice aggregation. Only invoices with an EffectiveDate on or after this date will be included. Example (ISO date strings): "2024-07-14" "2024-07-14T15:30:00" "2024-07-14T15:30:00Z"	DateTime, Mandatory
periodTo	End date of the financial period for invoice aggregation. Only invoices with an EffectiveDate on or before this date will be included. Example (ISO date strings): "2024-11-14" "2024-11-14T15:30:00" "2024-11-14T15:30:00Z"	DateTime, Mandatory
isClientInvoices	Determines whether to aggregate client invoices or supplier invoices. true: Aggregates client invoices only, and ignores supplier invoices false: Aggregates supplier invoices only, and ignores client invoices	bool, Optional
doNotAggregateSingle	Controls whether to skip aggregation of single invoices. Defaults to true Single invoices can result from sending a single invoice id, or from a group of company+currency+vat	bool, Optional

Please note that the given Invoices should:

have a status of InvoiceDraft, invoices with other statuses will be ignored
have an Effective Date between the periodFrom and periodTo mandatory properties
be either Client or Supplier invoices (matching isClientInvoices property)

RESULTS

This method is an asynchronous operation: Your request is queued and will execute as soon as possible.

Asynchronous operations - How to:

The API method immediately returns a JSON object that includes the ID of the operation (look for the requestId property).

However, the operation has not yet been executed. You will need to await the operation’s termination to obtain results.

Waiting can be done in two ways: Polling: Regularly check the operation’s status. Webhook Call: Wait for a callback using the callbackurl parameter in your request. We strongly recommend the latter approach. For more details, please refer to the documentation: Asynchronous operations

The JSON results, obtained with polling or with a callback, include the operation status as well as any results specific to the API method. Below is an example of successful termination:

 {
    "trm": {
        "requestid": 13432,
        "isbatch": false,
        "status": "Finished",
        "statusText": "Finished!"
    },
    "custom": {
        ids: [789, 790]
    }
}

Check the status of trm/status. In case of success, it should say “Finished”.

The node custom/ids returns the list of IDs of the newly created invoices resulting from the aggregation of the given invoice IDs. If no invoices were aggregated, the list will be empty

ERROR HANDLING

Effective error handling involves careful consideration and effort. Let’s break it down into three levels of errors:

Invalid payload

Immediate

If you submit an invalid payload, your API call will immediately be rejected with the error payload typical for the API. Here is an example when submitting an invalid source locale:

{
  "error": {
    "operation": null,
    "date": "2024-11-14T15:20:40.1234567Z",
    "title": "Invalid parameter 'invoiceIds': Please provide invoice IDs to aggregate"
  },
  "reason": "Invalid parameter 'invoiceIds': Please provide invoice IDs to aggregate"
}

Resolution: You likely need to fix your payload.

Operation failed

Delayed

If your payload is valid, your request is now queued. If the operation then fails with a fatal error, you get the async error payload. For example:

{
    "trm": {
        "requestid": 559,
        "isbatch": false,
        "status": "Failed",
        "statusText": "Operation failed!",
        "statusInfo": "The parameter xy was not properly supplied"
    }
}

Resolution: Depending on the error message. You should not see such issues often. If the error details are unclear you may need to reach out to Wordbee support.