Quesnelia changes to the transaction API

Issues in Poppy

The transaction API does not support several requests at the same time for the same order or invoice
This is an issue not just for parallel processing for users but also for modules, leading to bugs
Frequent errors when approving or paying invoices require manual workarounds
From mod-orders or mod-invoice, doing several requests to mod-finance in a row means that the previous requests should be rolled back if one request fails, but rollbacks are not implemented
Performance is not good with a large number of order lines or invoice lines, and not scaling well
The code is complex and hard to maintain, which means new bugs can easily be introduced with each change

Many of these issues are caused by usage of transaction summaries in parallel, which the API was not designed for. They led us to rethink the transaction API, to have a way to send all transactions updates in one request and ensure that either all updates are applied or none is and an error is returned.

Deprecated endpoints

These endpoints are deprecated in Quesnelia and will be removed in Ramsons.

Endpoint	Methods

Endpoint	Methods
`/finance/order-transaction-summaries`	`POST`
`/finance/order-transaction-summaries/{id}`	`PUT`
`/finance/invoice-transaction-summaries`	`POST`
`/finance/invoice-transaction-summaries/{id}`	`PUT`
`/finance/allocations`	`POST`
`/finance/transfers`	`POST`
`/finance/encumbrances`	`POST`
`/finance/encumbrances/{id}`	`PUT DELETE`
`/finance/payments`	`POST`
`/finance/payments/{id}`	`PUT`
`/finance/pending-payments`	`POST`
`/finance/pending-payments/{id}`	`PUT`
`/finance/credits`	`POST`
`/finance/credits/{id}`	`PUT`

New endpoint

This new endpoint is available in Quesnelia, and replaces all the deprecated ones.

Ednpoint	Method	Response

Ednpoint	Method	Response
`/finance/transactions/batch-all-or-nothing`	`POST`	204

New endpoint schema

The new endpoint accepts a JSON body formatted like this:

{
  "transactionsToCreate": [],
  "transactionsToUpdate": [],
  "idsOfTransactionsToDelete": [],
  "transactionPatches": []
}

The first 2 entries, transactionsToCreate and transactionsToUpdate, contain entire transaction records. Because the new endpoint does not return anything, transactions to create need to have an id, which will be used to create the record (with the previous POST endpoints this was not required).

idsOfTransactionsToDelete contain only transaction ids.

transactionPatches is not implemented yet. It will include parts of transactions, with the id and the field/values to patch.

This new endpoint has also a new implementation which is faster more reliable than before. A single database transaction is used for all operations, so if anything fails no change will be applied. Validation is a little different but it should only fail if there is a problem (it might fail where it was not before, because of bugs in the previous implementation).

Usage

Previously transactions were created one by one. To send a batch of transactions and have them processed together, we had to create a transaction summary first with the order or invoice id and the expected number of transactions, and send the transactions afterwards. The all-in-one mechanism only worked for a single order or invoice, and a single operation (POST or PUT). Deletions had to be done separately, with a separate request for each deletion.

Transaction summaries are no longer needed with the new endpoint. All creations, updates and deletions should be sent together in a single request, regardless of their order or invoice. The new endpoint has to be used even to just create a single transaction.

Database changes

Tables for transaction summaries and temporary transactions are no longer used in the database. They will be removed in Ramsons.

Implementation details

See UXPROD-4321.

Technical Designs and Decisions