hmrc.api package

Submodules

hmrc.api.client module

HMRC client

class hmrc.api.client.HmrcNoData

Bases: hmrc.api.data.HmrcDataClass

Empty HMRC data class

class hmrc.api.client.HmrcErrorDetail(code: str, message: str, path: str = None, reactivation_timestamp: int = None)

Bases: hmrc.api.data.HmrcDataClass

Error description

path = None

reactivation_timestamp = None

class hmrc.api.client.HmrcErrorResponse(code: str, message: str, path: str = None, reactivation_timestamp: int = None, errors: List[hmrc.api.client.HmrcErrorDetail] = None)

Bases: hmrc.api.client.HmrcErrorDetail

Error response

An error response comprises a top-level error description plus an optional list of contributory error descriptions.

errors = None

exception hmrc.api.client.HmrcClientError

Bases: OSError

HMRC API exception

This is used only when the server returns a recognisable HMRC error response representation.

error

The HMRC error response

class hmrc.api.client.HmrcClient(session: hmrc.auth.session.HmrcSession)

Bases: object

HMRC API client

REQUEST_CONTENT_TYPE = 'application/json'

RESPONSE_CONTENT_TYPE = 'application/vnd.hmrc.1.0+json'

request(uri, *, method='GET', query=None, body=None, scenario=None)

Send request

scope = []

Authorisation scopes

session = None

Requests session

class hmrc.api.client.HmrcEndpoint(uri: str, method: str = None, path: type = <class 'hmrc.api.client.HmrcNoData'>, query: type = <class 'hmrc.api.client.HmrcNoData'>, request: type = <class 'hmrc.api.client.HmrcNoData'>, response: type = <class 'hmrc.api.client.HmrcNoData'>)

Bases: object

A callable API endpoint

method = None

HTTP method

path

URI path parameter type

alias of HmrcNoData

query

URI query parameter type

alias of HmrcNoData

request

Request body type

alias of HmrcNoData

response

Response body type

alias of HmrcNoData

uri = None

Endpoint URI

hmrc.api.data module

HMRC API data representation

Data structures used within API messages are represented in Python using dataclasses, with the mapping between the Python representation and the HMRC API wire protocol representation handled automatically via introspection of the Python type annotations.

>>> from decimal import Decimal
>>> @hmrcdataclass
... class TaxPeriodSummary(HmrcDataClass):
...     tax_id: str
...     start: date
...     end: date
...     total_income: Decimal
...     tax_due: Decimal

>>> t1 = TaxPeriodSummary.from_json('''
...     {
...         "taxId": "82719NH23A",
...         "start": "2018-04-06",
...         "end": "2019-04-05",
...         "totalIncome": 38600.00,
...         "taxDue": 2412.50
...     }
... ''')

>>> t1.tax_id
'82719NH23A'

>>> t1.start.year
2018

>>> t1.total_income
Decimal('38600.00')

>>> t1.to_hmrc() # doctest: +NORMALIZE_WHITESPACE
{'taxId': '82719NH23A', 'start': '2018-04-06', 'end': '2019-04-05',
 'totalIncome': Decimal('38600.00'), 'taxDue': Decimal('2412.50')}

>>> t1.tax_due -= Decimal('100.00')

>>> t1.to_hmrc() # doctest: +NORMALIZE_WHITESPACE
{'taxId': '82719NH23A', 'start': '2018-04-06', 'end': '2019-04-05',
 'totalIncome': Decimal('38600.00'), 'taxDue': Decimal('2312.50')}

>>> t2 = TaxPeriodSummary(
...    tax_id = '543242WD69B',
...    start = date(2015, 6, 24),
...    end = date(2016, 6, 23),
...    total_income = Decimal('14000.00'),
...    tax_due = Decimal('0.00'),
... )

>>> t2.to_hmrc() # doctest: +NORMALIZE_WHITESPACE
{'taxId': '543242WD69B', 'start': '2015-06-24', 'end': '2016-06-23',
 'totalIncome': Decimal('14000.00'), 'taxDue': Decimal('0.00')}

>>> t2.to_json() # doctest: +NORMALIZE_WHITESPACE
'{"taxId": "543242WD69B", "start": "2015-06-24", "end": "2016-06-23",
  "totalIncome": 14000.00, "taxDue": 0.00}'

