Getting started and some questions

[cgdae]

Thanks for writing mtd-cli and libmtdac and making them available.

1. I thought it might be useful to other users of devuan-linux (and possibly debian) to have example commands to get started. In my case, for things like this i prefer using LD_PRELOAD to installing in /usr/, so:

   sudo apt install libjansson-dev
   sudo apt install libcurl4-openssl-dev
   git clone https://github.com/ac000/libmtdac.git
   git clone https://github.com/ac000/mtd-cli.git
   (cd libmtdac && make)
   (cd mtd-cli && make)
   export LD_LIBRARY_PATH=libmtdac/src mtd-cli/src/mtd-cli
   export DBUS_SESSION_BUS_ADDRESS=unix:path=/var/run/dbus/system_bus_socket
   

   (On devuan, DBUS_SESSION_BUS_ADDRESS=unix:path=/var/run/dbus/system_bus_socket seems to be required in order for mtd-cli init itsa to (i think) communicate with the web browser.)

2. I struggled a little with what to do after this. What seemed to work is:

   • Follow instructions in libmtdac/README.rst Register with HMRC.

   • Run: mtd-cli/src/mtd-cli init itsa.

   • For Enter your NINO, enter your National insurance number. I've subsequently read about this in the readme, but it confused me for a while.

   • Enter test user user id/pasword.

   • It's probably me, but i got confused by this:

     Follow the login process and accept the requested grants.
     
     Copy and paste the auth code shown on screen into the below prompt.
     
     If a browser window doesn't pop up, you can use the below url.
     
     https://test-api.service.hmrc.gov.uk/...
     
                         Press ENTER to continue
     

     I didn't realise that i had to press ENTER first - i thought mtd-cli had tried and failed to open a web browser, so i opened the URL manually.

3. I'm not sure how i could use mtd-cli to actually create records and send quarterly updates etc. Is there any information about what mtd-cli commands to use? Or should i look at the gov.uk website's description of the REST API and attempt to map back to mtd-cli commands?

Thanks for any help and suggestions.

[ac000]

Hi,

1. Thanks for giving this a try!

2. Yeah, no doubt the documentation could do with some improvements.

3. So mtd-cli just provides raw access to each endpoint supported. (itsa provides a slightly nicer interface but with a more limited scope).

However you should be able to do everything required. For example, to submit a cumulative period update, you would run something like

$ mtd-cli seb cps-update <file> businessId taxYear

Where <file> is a JSON file with the format as described here.

Or should i look at the gov.uk website's description of the REST API and attempt to map back to mtd-cli commands?

Currently that is probably the best way.

Using the endpoints[] array in libmtdac you can map the endpoint URL to an enum value that is used by the various endpoint files in mtd-cli.

E.g. taking the above cumulative period update as an example

We can see it has an endpoint URL of /individuals/business/self-employment/{nino}/{businessId}/cumulative/{taxYear}, looking that up in the endpoints[] array yields

        [MTD_API_EP_SEB_SECPS_AMEND] = {
                .epstr  = "MTD_API_EP_SEB_SECPS_AMEND",
                .tmpl   = "/individuals/business/self-employment/{nino}/{businessId}/cumulative/{taxYear}",
                .method = M_PUT,
                .ctype  = CONTENT_TYPE_JSON,
                .api    = MTD_EP_API_SEB,
        },

