tax

package
v0.37.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 1, 2023 License: Apache-2.0 Imports: 12 Imported by: 14

Documentation

Overview

Package tax encapsulates models related to taxation.

Index

Constants

This section is empty.

Variables

View Source 
var RequireIdentityCode = validateTaxID{/* contains filtered or unexported fields */}

RequireIdentityCode is an additional check to use alongside regular validation that will ensure the tax ID has a code value set.

View Source 
var SourceKeyDefinitions = []DefSourceKey{
	{
		Key:         SourceKeyTaxAgency,
		Description: "Sourced directly from a tax agency",
	},
	{
		Key:         SourceKeyPassport,
		Description: "A passport document",
	},
	{
		Key:         SourceKeyNational,
		Description: "National ID Card or similar",
	},
	{
		Key:         SourceKeyPermit,
		Description: "Residential or similar permit",
	},
	{
		Key:         SourceKeyOther,
		Description: "An other type of source not listed",
	},
}

SourceKeyDefinitions lists all the keys with their descriptions

Functions

func RegisterRegime added in v0.34.0 

func RegisterRegime(regime *Regime)

RegisterRegime adds a new regime to the shared global list of tax regimes.

Types

type Category 

type Category struct {
	Code cbc.Code    `json:"code" jsonschema:"title=Code"`
	Name i18n.String `json:"name" jsonschema:"title=Name"`
	Desc i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// Retained when true implies that the tax amount will be retained
	// by the buyer on behalf of the supplier, and thus subtracted from
	// the invoice taxable base total. Typically used for taxes related to
	// income.
	Retained bool `json:"retained,omitempty" jsonschema:"title=Retained"`

	// Specific tax definitions inside this category.
	Rates []*Rate `json:"rates" jsonschema:"title=Rates"`
}

Category contains the definition of a general type of tax inside a region.

func (*Category) Rate added in v0.20.0 

func (c *Category) Rate(key cbc.Key) *Rate

Rate provides the rate definition with a matching key for the category.

func (*Category) Validate 

func (c *Category) Validate() error

Validate ensures the Category's contents are correct.

type CategoryTotal 

