- Library version
- Errors
- Data Source
- Fraud Prevention Headers
- Config
- Initialisation functions
- Make Tax Digital - Self-Assessment API functions
- Make Tax Digital - Self-Assessment Accounts API functions [test-only]
- Make Tax Digital - Individuals Business End of Period Statement API functions
- Make Tax Digital - Individual Calculations API functions
- Make Tax Digital - Individual Loses API functions
- Make Tax Digital - Individuals Disclosures API functions
- Make Tax Digital - Business Income Source Summary API functions
- Make Tax Digital - Business Source Adjustable Summary API functions
- Make Tax Digital - Obligations API functions
- Make Tax Digital - Business Details API functions
- Make Tax Digital - VAT API functions
- Make Tax Digital - Create Test User API functions [test-only]
- Make Tax Digital - Test Fraud Prevention Headers API functions [test-only]
#include <libmtdac/mtd.h>
This header is included by each of the API specific header files.
#define LIBMTDAC_MAJOR_VERSION
#define LIBMTDAC_MINOR_VERSION
#define LIBMTDAC_MICRO_VERSION
enum mtd_error {
MTD_ERR_NONE,
MTD_ERR_OS,
MTD_ERR_REQUEST,
MTD_ERR_CURL,
MTD_ERR_NEEDS_AUTHORISATION,
MTD_ERR_UNKNOWN_FLAGS,
MTD_ERR_LIB_TOO_OLD,
MTD_ERR_CONFIG_DIR_UNSPEC,
MTD_ERR_CONFIG_DIR_INVALID,
MTD_ERR_NO_CONFIG,
MTD_ERR_INVALID_EP_API,
MTD_ERR_INVALID_ERROR
};
Apart form MTD_ERR_NONE these errors are returned as **-**MTD_ERR_...
enum mtd_hmrc_error {
MTD_HMRC_ERR_MULTIPLE,
MTD_HMRC_ERR_NO_MESSAGES_PRESENT,
MTD_HMRC_ERR_MATCHING_RESOURCE_NOT_FOUND,
MTD_HMRC_ERR_BUSINESS_ERROR,
MTD_HMRC_ERR_INVALID_REQUEST,
MTD_HMRC_ERR_UNKNOWN
};
These represent error messages returned from the various endpoints (obviously only a few are currently handled).
For requests that send (POST/PUT) data to an endpoint, the source for this data is defined via the following interface
enum mtd_data_src_type {
MTD_DATA_SRC_FILE,
MTD_DATA_SRC_BUF,
MTD_DATA_SRC_FP,
MTD_DATA_SRC_FD,
};
typedef union mtd_data_src {
const void *buf;
const char *file;
FILE *fp;
int fd;
} mtd_data_src_t;
struct mtd_dsrc_ctx {
mtd_data_src_t data_src;
size_t data_len;
enum mtd_data_src_type src_type;
};
You define a struct mtd_dsrc_ctx and set data_src to either a buffer that contains the data, a filename of a file containing the data, a stdio FILE pointer or a file descriptor of an already opened file containing the data to send.
You then set src_type to the appropriate enum mtd_data_src_type value.
In the case of using a buffer you also need to set the length in bytes of the data in the buffer via data_len
#define MTD_FPH_SET_FUNC(s, m, f)
#define MTD_FPH_CLI_PUBLIC_IP fph_srcip
#define MTD_FPH_CLI_PUBLIC_PORT fph_srcport
#define MTD_FPH_CLI_DEV_ID fph_device_id
#define MTD_FPH_CLI_USER_ID fph_user
#define MTD_FPH_CLI_TZ fph_tz
#define MTD_FPH_CLI_LOCAL_IPS fph_ipaddrs
#define MTD_FPH_CLI_MAC_ADDRS fph_macaddrs
#define MTD_FPH_CLI_UA fph_ua
#define MTD_FPH_CLI_MULTI_FACTOR fph_multi_factor
#define MTD_FPH_CLI_SCREENS fph_screens
#define MTD_FPH_CLI_WINDOW_SZ fph_window_sz
#define MTD_FPH_CLI_BROWSER_PLUGINS fph_browser_plugins
#define MTD_FPH_CLI_BROWSER_JS_UA fph_browser_js_ua
#define MTD_FPH_CLI_BROWSER_DNT fph_browser_dnt
#define MTD_FPH_CLI_LOCAL_IPS_TS fph_ipaddrs_ts
#define MTD_FPH_CLI_PUBLIC_IP_TS fph_srcip_ts
#define MTD_FPH_VEN_VERSION fph_version
#define MTD_FPH_VEN_VERSION_CLI fph_version_cli
#define MTD_FPH_VEN_LICENSE_ID fph_license_id
#define MTD_FPH_VEN_PUBLIC_IP fph_vendor_ip
#define MTD_FPH_VEN_FWD fph_vendor_fwd
#define MTD_FPH_VEN_PROD_NAME fph_prod_name
struct mtd_fph_ops {
char *(*fph_device_id)(void *user_data);
char *(*fph_user)(void *user_data);
char *(*fph_tz)(void *user_data);
char *(*fph_ipaddrs)(void *user_data);
char *(*fph_ipaddrs_ts)(void *user_data);
char *(*fph_macaddrs)(void *user_data);
char *(*fph_srcip)(void *user_data);
char *(*fph_srcip_ts)(void *user_data);
char *(*fph_srcport)(void *user_data);
char *(*fph_screens)(void *user_data);
char *(*fph_window_sz)(void *user_data);
char *(*fph_browser_plugins)(void *user_data);
char *(*fph_browser_js_ua)(void *user_data);
char *(*fph_browser_dnt)(void *user_data);
char *(*fph_vendor_ip)(void *user_data);
char *(*fph_vendor_fwd)(void *user_data);
char *(*fph_ua)(void *user_data);
char *(*fph_multi_factor)(void *user_data);
char *(*fph_license_id)(void *user_data);
char *(*fph_version)(void *user_data);
char *(*fph_version_cli)(void *user_data);
char *(*fph_prod_name)(void *user_data);
void *user_data;
};
This can be used to override the in built functions that generate the various fraud prevention header values. You can set any or all of them, any that are set to NULL will use the appropriate inbuilt function.
These functions should return a pointer to a dynamically allocated buffer that will be free(3)'d by the library.
You should probably take a quick look at the Fraud Prevention Headers section of the README.md to understand the possible privacy implications.
struct mtd_cfg {
const struct mtd_fph_ops *fph_ops;
const char * const *extra_hdrs;
const char *config_dir;
};
This is a structure that can be passed into mtd_init() to provide/override configuration data.
Firstly, it can be used for overriding the fraud prevention headers. A user could declare a struct mtd_fph_ops and set various members to their own functions then set mtd_cfg.fph_ops to this structure and pass it into mtd_init() e.g
Finally you need to specify the directory that libmtdac will use for its config data.
Typically this would be something like ${HOME}/.config/${APP_NAME}
const struct mtd_fph_ops fph_ops = {
.fph_user = my_user,
.fph_version = my_ver
};
const struct mtd_cfg cfg = {
.fph_ops = &fph_ops,
.config_dir = "/home/foo/.config/mtd-cli"
};
err = mtd_init(flags, &cfg);
You can also use the MTD_FPH_SET_FUNC() macro, e.g
struct mtd_fph_ops fph_ops = { NULL };
const struct mtd_cfg cfg = {
.fph_ops = &fph_ops,
.config_dir = "/home/foo/.config/mtd-cli"
};
MTD_FPH_SET_FUNC(fph_ops, MTD_FPH_CLI_USER_ID, my_user);
MTD_FPH_SET_FUNC(fph_ops, MTD_FPH_VEN_VERSION, my_ver);
The macro takes a struct mtd_fph_ops, the name of the structure member to set (here we use the defined macro names, but you can use either) and the function to set it to.
Secondly, you can use the extra_hdrs member to add extra HTTP headers to be sent, e.g a Gov-Test-Scenario header. E.g
const char *hdrs[2] = { NULL };
const struct mtd_cfg cfg = {
.extra_hdrs = hdrs,
.config_dir = "/home/foo/.config/mtd-cli"
};
hdrs[0] = getenv("MTD_CLI_HDRS");
extra_hdrs should point to a NULL terminated array of character pointers.
void mtd_global_init(void);
This function should be called before any other threads are running. In a non-threaded application you can skip this function and pass
MTD_OPT_GLOBAL_INIT
to mtd_init() instead.
int mtd_init(unsigned int flags, const struct mtd_cfg *cfg);
This function should be called once in each thread where libmtdac is to be used.
flags can currently be one of the following to specify the desired log level (defaults to MTD_OPT_LOG_ERR)
MTD_OPT_LOG_ERR
MTD_OPT_LOG_INFO
MTD_OPT_LOG_DEBUG
it can also be OR'd with one of the following to specify the application connection type. Only used when sending fraud prevention headers. Defaults to MTD_OPT_ACT_OTHER_DIRECT if not specified.
MTD_OPT_ACT_MOBILE_APP_DIRECT
MTD_OPT_ACT_DESKTOP_APP_DIRECT
MTD_OPT_ACT_MOBILE_APP_VIA_SERVER
MTD_OPT_ACT_DESKTOP_APP_VIA_SERVER
MTD_OPT_ACT_WEB_APP_VIA_SERVER
MTD_OPT_ACT_BATCH_PROCESS_DIRECT
MTD_OPT_ACT_OTHER_DIRECT
MTD_OPT_ACT_OTHER_VIA_SERVER
if you don't wish to send fraud prevention headers then you can set
MTD_OPT_NO_ANTI_FRAUD_HDRS
however they are mandatory...
for headers that have no value, by default we will skip sending that header, however if you wish to send an empty header you can set
MTD_OPT_SND_EMPTY_HDRS
in a single-threaded application, when not calling mtd_global_init()
MTD_OPT_GLOBAL_INIT
cfg is as described in Config above.
int mtd_init_auth(enum mtd_ep_api api, unsigned long scopes);
This function takes an enum describing what API (ITSA, VAT etc) this is adding authorisations for, it takes one of the following
MTD_EP_API_ITSA
MTD_EP_API_VAT
the above can be optionally bitwise OR'd with
MTD_EP_API_ADD
which says don't reset the oauth.json file when writing it, instead add this OAuth as another entry.
The second argument is a bitwise OR'd list of scopes that the application should be authorised for, the scopes available are
MTD_SCOPE_RD_SA
MTD_SCOPE_WR_SA
MTD_SCOPE_RD_VAT
MTD_SCOPE_WR_VAT
int mtd_init_creds(enum mtd_ep_api api);
int mtd_init_nino(void);
void mtd_deinit(void);
char *mtd_percent_encode(const char *str, ssize_t len);
const char *mtd_err2str(int err);
const char *mtd_err2enum_str(int err);
enum mtd_http_status_code mtd_http_status_code(const char *json);
Which returns one of the following enum values, which are mapped to the actual status code value
MTD_HTTP_OK
MTD_HTTP_CREATED
MTD_HTTP_ACCEPTED
MTD_HTTP_NO_CONTENT
MTD_HTTP_SEE_OTHER
MTD_HTTP_BAD_REQUEST
MTD_HTTP_UNAUTHORIZED
MTD_HTTP_FORBIDDEN
MTD_HTTP_NOT_FOUND
MTD_HTTP_METHOD_NOT_ALLOWED
MTD_HTTP_NOT_ACCEPTABLE
MTD_HTTP_GONE
MTD_HTTP_REQUEST_ENTITY_TOO_LARGE
MTD_HTTP_UNSUPPORTED_MEDIA_TYPE
MTD_HTTP_TOO_MANY_REQUESTS
MTD_HTTP_INTERNAL_SERVER_ERROR
MTD_HTTP_NOT_IMPLEMENTED
MTD_HTTP_SERVICE_UNAVAILABLE
MTD_HTTP_GATEWAY_TIMEOUT
const char *mtd_http_status_str_u(const char *json);
const char *mtd_http_status_str(const char *json);
enum mtd_hmrc_error mtd_hmrc_error(const char *json);
#include <libmtdac/mtd-sa.h>
int mtd_sa_se_create_employment(const struct mtd_dsrc_ctx *dsctx,
char **buf)
int mtd_sa_se_list_periods(const char *seid, char **buf);
int mtd_sa_se_create_period(const struct mtd_dsrc_ctx *dsctx,
const char *seid, char **buf);
int mtd_sa_se_get_period(const char *seid, const char *period_id,
char **buf);
int mtd_sa_se_update_period(const struct mtd_dsrc_ctx *dsctx,
const char *seid, const char *period_id,
char **buf);
int mtd_sa_se_get_annual_summary(const char *seid, const char *tax_year,
char **buf);
int mtd_sa_se_update_annual_summary(const struct mtd_dsrc_ctx *dsctx,
const char *seid,
const char *tax_year, char **buf);
int mtd_sa_pb_create_property(const struct mtd_dsrc_ctx *dsctx,
char **buf);
int mtd_sa_pb_list_non_fhl_periods(char **buf);
int mtd_sa_pb_create_non_fhl_period(const struct mtd_dsrc_ctx *dsctx,
char **buf);
int mtd_sa_pb_get_non_fhl_period(const char *pid, char **buf);
int mtd_sa_pb_update_non_fhl_period(const struct mtd_dsrc_ctx *dsctx,
const char *pid, char **buf);
int mtd_sa_pb_get_non_fhl_annual_summary(const char *tax_year,
char **buf);
int mtd_sa_pb_update_non_fhl_annual_summary(const struct mtd_dsrc_ctx *dsctx,
const char *tax_year,
char **buf);
int mtd_sa_pb_list_fhl_periods(char **buf);
int mtd_sa_pb_create_fhl_period(const struct mtd_dsrc_ctx *dsctx,
char **buf);
int mtd_sa_pb_get_fhl_period(const char *pid, char **buf);
int mtd_sa_pb_update_fhl_period(const struct mtd_dsrc_ctx *dsctx,
const char *pid, char **buf);
int mtd_sa_pb_get_fhl_annual_summary(const char *tax_year, char **buf);
int mtd_sa_pb_update_fhl_annual_summary(const struct mtd_dsrc_ctx *dsctx,
const char *tax_year,
char **buf);
int mtd_sa_di_get_annual_summary(const char *tax_year, char **buf);
int mtd_sa_di_update_annual_summary(const struct mtd_dsrc_ctx *dsctx,
const char *tax_year, char **buf);
int mtd_sa_sa_list_accounts(char **buf);
int mtd_sa_sa_create_account(const struct mtd_dsrc_ctx *dsctx, char **buf);
int mtd_sa_sa_get_account(const char *said, char **buf);
int mtd_sa_sa_get_annual_summary(const char *said, const char *tax_year,
char **buf);
int mtd_sa_sa_update_annual_summary(const struct mtd_dsrc_ctx *dsctx,
const char *said, const char *tax_year,
char **buf);
int mtd_sa_cg_get_charitable_giving(const char *tax_year, char **buf);
int mtd_sa_cg_update_charitable_giving(const struct mtd_dsrc_ctx *dsctx,
const char *tax_year, char **buf);
#include <libmtdac/mtd-ibeops.h>
int mtd_ibeops_submit_eops(const struct mtd_dsrc_ctx *dsctx, char **buf);
#include <libmtdac/mtd-saac.h>
int mtd_saac_get_balance(char **buf);
int mtd_saac_list_transactions(const char *query_string, char **buf);
int mtd_saac_get_transaction(const char *trid, char **buf);
int mtd_saac_list_charges(const char *query_string, char **buf);
int mtd_saac_get_charge(const char *trid, char **buf);
int mtd_saac_list_payments(const char *query_string, char **buf);
int mtd_saac_get_payment(const char *pyid, char **buf);
int mtd_saac_get_coding_out_uda(const char *tax_year, char **buf);
int mtd_saac_set_coding_out_uda(const struct mtd_dsrc_ctx *dsctx,
const char *tax_year, char **buf);
int mtd_saac_delete_coding_out_uda(const char *tax_year, char **buf);
#include <libmtdac/mtd-ic.h>
int mtd_ic_list_calculations(const char *query_string, char **buf);
int mtd_ic_trigger_calculation(const char *tax_year, const char *query_string,
char **buf);
int mtd_ic_get_calculation(const char *tax_year, const char *cid, char **buf);
int mtd_ic_final_decl(const char *tax_year, const char *cid, char **buf);
#include <libmtdac/mtd-il.h>
int mtd_il_bf_list_loses(const char *query_string, char **buf);
int mtd_il_bf_create_loss(const struct mtd_dsrc_ctx *dsctx, char **buf);
int mtd_il_bf_get_loss(const char *lid, char **buf);
int mtd_il_bf_delete_loss(const char *lid, char **buf);
int mtd_il_bf_update_loss_amnt(const struct mtd_dsrc_ctx *dsctx,
const char *lid, char **buf);
int mtd_il_lc_list_loses(const char *query_string, char **buf);
int mtd_il_lc_create_loss(const struct mtd_dsrc_ctx *dsctx, char **buf);
int mtd_il_lc_get_loss(const char *cid, char **buf);
int mtd_il_lc_delete_loss(const char *cid, char **buf);
int mtd_il_lc_update_loss_type(const struct mtd_dsrc_ctx *dsctx,
const char *cid, char **buf);
int mtd_il_lc_update_loss_order(const struct mtd_dsrc_ctx *dsctx,
const char *tax_year, char **buf);
#include <libmtdac/mtd-id.h>
int mtd_id_get(const char *tax_year, char **buf);
int mtd_id_set(const struct mtd_dsrc_ctx *dsctx, const char *tax_year,
char **buf);
int mtd_id_delete(const char *tax_year, char **buf);
int mtd_id_ma_create(const struct mtd_dsrc_ctx *dsctx, char **buf);
#include <libmtdac/mtd-biss.h>
int mtd_biss_get_summary(const char *business_type, const char *tax_year,
const char *bid, char **buf);
#include <libmtdac/mtd-bsas.h>
int mtd_bsas_list_summaries(const char *query_string, char **buf);
int mtd_bsas_trigger_summary(const struct mtd_dsrc_ctx *dsctx, char **buf);
int mtd_bsas_se_get_summary(const char *cid, char **buf);
int mtd_bsas_se_update_summary_adjustments(const struct mtd_dsrc_ctx *dsctx,
const char *cid, char **buf);
int mtd_bsas_pb_get_summary(const char *cid, char **buf);
int mtd_bsas_pb_update_summary_adjustments(const struct mtd_dsrc_ctx *dsctx,
const char *cid, char **buf);
int mtd_bsas_fp_get_summary(const char *cid, char **buf);
int mtd_bsas_fp_update_summary_adjustments(const struct mtd_dsrc_ctx *dsctx,
const char *cid, char **buf);
#include <libmtdac/mtd-ob.h>
int mtd_ob_list_inc_and_expend_obligations(const char *query_string,
char **buf);
int mtd_ob_list_crystallisation_obligations(const char *query_string,
char **buf);
int mtd_ob_list_end_of_period_obligations(const char *query_string,
char **buf);
#include <libmtdac/mtd-bd.h>
int mtd_bd_list(char **buf);
int mtd_bd_get(const char *bid, char **buf);
#include <libmtdac/mtd-vat.h>
int mtd_vat_list_obligations(const char *vrn, const char *query_string,
char **buf);
int mtd_vat_submit_period(const struct mtd_dsrc_ctx *dsctx, const char *vrn,
char **buf);
int mtd_vat_get_period(const char *vrn, const char *period_key, char **buf);
int mtd_vat_list_liabilities(const char *vrn, const char *query_string,
char **buf);
int mtd_vat_list_payments(const char *vrn, const char *query_string,
char **buf);
#include <libmtdac/mtd-test-cu.h>
int mtd_test_cu_create_individual(const struct mtd_dsrc_ctx *dsctx,
char **buf);
int mtd_test_cu_create_organisation(const struct mtd_dsrc_ctx *dsctx,
char **buf);
int mtd_test_cu_create_agent(const struct mtd_dsrc_ctx *dsctx, char **buf);
int mtd_test_cu_list_services(char **buf);
#include <libmtdac/mtd-test-fph.h>
int mtd_test_fph_validate(char **buf);
int mtd_test_fph_feedback(const char *api, const char *query_string,
char **buf);