Taking the enum value MTD_API_EP_SEB_SECPS_AMEND we can find that in mtd-cli/src/mtd-cli-seb.c

	{
		.name        = "cps-update",
		.api_ep      = MTD_API_EP_SEB_SECPS_AMEND,
		.nr_req_args = 3,
		.file_data   = true,
		.args        = "<file> businessId taxYear"
	}, {

So that shows the endpoint sub-command and required arguments. Near the top of the file is

#define API	seb

That's the name of the endpoint, so we end up with

$ mtd-cli seb cps-update <file> businessId taxYear

Now the idea would be to wrap this up in a shell script once you know all the bits you need for your use case.

Oh and in case you didn't notice there is bash command completion support, simply source bash_completion/mtd-cli and you can always get the basic command usage for each endpoint by mtd-cli endpoint sub-command ? (you also usually omit the ?).

[cgdae]

Thanks for the detailed response, and apologies for not responding sooner.

With the upcoming deadline for the first quarterly update for this financial year due soon, i'd like to figure out whether i'll be able to use mtd-cli or itsa.

I'd prefer to use itsa if it's simpler, but the help from running no args doesn't seem to mention quarterly updates, and's also failing with read_config: No 'business_idx' found (about which more below). Does that mean i'll need to use mtd-cli?

It looks like quarterly updates are handled by the Cumulative Period Summary you mentioned above (i was a bit confused by this as the gov.uk documentation doesn't describe them as cumulative, but then i noticed that for the "Create a Self-Employment Period Summary" it says "Note: This endpoint can only be used for submissions for tax year 2024-25 or earlier. New endpoints which support cumulative submission will be provided for tax year 2025-26 onwards.").

I need to find my businessID, and i've followed the procedure you describe above and end up with command: mtd-cli bd list. However despite my having obtained a authorisation code via mtd-cli init itsa, this is returning an error:

        "result": {
            "code": "CLIENT_OR_AGENT_NOT_AUTHORISED",
            "message": "The client or agent is not authorised"
        }

Do you have any idea what i'm doing wrong here?

Thanks as always for any help.

[ac000]

Hi,

I'd prefer to use itsa if it's simpler, but the help from running no args doesn't seem to mention quarterly updates,

Ah, in itsa quarterly is called a period

$ ./itsa 
...
    list-periods [<start> <end>]
    create-period <tax_year> [<start> <end>]
    update-period <tax_year> <period_id>
...

The create-period and update-period commands currently get the data from the sqlite backend of GNUCash.

Also I think there are a couple of gaps in functionality from what HMRC currently say is the minimum required functionality, so that may block getting production credentials currently.

mtd-cli should be OK though.

and's also failing with read_config: No 'business_idx' found

I'm going to assume you're doing this using the Test API with a test user.

Did you

$ mkdir -p ~/.config/itsa
$ cp config.json.tmpl ~/.config/itsa/config.json

(Note: The config defaults to the test API)

$ itsa init

(Which is like the mtd-cli init itsa command)

It looks like quarterly updates are handled by the Cumulative Period Summary you mentioned above (i was a bit confused by this as the gov.uk documentation doesn't describe them as cumulative,

Heh, I just followed the endpoint naming.

but then i noticed that for the "Create a Self-Employment Period Summary" it says "Note: This endpoint can only be used for submissions for tax year 2024-25 or earlier. New endpoints which support cumulative submission will be provided for tax year 2025-26 onwards.").

Right, so assuming you're operating on tax years from 2025-26 and later, then you use these endpoints.

Which as previously mentioned is this command

$ mtd-cli seb cps-update <file> businessId taxYear

That can be used to create and update cumulative period summaries and from the endpoint documentation you have two options. You can either send a larger non-consolidated request or a simpler consolidated one. E.g. a simple consolidated request passed as the <file> argument.

{
  "periodDates": {
    "periodStartDate": "2025-04-06",
    "periodEndDate": "2025-07-05"
  },
  "periodIncome": {
    "turnover": 1000.99,
    "other": 1000.09,
    "taxTakenOffTradingIncome": 1000.99
  },
  "periodExpenses": {
    "consolidatedExpenses": 1000.99
  }
}

I need to find my businessID, and i've followed the procedure you describe above and end up with command: mtd-cli bd list

Right, that should give you a list of all your businesses.

However despite my having obtained a authorisation code via mtd-cli init itsa, this is returning an error

      "result": {
           "code": "CLIENT_OR_AGENT_NOT_AUTHORISED",
           "message": "The client or agent is not authorised"
      }

From the endpoint documentation

The client and/or agent is not authorised. This is normally because: the client is not subscribed to MTD, the agent is not subscribed to Agent Services, or the client has not authorised the agent to act on their behalf.

What files do you have under $HOME/.config/mtd-cli/libmtdac/test-api? (Don't show their contents)

You should probably have at least creds.json nino.json oauth.json uuid.json

creds.json should contain your client id and client secret
nino.json should contain your National Insurance Number
oauth.json should contain at least an itsa entry with various token stuff
uuid.json should contain a random device id

I would start off with mtd-cli, it should do everything you need. The biggest hurdle you will likely have is actually trying to get production credentials.

Of course there is nothing preventing from using a mixture of the two.

Hope this gets you at least unstuck.