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 ?).