Creating Journal Entries with Accounting Code >599 - "resource not found"!?

[captgiro]

Any ideas as to why we can create Journal Entries with any Accounting Category up to 599, but after that, FreeAgent returns “resource not found”?

We’ve tried with & without Accounting Category sub-accounts.
We can pull all the accounting categories defined and everything looks hunky dory.

But, if an accounting category from 600 up is used when creating a Journal Entry, FreeAgent returns the error message. “Resource not found”.

Confusingly, the API documentation says the following nominal codes are supported

001 to 049: Income
100 to 199: Cost of Sales
200 to 399: Admin Expenses

But, we can successfully use 400 to 599 too, with the desired effect.

Is this an API bug, or pilot error?

[Ewa_Lipinska]

Hi captgiro,

Ewa here from the Engineering Team at FreeAgent — thanks for your message on our forum and I’ll do my best to help out.

So that I can locate your requests in our logs, and hopefully spot the problem, could I ask that you provide some additional information from the list below?

The name of your app (as registered in Dev Dashboard)
Timestamps of your requests (in UTC)
[Optionally] The IP(s) from which your requests are being sent
Which environment are you querying? (production or sandbox)?

Thanks,

Ewa

[captgiro]

Hello Ewa,

Thanks for following up. I just recreated the problem this morning, to ensure I have the data you requested…

App name in Dev Dashboard: “F3LAB” (I changed it this morning, so should be easy to find in your logs)
Timestamps: I don’t access to transaction log for micro-precision, but I just ran two tests today at 09:33 and 09:34 UTC (according to my PC browser’s time)
IPs: I can let you know privately. Not posting to public forum.
FreeAgent Environment: Production
FreeAgent login url: f3lab2005.freeagent.com

Test 1: Attempted to create Journal Entry for “Computer Equipment Purchase”, code 602-1
Test 2: Attempted to create Journal Entry for “Dividend”, code 908"

[Ewa_Lipinska]

Hi captgiro,

Thanks for providing this additional information – that should be plenty for me to go on. I’ll do a bit of digging and get back to you with my findings as soon as I can.

Best wishes,

Ewa

[Ewa_Lipinska]

Hi again @captgiro,

Thanks a lot for your patience while I was investigating the problems you encountered with creating journal entries in certain accounting categories

You should be able to successfully create journal entries in most categories with codes over 600 by including the base code in the category uri (e.g. the VAT category would be represented as "category":"https://api.freeagent.com/v2/categories/817" in your request body). When you need to post an entry to a category with a sub-account, rather than include the sub-code in the uri, our API expects you to specify the linked resource separately (see documentation for additional journal entry attributes here). For example, when posting to one of the user categories (900-910), your payload should include the following:

 "category":"https://api.freeagent.com/v2/categories/{base code}",
 "user":"https://api.freeagent.com/v2/users/{user id}",

FreeAgent will then infer the correct sub-account code for the user you specified in your request.

The exception to this would be capital asset categories which require a sub-code (601-607). As far as I can tell, and for reasons now deeply buried in our git history, support for passing in a sub-code for those has never been implemented. I’ve opened an issue report to document this problem, which is currently being triaged by our Engineers. Thank you very much for taking the time to highlight this issue and, as soon as I have an update, I’ll make sure to let you know on this thread.

All best,

Ewa

[captgiro]

Ok. Thanks for your speedy feedback Ewa. We’ll work on your suggestions. Creating VAT-related Journal Entries does indeed already work in our app (as neither sub-code nor user resource are required). We can solve the problems with Categories that do need a User resource (which explains the “Resource not found” message back from FreeAgent and can document for our users accordingly) and we’ll revert to not using subcodes to try the Capital Asset categories again.

[captgiro]

Hi Ewa, We’ve solved half the problem, by reverting to retrieving accounting categories WITHOUT sub-codes, and added a “User” attribute for journal items that need it. (We were mislead by the way FreeAgent API returns category descriptions with sub-codes ON).

So, we can now successfully create people-centric journal entries for Dividend, Director Loan Account, etc. Hoorah.

But, journal entries, that use sub-codes in the FreeAgent GUI (eg. Capital Assets), still return a “resource not found” error via the API, even though we’re not using sub-codes in the app. What is the resource that’s missing? Or, is it an incomplete API? You mentioned sub-codes had not been implemented in the API (even though we’re not using them).

We just ran a few tests, against live, you should find in your logs. App name: “F3LAB Pro”. Executed around 17:04 (BST). So, 16:04 in UTC.

[Ewa_Lipinska]

Hi @captgiro,

Great to here that you were able to resolve some of the problems with creating journal sets via our API. As for capital asset categories, you’re right in suspecting our API is at fault here – categories 601-607 must be used with a sub-code, but we don’t currently provide you with a way to pass an individual capital asset type as a resource just like a user or stock item. I’ve raised it with the team as an issue we’ll need to fix, as at the moment you won’t be able to create journal entires in those categories via the API. I’m hoping to be able to roll out a fix for this farily soon, so please watch this space!

Best wishes,

Ewa

[captgiro]

Could you please post an update here when the fix is deployed - then I’ll get a notification (and anyone else that cares will see a conclusion to this thread too). Thanks.

