bill

package
v0.38.1 Latest Latest
Warning

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

Go to latest
Published: Mar 16, 2023 License: Apache-2.0 Imports: 16 Imported by: 24

Documentation

Overview

Package bill provides models for dealing with Billing and specifically invoicing.

Index

Constants

View Source
const (
	InvoiceTypeStandard   cbc.Key = "standard"
	InvoiceTypeProforma   cbc.Key = "proforma"
	InvoiceTypeCorrective cbc.Key = "corrective"
	InvoiceTypeCreditNote cbc.Key = "credit-note"
	InvoiceTypeDebitNote  cbc.Key = "debit-note"
)

Predefined list of the invoice type codes officially supported.

View Source
const (
	ShortSchemaInvoice = "bill/invoice"
)

Constants used to help identify invoices

Variables

View Source
var InvoiceTypes = invoiceTypeDefs{
	{InvoiceTypeStandard, "A regular commercial invoice document between a supplier and customer.", "380"},
	{InvoiceTypeProforma, "For a clients validation before sending a final invoice.", "325"},
	{InvoiceTypeCorrective, "Corrected invoice that completely replaces the preceding document.", "384"},
	{InvoiceTypeCreditNote, "Reflects a refund either partial or complete of the preceding document.", "381"},
	{InvoiceTypeDebitNote, "An additional set of charges to be added to the preceding document.", "383"},
}

InvoiceTypes describes each of the InvoiceTypes supported by GOBL invoices, and includes a reference to the matching UNTDID 1001 code.

Functions

This section is empty.

Types

type Charge added in v0.13.0

