tax

package
v0.52.3 Latest Latest
Warning

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

 Go to latest Published: Jul 27, 2023 License: Apache-2.0 Imports: 14 Imported by: 11

Documentation

Overview

Package tax encapsulates models related to taxation.

Index

Constants

View Source 
const (
	// KeyRegime is used in the context to store the tax regime during validation.
	KeyRegime cbc.Key = "tax-regime"
)

Variables

View Source 
var (
	ErrIdentityCodeInvalid = errors.New("invalid tax identity code")
)

Standard error responses to be used by regimes.

View Source 
var IdentityTypeIn = func(keys ...cbc.Key) validation.Rule {
	out := make([]interface{}, len(keys))
	for i, l := range keys {
		out[i] = l
	}
	return validateTaxID{typeIn: out}
}

IdentityTypeIn checks that the identity code is within one of the acceptable keys.

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 RequireIdentityType = validateTaxID{/* contains filtered or unexported fields */}

RequireIdentityType ensures that the identity type is set.

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.

func ValidateInRegime added in v0.50.0 

func ValidateInRegime(ctx context.Context, obj interface{}) error

ValidateInRegime ensures that the object is valid in the context of the regime.

func ValidateStructWithRegime added in v0.51.2 

func ValidateStructWithRegime(ctx context.Context, obj interface{}, fields ...*validation.FieldRules) error

ValidateStructWithRegime wraps around the standard validation.ValidateStructWithContext method to add an additional check for the tax regime.

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"`

	// RateRequired when true implies that when a tax combo is defined using
	// this category that one of the rates must be defined.
	RateRequired bool `json:"rate_required,omitempty" jsonschema:"title=Rate Required"`

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

	// Codes defines a set of regime specific code mappings.
	Codes cbc.CodeSet `json:"codes,omitempty" jsonschema:"title=Codes"`

	// Meta contains additional information about the category that is relevant
	// for local frequently used formats.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

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"`
	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,omitempty" 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) UnmarshalJSON added in v0.50.0 

func (c *Combo) UnmarshalJSON(data []byte) error

UnmarshalJSON is a temporary migration helper that will move the first of the "tags" array used in earlier versions of GOBL into the rate field.

func (*Combo) ValidateWithContext added in v0.38.0 

func (c *Combo) ValidateWithContext(ctx context.Context) error

ValidateWithContext ensures the Combo has the correct details.

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"
	ErrInvalidTag           Error = "invalid-tag"
	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"`

	// Type is set according the requirements of each regime, some have a single
	// tax document type code, others require a choice to be made.
	Type cbc.Key `json:"type,omitempty" jsonschema:"title=Type"`

	// 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 KeyDefinition added in v0.38.0 