type CategoryTotal struct {
	Code      cbc.Code     `json:"code" jsonschema:"title=Code"`
	Retained  bool         `json:"retained,omitempty" jsonschema:"title=Retained"`
	Rates     []*RateTotal `json:"rates" jsonschema:"title=Rates"`
	Base      num.Amount   `json:"base" jsonschema:"title=Base"`
	Amount    num.Amount   `json:"amount" jsonschema:"title=Amount"`
	Surcharge *num.Amount  `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
}

CategoryTotal groups together all rates inside a given category.

type Combo added in v0.21.0 

type Combo struct {
	// Tax category code from those available inside a region.
	Category cbc.Code `json:"cat" jsonschema:"title=Category"`
	// Rate within a category to apply.
	Rate cbc.Key `json:"rate,omitempty" jsonschema:"title=Rate"`
	// Percent defines the percentage set manually or determined from the rate key (calculated if rate present).
	Percent num.Percentage `json:"percent" jsonschema:"title=Percent" jsonschema_extras:"calculated=true"`
	// Some countries require an additional surcharge (calculated if rate present).
	Surcharge *num.Percentage `json:"surcharge,omitempty" jsonschema:"title=Surcharge" jsonschema_extras:"calculated=true"`
	// contains filtered or unexported fields
}

Combo represents the tax combination of a category code and rate key. The percent and retained attributes will be determined automatically from the Rate key if set during calculation.

func (*Combo) Validate added in v0.21.0 

func (c *Combo) Validate() error

Validate ensures the Combo has the correct details.

type DefSourceKey added in v0.34.0 

type DefSourceKey struct {
	Key         SourceKey `json:"key" jsonschema:"title=Key"`
	Description string    `json:"description" jsonschema:"title=Description"`
}

DefSourceKey defines the details we have regarding a document source key.

type Error added in v0.22.1 

type Error cbc.Key

Error is a general wrapper around tax errors produced during run time, typically during calculations. Not to be confused with errors produced from definition validation. 

const (
	ErrMissingRegion        Error = "missing-region"
	ErrInvalidCategory      Error = "invalid-category"
	ErrInvalidRate          Error = "invalid-rate"
	ErrInvalidDate          Error = "invalid-date"
	ErrInvalidPricesInclude Error = "invalid-prices-include"
)

Standard list of tax errors

func (Error) Error added in v0.22.1 

func (e Error) Error() string

Error serializes the error's message.

func (Error) WithMessage added in v0.22.1 

func (e Error) WithMessage(msg string, s ...interface{}) error

WithMessage wraps around the original error so we can use if for matching and adds a human message.

type Identity added in v0.34.0 

type Identity struct {
	// Unique universal identity code for this tax identity.
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`

	// ISO country code for Where the tax identity was issued.
	Country l10n.CountryCode `json:"country" jsonschema:"title=Country Code"`

	// Where inside the country the tax identity holder is based for tax purposes
	// like a village, town, district, city, county, state or province. For some
	// areas, this could be a regular post or zip code. See the regime packages
	// for specific validation rules.
	Zone l10n.Code `json:"zone,omitempty" jsonschema:"title=Zone Code"`

	// What is the source document of the tax identity.
	Source SourceKey `json:"source,omitempty" jsonschema:"title=Source Key"`

	// Normalized code shown on the original identity document.
	Code cbc.Code `json:"code,omitempty" jsonschema:"title=Code"`

	// Additional details that may be required.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Identity stores the details required to identify an entity for tax purposes. There are two levels of accuracy that may be used to describe where an entity is located: Country and Locality. Country is a required field, but locality is optional according to rules of a given tax jurisdiction.

func (*Identity) Calculate added in v0.34.0 

func (id *Identity) Calculate() error

Calculate will attempt to perform a regional tax normalization on the tax identity.

func (*Identity) Regime added in v0.34.0 

func (id *Identity) Regime() *Regime

Regime provides the regime object for this tax identity.

func (*Identity) String added in v0.35.1 

func (id *Identity) String() string

String provides a string representation of the tax identity.

func (*Identity) Validate added in v0.34.0 

func (id *Identity) Validate() error

Validate checks to ensure the tax ID contains all the required fields and performs any regime specific validation based on the ID's country and zone properties.

type Rate 

type Rate struct {
	// Key identifies this rate within the system
	Key cbc.Key `json:"key" jsonschema:"title=Key"`

	Name i18n.String `json:"name" jsonschema:"title=Name"`
	Desc i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// Values contains a list of Value objects that contain the
	// current and historical percentage values for the rate and
	// additional filters.
	// Order is important, newer values should come before
	// older values.
	Values []*RateValue `json:"values" jsonschema:"title=Values"`
}

Rate defines a single rate inside a category

func (*Rate) Validate 

func (r *Rate) Validate() error

Validate checks that our tax definition is valid. This is only really meant to be used when testing new regional tax definitions.

func (*Rate) Value added in v0.35.0 

func (r *Rate) Value(date cal.Date, zone l10n.Code) *RateValue

Value determines the tax rate value for the provided date and zone, if applicable.

type RateTotal 

type RateTotal struct {
	Key     cbc.Key        `json:"key,omitempty" jsonschema:"title=Key"`
	Base    num.Amount     `json:"base" jsonschema:"title=Base"`
	Percent num.Percentage `json:"percent" jsonschema:"title=Percent"`
	// Total amount of rate, excluding surcharges
	Amount    num.Amount          `json:"amount" jsonschema:"title=Amount"`
	Surcharge *RateTotalSurcharge `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
}

RateTotal contains a sum of all the tax rates in the document with a matching category and rate. The Key is optional as we may be using the percentage to group rates.

type RateTotalSurcharge added in v0.25.0 

type RateTotalSurcharge struct {
	Percent num.Percentage `json:"percent" jsonschema:"title=Percent"`
	Amount  num.Amount     `json:"amount" jsonschema:"title=Amount"`
}

RateTotalSurcharge reflects the sum surcharges inside the rate.

type RateValue added in v0.20.0 

type RateValue struct {
	// Only use this value if one of the zones matches.
	Zones []l10n.Code `json:"zones,omitempty" jsonschema:"title=Zones"`
	// Date from which this value should be applied.
	Since *cal.Date `json:"since,omitempty" jsonschema:"title=Since"`
	// Percent rate that should be applied
	Percent num.Percentage `json:"percent" jsonschema:"title=Percent"`
	// An additional surcharge to apply.
	Surcharge *num.Percentage `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
	// When true, this value should no longer be used.
	Disabled bool `json:"disabled,omitempty" jsonschema:"title=Disabled"`
}

RateValue contains a percentage rate or fixed amount for a given date range. Fiscal policy changes mean that rates are not static so we need to be able to apply the correct rate for a given period.

func (*RateValue) HasZone added in v0.35.0 

func (rv *RateValue) HasZone(zone l10n.Code) bool

HasZone returns true if the rate value has a zone that matches the one provided.

func (*RateValue) Validate added in v0.20.0 

func (rv *RateValue) Validate() error

Validate ensures the tax rate contains all the required fields.

type Regime added in v0.34.0 

type Regime struct {
	// Name of the country
	Name i18n.String `json:"name" jsonschema:"title=Name"`

	// Country code for the region
	Country l10n.CountryCode `json:"country" jsonschema:"title=Code"`

	// Specific Locality, region, city, province, county, or similar code inside
	// the country, if needed.
	Zone l10n.Code `json:"zone,omitempty" jsonschema:"title=Zone"`

	// List of sub-zones inside a country.
	Zones []Zone `json:"zones,omitempty" jsonschema:"title=Zones"`

	// Currency used by the country.
	Currency currency.Code `json:"currency" jsonschema:"title=Currency"`

	// Set of specific scheme definitions inside the region.
	Schemes []*Scheme `json:"schemes,omitempty" jsonschema:"title=Schemes"`

	// List of tax categories.
	Categories []*Category `json:"categories" jsonschema:"title=Categories"`

	// Validator is a method to use to validate a document in a given region.
	Validator func(doc interface{}) error `json:"-"`

	// Calculator is used to performs regime specific calculations on data,
	// including any normalization that might need to take place such as
	// with tax codes and removing white-space.
	Calculator func(doc interface{}) error `json:"-"`
}

Regime defines the holding structure for the definitions of taxes inside a country or territory.

func AllRegimes added in v0.34.0 

func AllRegimes() []*Regime

AllRegimes provides an array of all the regime codes to definitions.

func RegimeFor added in v0.34.0 

func RegimeFor(country l10n.CountryCode, locality l10n.Code) *Regime

RegimeFor returns the regime definition for country and locality combination or nil if no match was found.

func (*Regime) CalculateObject added in v0.37.0 

func (r *Regime) CalculateObject(obj interface{}) error

CalculateObject performs any regime specific calculations on the provided object.

func (*Regime) Category added in v0.34.0 

func (r *Regime) Category(code cbc.Code) *Category

Category provides the requested category by its code.

func (*Regime) CurrencyDef added in v0.34.0 

func (r *Regime) CurrencyDef() *currency.Def

CurrencyDef provides the currency definition object for the region.

func (*Regime) SchemeFor added in v0.36.0 

func (r *Regime) SchemeFor(key cbc.Key) *Scheme

SchemeFor returns the scheme definition for the given key.

func (*Regime) Validate added in v0.34.0 

func (r *Regime) Validate() error

Validate enures the region definition is valid, including all subsequent categories.

func (*Regime) ValidateObject added in v0.37.0 

func (r *Regime) ValidateObject(obj interface{}) error

ValidateObject performs validation on the provided object in the context of the regime.

type RegimeCollection added in v0.34.0 

type RegimeCollection struct {
	// contains filtered or unexported fields
}

RegimeCollection defines how to access details about all the regimes currently stored.

func Regimes added in v0.34.0 

func Regimes() *RegimeCollection

Regimes provides the current global regime collection object.

func (*RegimeCollection) All added in v0.34.0 

func (c *RegimeCollection) All() []*Regime

All provides a list of all the registered Regimes.

func (*RegimeCollection) For added in v0.34.0 

func (c *RegimeCollection) For(country l10n.CountryCode, zone l10n.Code) *Regime

For provides a single matching regime from the collection, or nil if no match is found.

type Scheme added in v0.20.0 

type Scheme struct {
	// Key used to identify this scheme
	Key cbc.Key `json:"key" jsonschema:"title=Key"`

	// Name of this scheme.
	Name i18n.String `json:"name" jsonschema:"title=Name"`
	// Human details describing what this scheme is used for.
	Description i18n.String `json:"description,omitempty" jsonschema:"title=Description"`

	// List of tax category codes that can be used when this scheme is
	// applied.
	Categories []cbc.Code `json:"categories,omitempty" jsonschema:"title=Category Codes"`

	// Note defines a message that should be added to a document
	// when this scheme is used.
	Note *cbc.Note `json:"note,omitempty" jsonschema:"title=Note"`
}

Scheme contains the definition of a scheme that belongs to a region and can be used to simplify validation processes for document contents.

func (*Scheme) Validate added in v0.36.0 

func (s *Scheme) Validate() error

Validate ensures the tax details look valid.

type Set added in v0.21.0 

type Set []*Combo

Set defines a list of tax categories and their rates to be used alongside taxable items.

func (Set) Equals added in v0.21.0 

func (s Set) Equals(s2 Set) bool

Equals returns true if the sets match, regardless of order.

func (Set) Get added in v0.21.0 

func (s Set) Get(cat cbc.Code) *Combo

Get the Rate key for the given category

func (Set) Rate added in v0.21.0 

func (s Set) Rate(cat cbc.Code) cbc.Key

Rate returns the rate from the matching category, if set.

func (Set) Validate added in v0.21.0 

func (s Set) Validate() error

Validate ensures the set of tax combos looks correct

type SourceKey added in v0.34.0 

type SourceKey cbc.Key

SourceKey is used to identify different sources of tax identities that may be required by some regions. 

const (
	// Directly from tax Agency
	SourceKeyTaxAgency SourceKey = "tax-agency"
	// A passport document
	SourceKeyPassport SourceKey = "passport"
	// National ID Card or similar
	SourceKeyNational SourceKey = "national"
	// Residential permit
	SourceKeyPermit SourceKey = "permit"
	// Something else
	SourceKeyOther SourceKey = "other"
)

Main Source Key definitions.

func (SourceKey) JSONSchema added in v0.34.0 

func (k SourceKey) JSONSchema() *jsonschema.Schema

JSONSchema provides a representation of the struct for usage in Schema.

type TaxableLine 

type TaxableLine interface {
	GetTaxes() Set
	GetTotal() num.Amount
}

TaxableLine defines what we expect from a line in order to subsequently calculate the taxes that need to be added or retained.

type Total 

type Total struct {
	// Grouping of all the taxes by their category
	Categories []*CategoryTotal `json:"categories,omitempty" jsonschema:"title=Categories"`
	// Total value of all the taxes applied.
	Sum num.Amount `json:"sum" jsonschema:"title=Sum"`
}

Total contains a set of Category Totals which in turn contain all the accumulated taxes contained in the document. The resulting `sum` is that value that should be added to the payable total.

func (*Total) Category added in v0.13.0 

func (t *Total) Category(code cbc.Code) *CategoryTotal

Category provides the category total for the matching code.

type TotalCalculator added in v0.35.0 

type TotalCalculator struct {
	// Data used for making calculations that is not persisted
	Regime   *Regime
	Zone     l10n.Code
	Zero     num.Amount
	Includes cbc.Code
	Date     cal.Date
	Lines    []TaxableLine
}

TotalCalculator is used to calculate a tax totals object using the configured parameters.

func (*TotalCalculator) Calculate added in v0.35.0 

func (tc *TotalCalculator) Calculate(t *Total) error

Calculate figures out the total taxes for the set of `TaxableLine`s provided.

type Zone added in v0.34.0 

type Zone struct {
	// Unique zone code.
	Code l10n.Code `json:"code" jsonschema:"title=Code"`
	// Name of the zone to be use if a locality or region is not applicable.
	Name i18n.String `json:"name,omitempty" jsonschema:"title=Name"`
	// Village, town, district, or city name which should coincide with
	// address data.
	Locality i18n.String `json:"locality,omitempty" jsonschema:"title=Locality"`
	// Province, county, or state which should match address data.
	Region i18n.String `json:"region,omitempty" jsonschema:"title=Region"`
	// Any additional information
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Zone represents an area inside a country, like a province or a state, which shares the basic definitions of the country, but may vary in some validation rules.

func (*Zone) Validate added in v0.34.0 

func (z *Zone) Validate() error

Validate ensures that the zone looks correct.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.