exception hmrc.api.data.HmrcUnknownFieldError

Bases: KeyError

Unexpected HMRC API field

class hmrc.api.data.HmrcFieldMap(name: str, from_hmrc: Callable, to_hmrc: Callable, hmrc_name: str = None)

Bases: object

A mapping between a Python dataclass field and an HMRC API field

default_hmrc_name()

Construct default HMRC API field name from Python field name

The Python field name is converted from snake_case to camelCase.

from_hmrc = None

Construct Python value from HMRC API value

hmrc_name = None

HMRC field name

name = None

Python field name

to_hmrc = None

Convert Python value to HMRC API value

class hmrc.api.data.HmrcTypeMap

Bases: object

Mapper between Python field values and HMRC API field values

classmethod from_hmrc(pytype)

Construct Python value from HMRC API value

classmethod to_hmrc(pytype)

Convert Python value to HMRC API value

class hmrc.api.data.HmrcDataClass

Bases: object

HMRC data class

FieldMap

Field mapping class

alias of HmrcFieldMap

TypeMap

Type mapping class

alias of HmrcTypeMap

classmethod build_hmrc_mappings()

Construct mappings between Python fields and HMRC API fields

classmethod from_hmrc(hmrc)

Construct Python object from HMRC API representation

classmethod from_json(json, *, loads=<function loads>)

Construct Python object from JSON representation

to_hmrc()

Convert Python object to HMRC API representation

to_json(*, dumps=<function dumps>)

Convert Python object to JSON representation

hmrc.api.data.hmrcdataclass(cls)

HMRC data class decorator

hmrc.api.hello module

Hello World API

class hmrc.api.hello.HelloMessage(message: str)

Bases: hmrc.api.data.HmrcDataClass

Hello World message

class hmrc.api.hello.HelloClient(session: hmrc.auth.session.HmrcSession)

Bases: hmrc.api.client.HmrcClient

Hello World API client

application

A callable API endpoint

scope = ['hello']

user

A callable API endpoint

world

A callable API endpoint

hmrc.api.testuser module

Create Test User API

class hmrc.api.testuser.TestUserService

Bases: enum.Enum

Service names for enrollment

CORPORATION_TAX = 'corporation-tax'

CUSTOMS_SERVICES = 'customs-services'

LISA = 'lisa'

MTD_INCOME_TAX = 'mtd-income-tax'

MTD_VAT = 'mtd-vat'

NATIONAL_INSURANCE = 'national-insurance'

PAYE_FOR_EMPLOYERS = 'paye-for-employers'

RELIEF_AT_SOURCE = 'relief-at-source'

SECURE_ELECTRONIC_TRANSFER = 'secure-electronic-transfer'

SELF_ASSESSMENT = 'self-assessment'

SUBMIT_VAT_RETURNS = 'submit-vat-returns'

class hmrc.api.testuser.TestUserServices(service_names: List[hmrc.api.testuser.TestUserService])

Bases: hmrc.api.data.HmrcDataClass

Services for which the test user should be enrolled

class hmrc.api.testuser.TestUserAddress(line1: str, line2: str, postcode: str)

Bases: hmrc.api.data.HmrcDataClass

Test user address

class hmrc.api.testuser.TestUserIndividualDetails(first_name: str, last_name: str, date_of_birth: datetime.date, address: hmrc.api.testuser.TestUserAddress)

Bases: hmrc.api.data.HmrcDataClass

Individual test user details

class hmrc.api.testuser.TestUserOrganisationDetails(name: str, address: hmrc.api.testuser.TestUserAddress)

Bases: hmrc.api.data.HmrcDataClass

Organisation test user details

class hmrc.api.testuser.TestUser(user_id: str, password: str, user_full_name: str, email_address: str, individual_details: hmrc.api.testuser.TestUserIndividualDetails = None, organisation_details: hmrc.api.testuser.TestUserOrganisationDetails = None, sa_utr: str = None, nino: str = None, mtd_it_id: str = None, emp_ref: str = None, ct_utr: str = None, vrn: str = None, vat_registration_date: datetime.date = None, lisa_manager_reference_number: str = None, secure_electronic_transfer_reference_number: str = None, pension_scheme_administrator_identifier: str = None, eori_number: str = None, group_identifier: str = None)

