it appears that as of about somewhere between three and five days ago, something has changed in the FreeAgent API on the bank transaction explanations endpoint.
I have checked the documentation, but there has been no change with respect to the issue that I am seeing.
My implementation of the FreeAgent API in this area has not changed for probably close to 10 years, and it has been working without issues since I first implemented it. When explaining a bank transaction with a bill, I have never before needed to provide the category field when sending that API request; however, I am getting an API error from FreeAgent with the following details:
POST https://api.freeagent.com/v2/bank_transaction_explanations resulted in a 422 Unprocessable Entity response: {“errors”:[{“message”:“category is not valid for a money-in explanation”}]}
So because I’m not passing a category, the API is now suddenly rejecting my attempt to explain a bank transaction with an already created bill in FreeAgent because the category is not valid - according to the server.
When I assign a category to a bill item, I query that category every single time for FreeAgent API based on its ID, and only when I get back a valid response from the API do I use that category when providing to the bill item. But that’s in the bill. That is not in the request sent to the Bank Transaction Explanations endpoint. If there was a problem with the category in the bill or the bill item, then that would have been flagged, I’m sure, much sooner when I created the bill, but that’s not happening, and the bill entities are perfectly valid.
The Bank Transaction Explanations endpoint does not require a category if I am explaining it with a bill that has already been created.
This sudden change, as I said, has only started in the last few days, so this means that something on your side has changed. I would like you to find that and rectify any recent rollouts that you’ve made.
Thanks for the response! I guess they’ve updated the API to be stricter on that checking. I can’t remember what my code is passing as a value - I think I was just relying on the fact that it’s a ‘bill’ to handle the positive/negative status of the amount. I’ll check that, thanks!
We have made a change recently to make the validation stricter around whether an amount for an explanation is positive or negative. As Andrew correctly diagnosed it is due to your API app sending a paid_bill with a positive gross_value. As this it is a bill being paid we would expect this to have a negative gross_value as it represents money-out.
We did manage to identify the majority of the API applications that would run into this problem and contact developers ahead of time. I’m sorry that we didn’t manage to identify your application as one that would be affected.
Thanks for getting back to me on that. When I changed the direction of the value, it fixed the problem.
I think what could really benefit us is if you had a very simple running log of all the little changes that are applied to an API. It could just be a one-liner, which means if something breaks we can just look up the very simple change log and say, “Oh that maybe applies to what I’m seeing,” and then fix it rather than spend hours trying to debug our code, sending support requests, sending discussions. A very simple one-liner change log for anything that might be breaking or affecting api implementations would really, really help developers. Otherwise, it’s just a black box.
There is a page in the docs that lists notable changes : Changes. To be perfectly honest we’d forgotten to add that change there - I have retrospectively added it now.
Prompted by the recent “tightening” of validation around Bank Transaction Explanations, we thought it prudent to double-check Fabio’s bulk Bank Transaction Explanation support.
We concluded we’re still good. But, FreeAgent’s API doc missed a bit
Specifically, “description” is not required for Bank Transfers, Invoice paymentsOR Bill Payments, in the bank_transaction_explanations endpoint.
But, FreeAgent’s API doc missed a bit 