[Ewa_Lipinska]

Hi @captgiro,

I’m pleased to let you know I’ve just deployed a couple of changes to our API to allow creation of journal sets in capital asset categories requiring a sub-code (601-607). We’ve added a new endpoint for Capital Asset Types which will allow you to retrieve the URIs to the resources you’ll need to pass to the capital_asset_type attribute in journal sets (see updated documentation for journal entires here). You’ll notice that this follows the same pattern to the user and stock item categories to ensure consistency.

I hope this helps, but please let me know if you have any further questions.

Best wishes,

Ewa

[captgiro]

Thanks Ewa, We’ll give it a whirl and report back… //Greg

[captgiro]

Ok. We can now read and write Capital Asset Journal Entries, BUT… we noticed a couple of inconsistencies in FA’s API (and an improvement, I’ll explain later). First the inconsistencies:

When creating Journal Entries for Capital Assets, the Accounting Category names (NOT using sub-accounts) in the API reflect the Accounting Category names in the FA GUI… Except for “Capital Asset Disposal”.

In the GUI, it’s called “[Asset Type] Disposal”, but in the API it’s called “Disposal of [Asset Type]”

Ideally, the API should read the same as the GUI. There is consistency for every other asset type and accounting category. I realise, this would be a non-backwards-compatible change, but evidently, no-one else is using it yet, so consistency at this point would be more elegant for this and future integrations.

The GUI looks like this:

Whereas the API fields to create these Journal Entries looks like this:

However, when reading Journal Entries, the Capital Asset Types are incorporated into the Accounting Category (which is how Categories behave when using sub_accounts). This is inconsistent to the way User-centric Journal Entries are returned (with a separate user item attrbute).

…and the improvement. When we first tried to create a user-centric Journal Entry (eg. Dividend) without the User attribute, FA API reported “Resource not found”. Now, the API uses the default User (eg. “me” if I’ve linked to “my” FA account, or the Default User if an Accountant does). This is much better! Thanks.

ps. The API docs need an update, there are a few documentation issues too in Capital Asset Types:

[captgiro]

Glad to see you’re following this. The API description is now better, but there still should be an “s” after “Motor Vehicle”…

[Ewa_Lipinska]

Hi @captgiro,

Thanks a lot for your feedback, it’s much appreciated! As you’ve already seen, the API docs have now been updated to remove the typos which have mischievously snuck into the names of capital asset types (including the missing “s” in “Motor Vehicles”).

As for the naming of the disposal category, I’m not sure if I can reproduce the inconsistency you’re seeing. When creating a journal set in a capital asset disposal category (e.g. 604-1), the API response returns the category code with sub-account but no name:

When I then query the /categories endpoint (with the sub_accounts=true parameter), I get back the name of the category as Computer Equipment Disposal, which is consistent with the web app’s UI:

When I query the /categories endpoint without sub-accounts, 604 is returned as Disposal of Capital Asset but this is also consistent with how the main category is displayed in the web UI:

As for the other problem you spotted, where the capital_asset_type is incorporated in the sub-code rather than getting returned as a separate attribute in the API response, I can see how that would be useful now that we allow you to query individual capital asset types. I’ll flag this as an improvement request to our team, although I can’t promise we’ll be able to implement it straight away as it would change the way journal entries in categories 601-607 are returned for all API users so we’ll need to assess the risks and the best way forward here first.

Best wishes,

Ewa

[captgiro]

Czesc Ewa, sorry for the delay…

The inconsistency in “Disposal” Journal Entry names, is between differents areas of FA GUI.
When manually creating a Journal Set (in the GUI), we see “604-x {Asset Type} Disposal”:

But, when viewing or creating Accounting Categories for Capital Assets, via “Settings”, the Disposal code 604 is named “Disposal of Capital Asset”:

Right now, we’re retrieving Accounting Categories without using sub_classes, to test our app User input, as this works reliably with both simple journal entries (with just one attribute, eg. “Rent”) and also user-centric journal entries (eg. “Dividend” + “User”), and, realistically, these are the most likely use cases.

But, with Capital Assets, we can query the Accounting Categories without sub_classes, and can we then create Journal Entries using those Accounting Categories + Capital Asset Type. But, if an existing Journal Set is queried, there is no mechanism to return back “Category” and “Capital Asset Type” as two attributes via the API. Anyway, I think you understand the point, here. I accept, to change API behaviour would be not backwards compatible, so something like:

GET https://api.freeagent.com/v2/journal_sets?sub_accounts=false

could be used to force separate fields when coming out, and not upset legacy Asset-related Journal Entry API users. It’s also consistent with the API syntax around Categories.

Anyway, I think we concluded this thread. Over to FA Dev’s to review usage stats, and ponder the best solution… //Greg

[Ewa_Lipinska]

Cześć @captgiro ,

Thank you very much for this detailed description, knowing your use case will certainly help us evaluate how best to ensure consistency in the way categories of journal entries are returned. As far as I can tell, journal entries in capital asset categories are the only ones that return a sub-code rather than a resource reference attribute (which made sense until we added a way to query capital asset types directly), so it’s definitely something that should go on our (as you might imagine, ever-growing!) API to-do list.

All best,

Ewa