Bases: hmrc.api.data.HmrcDataClass

Organisation test user

ct_utr = None

emp_ref = None

eori_number = None

group_identifier = None

individual_details = None

lisa_manager_reference_number = None

mtd_it_id = None

nino = None

organisation_details = None

pension_scheme_administrator_identifier = None

sa_utr = None

secure_electronic_transfer_reference_number = None

vat_registration_date = None

vrn = None

class hmrc.api.testuser.TestUserClient(session: hmrc.auth.session.HmrcSession)

Bases: hmrc.api.client.HmrcClient

Create Test User API client

create_individual

A callable API endpoint

create_organisation

A callable API endpoint

hmrc.api.vat module

VAT API

class hmrc.api.vat.VatObligationStatus

Bases: enum.Enum

Obligation status

FULFILLED = 'F'

OPEN = 'O'

class hmrc.api.vat.VatPaymentIndicator

Bases: enum.Enum

Payment method

DIRECT_CREDIT = 'BANK'

DIRECT_DEBIT = 'DD'

class hmrc.api.vat.VatVrnParams(vrn: str)

Bases: hmrc.api.vat.VatDataClass

Parameter list: VAT registration number only

class hmrc.api.vat.VatVrnPeriodParams(vrn: str, period_key: str)

Bases: hmrc.api.vat.VatVrnParams

Parameter list: VAT registration number and period key

class hmrc.api.vat.VatObligationsParams(from_: datetime.date = None, to: datetime.date = None, status: hmrc.api.vat.VatObligationStatus = None)

Bases: hmrc.api.vat.VatDataClass

Parameter list: VAT obligations search criteria

from_ = None

status = None

to = None

class hmrc.api.vat.VatObligation(start: datetime.date, end: datetime.date, due: datetime.date, status: hmrc.api.vat.VatObligationStatus, period_key: str, received: datetime.date = None)

Bases: hmrc.api.vat.VatDataClass

VAT obligation

received = None

class hmrc.api.vat.VatObligations(obligations: List[hmrc.api.vat.VatObligation])

Bases: hmrc.api.vat.VatDataClass

List of VAT obligations

class hmrc.api.vat.VatReturn(period_key: str, vat_due_sales: decimal.Decimal, vat_due_acquisitions: decimal.Decimal, total_vat_due: decimal.Decimal, vat_reclaimed_curr_period: decimal.Decimal, net_vat_due: decimal.Decimal, total_value_sales_ex_vat: int, total_value_purchases_ex_vat: int, total_value_goods_supplied_ex_vat: int, total_acquisitions_ex_vat: int)

Bases: hmrc.api.vat.VatDataClass

VAT return

class hmrc.api.vat.VatSubmission(period_key: str, vat_due_sales: decimal.Decimal, vat_due_acquisitions: decimal.Decimal, total_vat_due: decimal.Decimal, vat_reclaimed_curr_period: decimal.Decimal, net_vat_due: decimal.Decimal, total_value_sales_ex_vat: int, total_value_purchases_ex_vat: int, total_value_goods_supplied_ex_vat: int, total_acquisitions_ex_vat: int, finalised: bool)

Bases: hmrc.api.vat.VatReturn

VAT return submission

class hmrc.api.vat.VatConfirmation(processing_date: datetime.datetime, payment_indicator: hmrc.api.vat.VatPaymentIndicator = None, form_bundle_number: str = None, charge_ref_number: str = None)

Bases: hmrc.api.vat.VatDataClass

VAT return submission confirmation

charge_ref_number = None

form_bundle_number = None

payment_indicator = None

class hmrc.api.vat.VatReadOnlyClient(session: hmrc.auth.session.HmrcSession, vrn: str = None)

Bases: hmrc.api.client.HmrcClient

VAT API client with read-only access

obligations

A callable API endpoint

retrieve

A callable API endpoint

scope = ['read:vat']

vrn = None

class hmrc.api.vat.VatClient(session: hmrc.auth.session.HmrcSession, vrn: str = None)

Bases: hmrc.api.vat.VatReadOnlyClient

VAT API client

scope = ['read:vat', 'write:vat']

submit

A callable API endpoint

Module contents

HMRC API