type KeyDefinition struct {
	// Actual key value.
	Key cbc.Key `json:"key" jsonschema:"title=Key"`
	// Short name for the key, if relevant.
	Name i18n.String `json:"name,omitempty" jsonschema:"title=Name"`
	// Description offering more details about when the key should be used.
	Desc i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`
	// Codes defines a set of codes that may be used within a given regime or format
	// that will help identify which key definition to use.
	Codes cbc.CodeSet `json:"codes,omitempty" jsonschema:"title=Codes"`
	// Any additional data that might be relevant in some regimes.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

KeyDefinition defines properties of a key that is specific for a regime.

func (*KeyDefinition) Validate added in v0.50.0 

func (kd *KeyDefinition) Validate() error

Validate ensures the key definition looks correct in the context of the regime.

type PrecedingDefinitions added in v0.38.0 

type PrecedingDefinitions struct {
	// The types of sub-documents supported by the regime
	Types []cbc.Key `json:"types,omitempty" jsonschema:"title=Types"`
	// Stamps that must be copied from the preceding document.
	Stamps []cbc.Key `json:"stamps,omitempty" jsonschema:"title=Stamps"`
	// Corrections contains a list of all the keys that can be used to identify a correction.
	Corrections []*KeyDefinition `json:"corrections,omitempty" jsonschema:"title=Corrections"`
	// CorrectionMethods describe the methods used to correct an invoice.
	CorrectionMethods []*KeyDefinition `json:"correction_methods,omitempty" jsonschema:"title=Correction Methods"`
}

PrecedingDefinitions contains details about what can be defined in Invoice preceding document data.

func (*PrecedingDefinitions) HasType added in v0.40.0 

func (pd *PrecedingDefinitions) HasType(t cbc.Key) bool

HasType returns true if the preceding definitions has a type that matches the one provided.

type Rate 

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

	// Human name of the rate
	Name i18n.String `json:"name" jsonschema:"title=Name"`
	// Useful description of the rate.
	Desc i18n.String `json:"desc,omitempty" jsonschema:"title=Description"`

	// Exempt when true implies that the rate when used in a tax Combo should
	// not define a percent value.
	Exempt bool `json:"exempt,omitempty" jsonschema:"title=Exempt"`

	// 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,omitempty" jsonschema:"title=Values"`

	// Codes defines a set of regime specific code mappings.
	Codes cbc.CodeSet `json:"codes,omitempty" jsonschema:"title=Codes"`

	// Meta contains additional information about the rate that is relevant
	// for local frequently used implementations.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

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 {
	// Optional rate key is required when grouping.
	Key cbc.Key `json:"key,omitempty" jsonschema:"title=Key"`
	// Base amount that the percentage is applied to.
	Base num.Amount `json:"base" jsonschema:"title=Base"`
	// Percentage of the rate, which may be nil for exempt rates.
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
	// Surcharge applied to the rate.
	Surcharge *RateTotalSurcharge `json:"surcharge,omitempty" jsonschema:"title=Surcharge"`
	// Total amount of rate, excluding surcharges
	Amount num.Amount `json:"amount" jsonschema:"title=Amount"`
}

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"`

	// Tags that can be applied at the document level to identify additional
	// considerations.
	Tags []*KeyDefinition `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Identity types specific for the regime and may be validated
	// against.
	IdentityTypeKeys []*KeyDefinition `json:"identity_types,omitempty" jsonschema:"title=Identity Types"`

	// Charge types specific for the regime and may be validated or used in the UI as suggestions
	ChargeKeys []*KeyDefinition `json:"charge_types,omitempty" jsonschema:"title=Charge Types"`

	// PaymentMeansKeys specific for the regime that extend the original
	// base payment means keys.
	PaymentMeansKeys []*KeyDefinition `json:"payment_means,omitempty" jsonschema:"title=Payment Means"`

	// ItemKeys specific for the regime that need to be added to `org.Item` data
	// in line rows.
	ItemKeys []*KeyDefinition `json:"item_keys,omitempty" jsonschema:"title=Item Keys"`

	// Sets of scenario definitions for the regime.
	Scenarios []*ScenarioSet `json:"scenarios,omitempty" jsonschema:"title=Scenarios"`

	// Configuration details for preceding options.
	Preceding *PrecedingDefinitions `json:"preceding,omitempty" jsonschema:"title=Preceding"`

	// 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 RegimeFromContext added in v0.38.0 

func RegimeFromContext(ctx context.Context) *Regime

RegimeFromContext returns the regime from the given context, or nil.

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) InCategories added in v0.38.0 

func (r *Regime) InCategories() validation.Rule

InCategories returns a validation rule to ensure the category code is inside the list of known codes.

func (*Regime) InCategoryRates added in v0.50.0 

func (r *Regime) InCategoryRates(cat cbc.Code) validation.Rule

InCategoryRates is used to provide a validation rule that will ensure a rate key is defined inside a category.

func (*Regime) InTags added in v0.38.0 

func (r *Regime) InTags() validation.Rule

InTags returns a validation rule to ensure the tag key is inside the list of known tags.

func (*Regime) Rate added in v0.50.0 

func (r *Regime) Rate(cat cbc.Code, key cbc.Key) *Rate

Rate provides the rate definition for the provided category code and rate key.

func (*Regime) ScenarioSet added in v0.38.0 

func (r *Regime) ScenarioSet(schema string) *ScenarioSet

ScenarioSet returns a single scenario set instance for the provided document schema.

func (*Regime) Tag added in v0.38.0 

func (r *Regime) Tag(key cbc.Key) *KeyDefinition

Tag returns the KeyDefinition for the provided tag 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.

func (*Regime) WithContext added in v0.38.0 

func (r *Regime) WithContext(ctx context.Context) context.Context

WithContext adds this regime to the given context.

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 Scenario added in v0.38.0 

type Scenario struct {
	// Type of document, if present.
	Types []cbc.Key `json:"type,omitempty" jsonschema:"title=Type"`

	// Tag that was applied to the document
	Tags []cbc.Key `json:"tags,omitempty" jsonschema:"title=Tag"`

	// Name of the scenario for further information.
	Name i18n.String `json:"name,omitempty" jsonschema:"title=Name"`

	// A note to be added to the document if the scenario is applied.
	Note *cbc.Note `json:"note,omitempty" jsonschema:"title=Note"`

	// Codes is used to define additional codes for regime specific
	// situations.
	Codes cbc.CodeSet `json:"codes,omitempty" jsonschema:"title=Codes"`

	// Any additional local meta data that may be useful in integrations.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Scenario is used to describe a tax scenario of a document based on the combination of document type and tag used.

func (*Scenario) Validate added in v0.38.0 

func (s *Scenario) Validate() error

Validate checks the scenario for errors.

type ScenarioSet added in v0.38.0 

type ScenarioSet struct {
	// Partial or complete schema URL for the document type
	Schema string `json:"schema" jsonschema:"title=Schema"`
	// List of scenarios for the schema
	List []*Scenario `json:"list" jsonschema:"title=List"`
}

ScenarioSet is a collection of tax scenarios for a given schema that can be used to determine special codes or notes that need to be included in the final document.

func (*ScenarioSet) SummaryFor added in v0.38.0 

func (ss *ScenarioSet) SummaryFor(docType cbc.Key, docTags []cbc.Key) *ScenarioSummary

SummaryFor returns a summary by applying the scenarios to the supplied document.

func (*ScenarioSet) Validate added in v0.38.0 

func (ss *ScenarioSet) Validate() error

Validate checks the scenario set for errors.

type ScenarioSummary added in v0.38.0 

type ScenarioSummary struct {
	Notes []*cbc.Note
	Codes cbc.CodeSet
	Meta  cbc.Meta
}

ScenarioSummary is the result after running through a set of scenarios and determining which combinations of Notes and Meta are viable.

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) ValidateWithContext added in v0.38.0 

func (s Set) ValidateWithContext(ctx context.Context) error

ValidateWithContext ensures the set of tax combos looks correct

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"`
	// Codes defines a set of regime specific code mappings.
	Codes cbc.CodeSet `json:"codes,omitempty" jsonschema:"title=Codes"`
	// 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.