type Charge struct {
	// Unique identifying for the discount entry
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Line number inside the list of discounts (calculated).
	Index int `json:"i" jsonschema:"title=Index" jsonschema_extras:"calculated=true"`
	// Code to used to refer to the this charge
	Ref string `json:"ref,omitempty" jsonschema:"title=Reference"`
	// Base represents the value used as a base for percent calculations.
	// If not already provided, we'll take the invoices sum before
	// discounts.
	Base *num.Amount `json:"base,omitempty" jsonschema:"title=Base"`
	// Percentage to apply to the invoice's Sum
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
	// Amount to apply (calculated if percent present)
	Amount num.Amount `json:"amount" jsonschema:"title=Amount" jsonschema_extras:"calculated=true"`
	// List of taxes to apply to the charge
	Taxes tax.Set `json:"taxes,omitempty" jsonschema:"title=Taxes"`
	// Code for why was this charge applied?
	Code string `json:"code,omitempty" jsonschema:"title=Reason Code"`
	// Text description as to why the charge was applied
	Reason string `json:"reason,omitempty" jsonschema:"title=Reason"`
	// Additional semi-structured information.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Charge represents a surchange applied to the complete document independent from the individual lines.

func (*Charge) GetTaxes added in v0.20.0

func (m *Charge) GetTaxes() tax.Set

GetTaxes responds with the array of tax rates applied to this line.

func (*Charge) GetTotal added in v0.13.0

func (m *Charge) GetTotal() num.Amount

GetTotal provides the final total for this line, excluding any tax calculations.

func (*Charge) Validate added in v0.13.0

func (m *Charge) Validate() error

Validate checks the discount's fields.

type Delivery

type Delivery struct {
	// The party who will receive delivery of the goods defined in the invoice and is not responsible for taxes.
	Receiver *org.Party `json:"receiver,omitempty" jsonschema:"title=Receiver"`
	// When the goods should be expected
	Date *cal.Date `json:"date,omitempty" jsonschema:"title=Date"`
	// Start of an invoicing or delivery period
	StartDate *cal.Date `json:"start_date,omitempty" jsonschema:"title=Start Date"`
	// End of an invoicing or delivery period
	EndDate *cal.Date `json:"end_date,omitempty" jsonschema:"title=End Date"`
}

Delivery covers the details of the destination for the products described in the invoice body.

func (*Delivery) Validate added in v0.28.0

func (d *Delivery) Validate() error

Validate the delivery details

type Discount added in v0.13.0

type Discount struct {
	// Unique identifying for the discount entry
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Line number inside the list of discounts (calculated)
	Index int `json:"i" jsonschema:"title=Index" jsonschema_extras:"calculated=true"`
	// Reference or ID for this Discount
	Ref string `json:"ref,omitempty" jsonschema:"title=Reference"`
	// Base represents the value used as a base for percent calculations.
	// If not already provided, we'll take the invoices sum.
	Base *num.Amount `json:"base,omitempty" jsonschema:"title=Base"`
	// Percentage to apply to the invoice's Sum.
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
	// Amount to apply (calculated if percent present).
	Amount num.Amount `json:"amount" jsonschema:"title=Amount" jsonschema_extras:"calculated=true"`
	// List of taxes to apply to the discount
	Taxes tax.Set `json:"taxes,omitempty" jsonschema:"title=Taxes"`
	// Code for the reason this discount applied
	Code string `json:"code,omitempty" jsonschema:"title=Reason Code"`
	// Text description as to why the discount was applied
	Reason string `json:"reason,omitempty" jsonschema:"title=Reason"`
	// Additional semi-structured information.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Discount represents an allowance applied to the complete document independent from the individual lines. These have more in common with Invoice Lines than anything else, as each discount must have the correct taxes defined.

func (*Discount) GetTaxes added in v0.20.0

func (m *Discount) GetTaxes() tax.Set

GetTaxes responds with the array of tax rates applied to this line.

func (*Discount) GetTotal added in v0.13.0

func (m *Discount) GetTotal() num.Amount

GetTotal provides the final total for this line, excluding any tax calculations. We return a negative value so that discounts will be applied correctly.

func (*Discount) Validate added in v0.13.0

func (m *Discount) Validate() error

Validate checks the discount's fields.

type DocumentReference added in v0.35.0

type DocumentReference struct {
	// Unique ID copied from the source document.
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Series the reference document belongs to.
	Series string `json:"series,omitempty" jsonschema:"title=Series"`
	// Source document's code or other identifier.
	Code string `json:"code,omitempty" jsonschema:"title=Code"`
	// Link to the source document.
	URL string `json:"url,omitempty" jsonschema:"title=URL,format=uri"`
}

DocumentReference provides a link to a existing document.

func (*DocumentReference) Validate added in v0.35.0

func (dr *DocumentReference) Validate() error

Validate ensures the Document Reference looks correct.

type Invoice

type Invoice struct {
	// Unique document ID. Not required, but always recommended in addition to the Code.
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Used as a prefix to group codes.
	Series string `json:"series,omitempty" jsonschema:"title=Series"`
	// Sequential code used to identify this invoice in tax declarations.
	Code string `json:"code" jsonschema:"title=Code"`
	// Type of invoice document subject to the requirements of the local tax regime.
	Type cbc.Key `json:"type" jsonschema:"title=Type"`
	// Currency for all invoice totals.
	Currency currency.Code `json:"currency" jsonschema:"title=Currency"`
	// Exchange rates to be used when converting the invoices monetary values into other currencies.
	ExchangeRates []*currency.ExchangeRate `json:"exchange_rates,omitempty" jsonschema:"title=Exchange Rates"`
	// Special tax configuration for billing.
	Tax *Tax `json:"tax,omitempty" jsonschema:"title=Tax"`

	// Key information regarding previous invoices and potentially details as to why they
	// were corrected.
	Preceding []*Preceding `json:"preceding,omitempty" jsonschema:"title=Preceding Details"`

	// When the invoice was created.
	IssueDate cal.Date `json:"issue_date" jsonschema:"title=Issue Date"`
	// Date when the operation defined by the invoice became effective.
	OperationDate *cal.Date `json:"op_date,omitempty" jsonschema:"title=Operation Date"`
	// When the taxes of this invoice become accountable, if none set, the issue date is used.
	ValueDate *cal.Date `json:"value_date,omitempty" jsonschema:"title=Value Date"`

	// The taxable entity supplying the goods or services.
	Supplier *org.Party `json:"supplier" jsonschema:"title=Supplier"`
	// Legal entity receiving the goods or services, may be empty in certain circumstances such as simplified invoices.
	Customer *org.Party `json:"customer,omitempty" jsonschema:"title=Customer"`

	// List of invoice lines representing each of the items sold to the customer.
	Lines []*Line `json:"lines,omitempty" jsonschema:"title=Lines"`
	// Discounts or allowances applied to the complete invoice
	Discounts []*Discount `json:"discounts,omitempty" jsonschema:"title=Discounts"`
	// Charges or surcharges applied to the complete invoice
	Charges []*Charge `json:"charges,omitempty" jsonschema:"title=Charges"`
	// Expenses paid for by the supplier but invoiced directly to the customer.
	Outlays []*Outlay `json:"outlays,omitempty" jsonschema:"title=Outlays"`

	// Ordering details including document references and buyer or seller parties.
	Ordering *Ordering `json:"ordering,omitempty" jsonschema:"title=Ordering Details"`
	// Information on when, how, and to whom the invoice should be paid.
	Payment *Payment `json:"payment,omitempty" jsonschema:"title=Payment Details"`
	// Specific details on delivery of the goods referenced in the invoice.
	Delivery *Delivery `json:"delivery,omitempty" jsonschema:"title=Delivery Details"`

	// Summary of all the invoice totals, including taxes (calculated).
	Totals *Totals `json:"totals" jsonschema:"title=Totals" jsonschema_extras:"calculated=true"`

	// Unstructured information that is relevant to the invoice, such as correction or additional
	// legal details.
	Notes []*cbc.Note `json:"notes,omitempty" jsonschema:"title=Notes"`
	// Additional semi-structured data that doesn't fit into the body of the invoice.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Invoice represents a payment claim for goods or services supplied under conditions agreed between the supplier and the customer. In most cases the resulting document describes the actual financial commitment of goods or services ordered from the supplier.

func (*Invoice) Calculate

func (inv *Invoice) Calculate() error

Calculate performs all the calculations required for the invoice totals and taxes. If the original invoice only includes partial calculations, this will figure out what's missing.

func (Invoice) JSONSchemaExtend added in v0.38.0

func (Invoice) JSONSchemaExtend(schema *jsonschema.Schema)

JSONSchemaExtend extends the schema with additional property details

func (*Invoice) RemoveIncludedTaxes added in v0.25.2

func (inv *Invoice) RemoveIncludedTaxes(accuracy uint32) *Invoice

RemoveIncludedTaxes is a special function that will go through all prices which may include the tax included in the invoice, and remove them. The accuracy parameter is used to determine the additional exponent that will be added to prices before calculation with the aim of reducing rounding errors. An accuracy value of 2 is recommended.

A new invoice object is returned, leaving the original objects untouched.

func (*Invoice) ScenarioSummary added in v0.38.0

func (inv *Invoice) ScenarioSummary() *tax.ScenarioSummary

ScenarioSummary determines a summary of the tax scenario for the invoice based on the document type and tax tags.

func (*Invoice) UNTDID1001 added in v0.38.0

func (i *Invoice) UNTDID1001() cbc.Code

UNTDID1001 provides the official code number assigned with the Invoice type.

func (*Invoice) Validate

func (inv *Invoice) Validate() error

Validate checks to ensure the invoice is valid and contains all the information we need.

func (*Invoice) ValidateWithContext added in v0.38.0

func (inv *Invoice) ValidateWithContext(ctx context.Context) error

ValidateWithContext checks to ensure the invoice is valid and contains all the information we need.

type InvoiceTypeDef added in v0.30.0

type InvoiceTypeDef struct {
	Key         cbc.Key  `json:"key" jsonschema:"title=InvoiceType Key"`
	Description string   `json:"description" jsonschema:"title=Description"`
	UNTDID1001  cbc.Code `json:"untdid1001" jsonschema:"title=UNTDID 1001 Code"`
}

InvoiceTypeDef is used to describe a type definition.

type Line

type Line struct {
	// Unique identifier for this line
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Line number inside the parent (calculated)
	Index int `json:"i" jsonschema:"title=Index" jsonschema_extras:"calculated=true"`
	// Number of items
	Quantity num.Amount `json:"quantity" jsonschema:"title=Quantity"`
	// Details about what is being sold
	Item *org.Item `json:"item" jsonschema:"title=Item"`
	// Result of quantity multiplied by the item's price (calculated)
	Sum num.Amount `json:"sum" jsonschema:"title=Sum" jsonschema_extras:"calculated=true"`
	// Discounts applied to this line
	Discounts []*LineDiscount `json:"discounts,omitempty" jsonschema:"title=Discounts"`
	// Charges applied to this line
	Charges []*LineCharge `json:"charges,omitempty" jsonschema:"title=Charges"`
	// Map of taxes to be applied and used in the invoice totals
	Taxes tax.Set `json:"taxes,omitempty" jsonschema:"title=Taxes"`
	// Total line amount after applying discounts to the sum (calculated).
	Total num.Amount `json:"total" jsonschema:"title=Total"  jsonschema_extras:"calculated=true"`
	// Set of specific notes for this line that may be required for
	// clarification.
	Notes []*cbc.Note `json:"notes,omitempty" jsonschema:"title=Notes"`
}

Line is a single row in an invoice.

func (*Line) GetTaxes added in v0.20.0

func (l *Line) GetTaxes() tax.Set

GetTaxes responds with the array of tax rates applied to this line.

func (*Line) GetTotal

func (l *Line) GetTotal() num.Amount

GetTotal provides the final total for this line, excluding any tax calculations.

func (*Line) ValidateWithContext added in v0.38.0

func (l *Line) ValidateWithContext(ctx context.Context) error

ValidateWithContext ensures the line contains everything required using the provided context that should include the regime.

type LineCharge added in v0.13.0

type LineCharge struct {
	// Percentage if fixed amount not applied
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
	// Fixed or resulting charge amount to apply (calculated if percent present).
	Amount num.Amount `json:"amount" jsonschema:"title=Amount" jsonschema_extras:"calculated=true"`
	// Reference code.
	Code string `json:"code,omitempty" jsonschema:"title=Code"`
	// Text description as to why the charge was applied
	Reason string `json:"reason,omitempty" jsonschema:"title=Reason"`
}

LineCharge represents an amount added to the line, and will be applied before taxes. TODO: use UNTDID 7161 code list

func (*LineCharge) Validate added in v0.13.0

func (lc *LineCharge) Validate() error

Validate checks the line charge's fields.

type LineDiscount added in v0.13.0

type LineDiscount struct {
	// Percentage if fixed amount not applied
	Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
	// Fixed discount amount to apply (calculated if percent present).
	Amount num.Amount `json:"amount" jsonschema:"title=Value" jsonschema_extras:"calculated=true"`
	// Reason code.
	Code string `json:"code,omitempty" jsonschema:"title=Code"`
	// Text description as to why the discount was applied
	Reason string `json:"reason,omitempty" jsonschema:"title=Reason"`
}

LineDiscount represents an amount deducted from the line, and will be applied before taxes. TODO: use UNTDID 5189 code list

func (*LineDiscount) Validate added in v0.13.0

func (ld *LineDiscount) Validate() error

Validate checks the line discount's fields.

type Ordering

type Ordering struct {
	// Identifier assigned by the customer or buyer for internal routing purposes.
	Code string `json:"code,omitempty" jsonschema:"title=Code"`
	// Project this invoice refers to.
	Project *DocumentReference `json:"project,omitempty" jsonschema:"title=Project"`
	// The identification of a contract.
	Contract *DocumentReference `json:"contract,omitempty" jsonschema:"title=Contract"`
	// Purchase order issued by the customer or buyer.
	Purchase *DocumentReference `json:"purchase,omitempty" jsonschema:"title=Purchase Order"`
	// Sales order issued by the supplier or seller.
	Sale *DocumentReference `json:"sale,omitempty" jsonschena:"title=Sales Order"`
	// Receiving Advice.
	Receiving *DocumentReference `json:"receiving,omitempty" jsonschame:"title=Receiving Advice"`
	// Despatch advice.
	Despatch *DocumentReference `json:"despatch,omitempty" jsonschema:"title=Despatch Advice"`
	// Tender advice, the identification of the call for tender or lot the invoice relates to.
	Tender *DocumentReference `json:"tender,omitempty" jsonscheme:"title=Tender Advice"`

	// Party who is responsible for making the purchase, but is not responsible
	// for handling taxes.
	Buyer *org.Party `json:"buyer,omitempty" jsonschema:"title=Buyer"`
	// Party who is selling the goods but is not responsible for taxes like the
	// supplier.
	Seller *org.Party `json:"seller,omitempty" jsonschema:"title=Seller"`
}

Ordering provides additional information about the ordering process including references to other documents and alternative parties involved in the order-to-delivery process.

func (*Ordering) Validate added in v0.28.0

func (o *Ordering) Validate() error

Validate the ordering details.

type Outlay

type Outlay struct {
	// Unique identity for this outlay.
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Outlay number index inside the invoice for ordering (calculated).
	Index int `json:"i" jsonschema:"title=Index" jsonschema_extras:"calculated=true"`
	// When was the outlay made.
	Date *cal.Date `json:"date,omitempty" jsonschema:"title=Date"`
	// Invoice number or other reference detail used to identify the outlay.
	Code string `json:"code,omitempty" jsonschema:"title=Code"`
	// Series of the outlay invoice.
	Series string `json:"series,omitempty" jsonschema:"title=Series"`
	// Details on what the outlay was.
	Description string `json:"desc" jsonschema:"title=Description"`
	// Who was the supplier of the outlay
	Supplier *org.Party `json:"supplier,omitempty" jsonschema:"title=Supplier"`
	// Amount paid by the supplier.
	Amount num.Amount `json:"amount" jsonschema:"title=Amount"`
}

Outlay represents a reimbursable expense that was paid for by the supplier and invoiced separately by the third party directly to the customer. Most suppliers will want to include the expenses of their providers as part of their own operational costs. However, outlays are common in countries like Spain where it is typical for an accountant or lawyer to pay for notary fees, but forward the invoice to the customer.

func (*Outlay) Validate added in v0.5.0

func (o *Outlay) Validate() error

Validate ensures the outlay contains everything required.

type Payment

type Payment struct {
	// The party responsible for receiving payment of the invoice, if not the supplier.
	Payee *org.Party `json:"payee,omitempty" jsonschema:"title=Payer"`
	// Payment terms or conditions.
	Terms *pay.Terms `json:"terms,omitempty" jsonschema:"title=Terms"`
	// Any amounts that have been paid in advance and should be deducted from the amount due.
	Advances []*pay.Advance `json:"advances,omitempty" jsonschema:"title=Advances"`
	// Details on how payment should be made.
	Instructions *pay.Instructions `json:"instructions,omitempty" jsonschema:"title=Instructions"`
}

Payment contains details as to how the invoice should be paid.

func (*Payment) Validate added in v0.28.0

func (p *Payment) Validate() error

Validate checks to make sure the payment data looks good

type Preceding

type Preceding struct {
	// Preceding document's UUID if available can be useful for tracing.
	UUID *uuid.UUID `json:"uuid,omitempty" jsonschema:"title=UUID"`
	// Series identification code
	Series string `json:"series,omitempty" jsonschema:"title=Series"`
	// Code of the previous document.
	Code string `json:"code" jsonschema:"title=Code"`
	// The issue date of the previous document.
	IssueDate cal.Date `json:"issue_date" jsonschema:"title=Issue Date"`
	// Human readable description on why the preceding invoice is being replaced.
	Reason string `json:"reason,omitempty" jsonschema:"title=Reason"`
	// Seals of approval from other organisations that may need to be listed.
	Stamps []*cbc.Stamp `json:"stamps,omitempty" jsonschema:"title=Stamps"`
	// Tax regime specific keys reflecting why the preceding invoice is being replaced.
	Corrections []cbc.Key `json:"corrections,omitempty" jsonschema:"title=Corrections"`
	// Tax regime specific keys reflecting the method used to correct the preceding invoice.
	CorrectionMethod cbc.Key `json:"correction_method,omitempty" jsonschema:"title=Correction Method"`
	// Tax period in which the previous invoice had an effect required by some tax regimes and formats.
	Period *cal.Period `json:"period,omitempty" jsonschema:"title=Period"`
	// Additional semi-structured data that may be useful in specific regions
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Preceding allows for information to be provided about a previous invoice that this one will replace, subtract from, or add to. If this is used, the invoice type code will most likely need to be set to `corrective`, `credit-note`, or similar.

func (*Preceding) Validate added in v0.16.0

func (p *Preceding) Validate() error

Validate ensures the preceding details look okay

type Tax added in v0.20.0

type Tax struct {
	// Category of the tax already included in the line item prices, especially
	// useful for B2C retailers with customers who prefer final prices inclusive of
	// tax.
	PricesInclude cbc.Code `json:"prices_include,omitempty" jsonschema:"title=Prices Include"`

	// Special tax tags that apply to this invoice according to local requirements.
	Tags []cbc.Key `json:"tags,omitempty" jsonschema:"title=Tags"`

	// Any additional data that may be required for processing, but should never
	// be relied upon by recipients.
	Meta cbc.Meta `json:"meta,omitempty" jsonschema:"title=Meta"`
}

Tax defines a summary of the taxes which may be applied to an invoice.

func (*Tax) ContainsTag added in v0.38.0

func (t *Tax) ContainsTag(key cbc.Key) bool

ContainsTag returns true if the tax contains the given tag.

func (*Tax) ValidateWithContext added in v0.38.0

func (t *Tax) ValidateWithContext(ctx context.Context) error

ValidateWithContext ensures the tax details look valid.

type TaxScheme added in v0.20.0

type TaxScheme string

TaxScheme allows for defining a specific or special scheme that applies to the billing document. Schemes are defined as needed for each region.

type Totals

type Totals struct {
	// Sum of all line item sums
	Sum num.Amount `json:"sum" jsonschema:"title=Sum"`
	// Sum of all document level discounts
	Discount *num.Amount `json:"discount,omitempty" jsonschema:"title=Discount"`
	// Sum of all document level charges
	Charge *num.Amount `json:"charge,omitempty" jsonschema:"title=Charge"`
	// If prices include tax, this is the total tax included in the price.
	TaxIncluded *num.Amount `json:"tax_included,omitempty" jsonschema:"title=Tax Included"`
	// Sum of all line sums minus the discounts, plus the charges, without tax.
	Total num.Amount `json:"total" jsonschema:"title=Total"`
	// Summary of all the taxes included in the invoice.
	Taxes *tax.Total `json:"taxes,omitempty" jsonschema:"title=Tax Totals"`
	// Total amount of tax to apply to the invoice.
	Tax num.Amount `json:"tax,omitempty" jsonschema:"title=Tax"`
	// Grand total after all taxes have been applied.
	TotalWithTax num.Amount `json:"total_with_tax" jsonschema:"title=Total with Tax"`
	// Total paid in outlays that need to be reimbursed
	Outlays *num.Amount `json:"outlays,omitempty" jsonschema:"title=Outlay Totals"`
	// Total amount to be paid after applying taxes and outlays.
	Payable num.Amount `json:"payable" jsonschema:"title=Payable"`
	// Total amount already paid in advance.
	Advances *num.Amount `json:"advance,omitempty" jsonschema:"title=Advance"`
	// How much actually needs to be paid now.
	Due *num.Amount `json:"due,omitempty" jsonschema:"title=Due"`
}

Totals contains the summaries of all calculations for the invoice.

func (*Totals) ValidateWithContext added in v0.38.0

func (t *Totals) ValidateWithContext(ctx context.Context) error

ValidateWithContext checks the totals calculated for the invoice.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL