README
¶
🇲🇽 GOBL Mexico Tax Regime
Mexico uses the CFDI (Comprobante Fiscal Digital por Internet) format for their e-invoicing system.
Example MX GOBL files can be found in the examples (YAML uncalculated documents) and examples/out (JSON calculated envelopes) subdirectories.
Public Documentation
Mexico specifics
Mexican invoices as defined in the CFDI specification must include a set of specific codes that will either need to be known in advance by the supplier or requested from the customer during their purchase process.
The following sections highlight these codes and how they can be defined inside your GOBL documents.
LugarExpedicion - Issue Place
Every MX invoice needs to specify the postal code of place where it was issued. In a GOBL Invoice, you can provide this value using the mx-cfdi-issue-place extension under the tax of the invoice.
Example
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"tax": {
"ext": {
"mx-cfdi-issue-place": "26015"
}
},
// [...]
}
RegimenFiscal - Fiscal Regime
Every Supplier and Customer in a Mexican invoice must be associated with a fiscal regime code. You'll need to ensure this field's value is requested from customers when they require an invoice.
In GOBL the mx-cfdi-fiscal-regime extension key is used alongside the value expected by the SAT.
Example
The following example will associate the supplier with the 601 fiscal regime code:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"supplier": {
"name": "ESCUELA KEMPER URGATE",
"tax_id": {
"country": "MX",
"code": "EKU9003173C9"
},
"ext": {
"mx-cfdi-fiscal-regime": "601"
}
}
// [...]
}
DomicilioFiscalReceptor - Receipt's Tax Address
In CFDI, DomicilioFiscalReceptor is a mandatory field that specifies the postal code of the recepient's tax address. In a GOBL Invoice, you can provide this value setting the mx-cfdi-post-code extension of the invoice's customer.
Example
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"customer": {
"name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"tax_id": {
"country": "MX",
"code": "URE180429TM6"
},
"ext": {
"mx-cfdi-fiscal-regime": "601",
"mx-cfdi-use": "G01",
"mx-cfdi-post-code": "65000"
}
}
// [...]
}
UsoCFDI - CFDI Use
The CFDI’s UsoCFDI field specifies how the invoice's recipient will use the invoice to deduce taxes for the expenditure made. In a GOBL Invoice, include the mx-cfdi-use extension in the customer.
This field will be validated for presence and will be checked against the list of codes defined as part of the CFDI specification.
Example
The following GOBL maps to the G03 (Gastos en general) value of the UsoCFDI field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"customer": {
"name": "UNIVERSIDAD ROBOTICA ESPAÑOLA",
"tax_id": {
"country": "MX",
"code": "URE180429TM6"
},
"ext": {
"mx-cfdi-fiscal-regime": "601",
"mx-cfdi-use": "G01",
"mx-cfdi-post-code": "65000"
}
}
// [...]
}
MetodoPago – Payment Method
The CFDI’s MetodoPago field specifies whether the invoice has been fully paid at the moment of issuing the invoice (PUE - Pago en una sola exhibición) or whether it will be paid in one or several instalments after that (PPD – Pago en parcialidades o diferido).
In GOBL, the presence or absence of payment advances covering the invoice’s total payable amount will determine whether the MetodoPago will be set to PUE or PPD.
Please note that if you don't include any advances in your GOBL invoice, it will be assumed that the payment of the invoice is outstanding (MetodoPago = PPD). This implies that the invoice supplier will have to issue “CFDI de Complemento de Pago” (remittance advice) documents at a later stage when receiving the invoice payments.
Examples
The following GOBL will map to the PUE (Pago en una sola exhibición) value of the MetodoPago field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"payment": {
"advances": [
{
"key": "credit-transfer",
"desc": "Full credit card payment",
"amount": "232.00"
}
]
},
"totals": {
"payable": "232.00",
"advance": "232.00",
"due": "0.00"
// [...]
}
}
The following GOBL will map to the PPD (Pago en parcialidades o diferido) value of the MetodoPago field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"payment": {
"advances": [
{
"key": "credit-transfer",
"desc": "Partial credit card payment",
"amount": "100.00"
}
]
},
"totals": {
"payable": "232.00",
"advance": "100.00",
"due": "132.00"
// [...]
}
}
The following GOBL will map to the PPD (Pago en parcialidades o diferido) value of the MetodoPago field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// No "payment" key [...]
"totals": {
"payable": "232.00",
// [...]
}
}
FormaPago - Payment Means
The CFDI’s FormaPago field specifies an invoice's means of payment.
If the invoice hasn't been fully paid at the time of issuing the invoice (MetodoPago = PPD, see the previous section) the value of FormaPago will always be set to 99 (Por definir).
Otherwise (MetodoPago = PUE), the FormaPago value will be mapped from the key of the largest payment advance in the GOBL invoice. The following table lists all the supported values and how GOBL will map them:
| Code | Name | GOBL Payment Advance Key |
|---|---|---|
| 01 | Efectivo | cash |
| 02 | Cheque nominativo | cheque |
| 03 | Transferencia electrónica de fondos | credit-transfer |
| 04 | Tarjeta de crédito | card |
| 05 | Monedero electrónico | online+wallet |
| 06 | Dinero electrónico | online |
| 08 | Vales de despensa | other+grocery-vouchers |
| 12 | Dación en pago | other+in-kind |
| 13 | Pago por subrogación | other+subrogation |
| 14 | Pago por consignación | other+consignment |
| 15 | Condonación | other+debt-relief |
| 17 | Compensación | netting |
| 23 | Novación | other+novation |
| 24 | Confusión | other+merger |
| 25 | Remisión de deuda | other+remission |
| 26 | Prescripción o caducidad | other+expiration |
| 27 | A satisfacción del acreedor | other+satisfy-creditor |
| 28 | Tarjeta de débito | card+debit |
| 29 | Tarjeta de servicios | card+services |
| 30 | Aplicación de anticipos | other+advance |
| 31 | Intermediario pagos | other+intermediary |
| 99 | Por definir | other |
Example
The following GOBL maps to the 05 (Monedero electrónico) value of the FormaPago field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"payment": {
"advances": [
{
"key": "online+wallet",
"desc": "Prepago con monedero electrónico",
"amount": "100.00"
}
]
}
}
ClaveUnidad - Unit Code
The CFDI’s ClaveUnidad field specifies the unit in which the quantity of an invoice's line is given. These are UNECE codes that GOBL will map directly from the invoice's line item unit. See the source code for the full list of supported units with their associated UNECE codes.
Example
The following GOBL maps to the KGM (Kilogram) value of the ClaveUnidad field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"lines": [
{
// [...]
"item": {
"name": "Jasmine rice",
"unit": "kg",
"price": "1.27"
},
}
]
}
ClaveProdServ - Product or Service Code
The CFDI’s ClaveProdServ field specifies the type of an invoice's line item. GOBL uses the line item extension key mx-cfdi-prod-serv to map the code directly to the ClaveProdServ field.
The catalogue of available Product or Service codes that form part of the CFDI standard is immense with some 50.000 entries to choose from. Due the huge number of codes GOBL will not validate these fields, you'll have to check with local accountants to check which code should be used for your products or services.
Example
The following GOBL maps to the 10101602 ("live ducks") value to the ClaveProdServ field:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"lines": [
{
// [...]
"item": {
"name": "Selección de patos vivos",
"ext": {
"mx-cfdi-prod-serv": "10101602"
}
},
}
]
}
Generic RFCs
In MX, CFDI invoices to end consumers need to use a generic RFC code (XAXX010101000) in the document's Receptor and some specific values for the supplier extensions. In GOBL, you don't need to enter those values explicitly. Just set the simplified tax tag in your invoice and exclude the customer, the GOBL to CFDI conversor will take care of the rest:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"tax": {
"tags": [
"simplified"
]
}
// No "customer" entry
}
Similarly, CFDI invoices to foreign customers are required to use the foreign generic RFC (XEXX010101000) along with some specific values for the extensions. The country and the local tax code of the supplier are included in separated CFDI fields. And again, in GOBL, you just need to provide the actual country and tax code of the supplier (without extensions), and the GOBL to CFDI conversor will take care of producing the correct document:
{
"$schema": "https://gobl.org/draft-0/bill/invoice",
// [...]
"customer": {
"name": "Almuerzos Colombianos SAS",
"tax_id": {
"country": "CO",
"code": "9014514805"
}
}
// [...]
}
Complements
Complements let you include additional complementary information to your GOBL documents. The following sections describe the complements made available by the MX regime, their purpose and how you can use them.
Fuel Account Balance
The Fuel Account Balance complement carries the data to produce a CFDI’s “Complemento de Estado de Cuenta de Combustibles para Monederos Electrónicos” (version 1.2 revision B) providing detailed information about fuel purchases made with electronic wallets.
In Mexico, e-wallet suppliers use this complement to report this information in the invoices to their customers.
Learn more about this complement here:
Food Vouchers
The Food Vouchers complement carries the data to produce a CFDI's “Complemento de Vales de Despensa” (version 1.0) providing detailed information about food vouchers issued by an e-wallet supplier to its customer's employees.
In Mexico, e-wallet suppliers use this complement to report this information in the invoices to their customers.
Learn more about this complement here:
Documentation
¶
Overview ¶
Package mx provides the Mexican tax regime.
Index ¶
- Constants
- Variables
- func Calculate(doc interface{}) error
- func DetermineTaxCodeType(code cbc.Code) cbc.Key
- func New() *tax.Regime
- func Validate(doc interface{}) error
- type FoodVouchers
- type FoodVouchersEmployee
- type FoodVouchersLine
- type FuelAccountBalance
- type FuelAccountItem
- type FuelAccountLine
- type FuelAccountTax
Constants ¶
const ( ExtKeyCFDIIssuePlace = "mx-cfdi-issue-place" ExtKeyCFDIPostCode = "mx-cfdi-post-code" ExtKeyCFDIFiscalRegime = "mx-cfdi-fiscal-regime" ExtKeyCFDIUse = "mx-cfdi-use" ExtKeyCFDIProdServ = "mx-cfdi-prod-serv" // name from XML field: ClaveProdServ )
Mexican CFDI extension keys required by the SAT (tax authority in Mexico) in all invoices and cannot be determined automatically.
const ( CURPPattern = "" /* 132-byte string literal not displayed */ SocialSecurityPattern = "^[0-9]{11}$" )
Complement's Codes Patterns
const ( FuelAccountPriceMinimumPrecision = 3 FuelAccountTotalsPrecision = 2 )
Constants for the precision of complement's amounts
const ( KeySATFormaPago cbc.Key = "sat-forma-pago" // for mapping to c_FormaPago’s codes KeySATTipoDeComprobante cbc.Key = "sat-tipo-de-comprobante" // for mapping to c_TipoDeComprobante’s codes KeySATTipoRelacion cbc.Key = "sat-tipo-relacion" // for mapping to c_TipoRelacion’s codes KeySATImpuesto cbc.Key = "sat-impuesto" // for mapping to c_Impuesto’s codes )
Custom keys used typically in meta or codes information.
const ( StampCFDISignature cbc.Key = "cfdi-sig" // Signature - Sello Digital del CFDI StampCFDISerial cbc.Key = "cfdi-serial" // Cert Serial - Número de Certificado del CFDI StampSATSignature cbc.Key = "sat-sig" // Signature - Sello Digital del SAT (optional) StampSATSerial cbc.Key = "sat-serial" // Cert Serial - Número de Certificado SAT StampSATTimestamp cbc.Key = "sat-timestamp" // Timestamp - Fecha y hora de certificación del SAT StampSATUUID cbc.Key = "sat-uuid" // Folio Fiscal StampSATURL cbc.Key = "sat-url" // URL QR Code StampSATProviderRFC cbc.Key = "sat-provider-rfc" // Provider RFC - RFC del Proveedor de Certificación StampSATChain cbc.Key = "sat-chain" // Cadena original del complemento de certificación digital del SAT )
Official SAT and CFDI codes to include in stamps.
const ( MeansKeyWallet cbc.Key = "wallet" MeansKeyGroceryVouchers cbc.Key = "grocery-vouchers" MeansKeyInKind cbc.Key = "in-kind" MeansKeySubrogation cbc.Key = "subrogation" MeansKeyConsignment cbc.Key = "consignment" MeansKeyDebtRelief cbc.Key = "debt-relief" MeansKeyNovation cbc.Key = "novation" MeansKeyMerger cbc.Key = "merger" MeansKeyRemission cbc.Key = "remission" MeansKeyExpiration cbc.Key = "expiration" MeansKeySatisfyCreditor cbc.Key = "satisfy-creditor" MeansKeyDebit cbc.Key = "debit" MeansKeyServices cbc.Key = "services" MeansKeyAdvance cbc.Key = "advance" MeansKeyIntermediary cbc.Key = "intermediary" )
Regime Specific Payment Means Extension Keys
const ( TaxCategoryRVAT cbc.Code = "RVAT" // IVA (Retenido) TaxCategoryIEPS cbc.Code = "IEPS" // Impuesto Especial sobre Producción y Servicios TaxCategoryRIEPS cbc.Code = "RIEPS" // Impuesto Especial sobre Producción y Servicios (Retenido) TaxCategoryISR cbc.Code = "ISR" // Impuesto Sobre la Renta )
Local tax categories
const ( TaxIdentityCodeGeneric cbc.Code = "XAXX010101000" TaxIdentityCodeForeign cbc.Code = "XEXX010101000" )
Constants used to specific tax identity codes.
const ( TaxIdentityTypePerson cbc.Key = "person" TaxIdentityTypeCompany cbc.Key = "company" )
Tax Identity Type
const ( TaxIdentityPatternPerson = `^([A-ZÑ&]{4})([0-9]{6})([A-Z0-9]{3})$` TaxIdentityPatternCompany = `^([A-ZÑ&]{3})([0-9]{6})([A-Z0-9]{3})$` )
Tax Identity Patterns
const (
FoodVouchersFinalPrecision = 2
)
Constants for the precision of the complement's amounts
const (
TaxRateExempt cbc.Key = "exempt"
)
Local tax rates
Variables ¶
var ( CURPRegexp = regexp.MustCompile(CURPPattern) SocialSecurityRegexp = regexp.MustCompile(SocialSecurityPattern) )
Complement's Codes Regexps
var ( TaxIdentityRegexpPerson = regexp.MustCompile(TaxIdentityPatternPerson) TaxIdentityRegexpCompany = regexp.MustCompile(TaxIdentityPatternCompany) )
Tax Identity Regexp
var FuelAccountValidTaxCodes = []any{ tax.CategoryVAT, TaxCategoryIEPS, }
FuelAccountValidTaxCodes lists of the complement's allowed tax codes
Functions ¶
func Calculate ¶
func Calculate(doc interface{}) error
Calculate performs regime specific calculations.
func DetermineTaxCodeType ¶
DetermineTaxCodeType determines the type of tax code or provides an empty key if it looks invalid.
Types ¶
type FoodVouchers ¶ added in v0.61.0
type FoodVouchers struct {
// Customer's employer registration number (maps to `registroPatronal`).
EmployerRegistration string `json:"employer_registration,omitempty" jsonschema:"title=Employer Registration"`
// Customer's account number (maps to `numeroDeCuenta`).
AccountNumber string `json:"account_number" jsonschema:"title=Account Number"`
// Sum of all line amounts (calculated, maps to `total`).
Total num.Amount `json:"total" jsonschema:"title=Total" jsonschema_extras:"calculated=true"`
// List of food vouchers issued to the customer's employees (maps to `Conceptos`).
Lines []*FoodVouchersLine `json:"lines" jsonschema:"title=Lines"`
}
FoodVouchers carries the data to produce a CFDI's "Complemento de Vales de Despensa" (version 1.0) providing detailed information about food vouchers issued by an e-wallet supplier to its customer's employees.
This struct maps to the `ValesDeDespensa` root node in the CFDI's complement.
func (*FoodVouchers) Calculate ¶ added in v0.61.0
func (fvc *FoodVouchers) Calculate() error
Calculate performs the complement's calculations and normalisations.
func (*FoodVouchers) Validate ¶ added in v0.61.0
func (fvc *FoodVouchers) Validate() error
Validate checks the FoodVouchers data according to the SAT's rules for the "Complemento de Vales de Despensa".
type FoodVouchersEmployee ¶ added in v0.60.0
type FoodVouchersEmployee struct {
// Employee's tax identity code (maps to `rfc`).
TaxCode cbc.Code `json:"tax_code" jsonschema:"title=Employee's Tax Identity Code"`
// Employee's CURP ("Clave Única de Registro de Población", maps to `curp`).
CURP cbc.Code `json:"curp" jsonschema:"title=Employee's CURP"`
// Employee's name (maps to `nombre`).
Name string `json:"name" jsonschema:"title=Employee's Name"`
// Employee's Social Security Number (maps to `numSeguridadSocial`).
SocialSecurity cbc.Code `json:"social_security,omitempty" jsonschema:"title=Employee's Social Security Number"`
}
FoodVouchersEmployee represents an employee that received a food voucher. It groups employee related field that appears under the `Concepto` node in the CFDI's complement.
func (*FoodVouchersEmployee) Validate ¶ added in v0.60.0
func (fve *FoodVouchersEmployee) Validate() error
Validate checks the FoodVouchersEmployee data is valid.
type FoodVouchersLine ¶ added in v0.60.0
type FoodVouchersLine struct {
// Identifier of the e-wallet that received the food voucher (maps to `Identificador`).
EWalletID cbc.Code `json:"e_wallet_id" jsonschema:"title=E-wallet Identifier"`
// Date and time of the food voucher's issue (maps to `Fecha`).
IssueDateTime cal.DateTime `json:"issue_date_time" jsonschema:"title=Issue Date and Time"`
// Employee that received the food voucher.
Employee *FoodVouchersEmployee `json:"employee,omitempty" jsonschema:"title=Employee"`
// Amount of the food voucher (maps to `importe`).
Amount num.Amount `json:"amount" jsonschema:"title=Amount"`
}
FoodVouchersLine represents a single food voucher issued to the e-wallet of one of the customer's employees. It maps to one `Concepto` node in the CFDI's complement.
func (*FoodVouchersLine) Validate ¶ added in v0.60.0
func (fvl *FoodVouchersLine) Validate() error
Validate checks the FoodVouchersLine data is valid.
type FuelAccountBalance ¶ added in v0.60.0
type FuelAccountBalance struct {
// Customer's account number (maps to `NumeroDeCuenta`).
AccountNumber string `json:"account_number" jsonschema:"title=Account Number"`
// Sum of all line totals (i.e. taxes not included) (calculated, maps to `SubTotal`).
Subtotal num.Amount `json:"subtotal" jsonschema:"title=Subtotal" jsonschema_extras:"calculated=true"`
// Grand total after taxes have been applied (calculated, maps to `Total`).
Total num.Amount `json:"total" jsonschema:"title=Total" jsonschema_extras:"calculated=true"`
// List of fuel purchases made with the customer's e-wallets (maps to `Conceptos`).
Lines []*FuelAccountLine `json:"lines" jsonschema:"title=Lines"`
}
FuelAccountBalance carries the data to produce a CFDI's "Complemento de Estado de Cuenta de Combustibles para Monederos Electrónicos" (version 1.2 revision B) providing detailed information about fuel purchases made with electronic wallets. In Mexico, e-wallet suppliers are required to report this complementary information in the invoices they issue to their customers.
This struct maps to the `EstadoDeCuentaCombustible` root node in the CFDI's complement.
func (*FuelAccountBalance) Calculate ¶ added in v0.60.0
func (fab *FuelAccountBalance) Calculate() error
Calculate performs the complement's calculations and normalisations.
func (*FuelAccountBalance) Validate ¶ added in v0.60.0
func (fab *FuelAccountBalance) Validate() error
Validate ensures that the complement's data is valid.
type FuelAccountItem ¶ added in v0.60.0
type FuelAccountItem struct {
// Type of fuel (one of `c_ClaveTipoCombustible` codes, maps to `TipoCombustible`).
Type cbc.Code `json:"type" jsonschema:"title=Type"`
// Reference unit of measure used in the price and the quantity (maps to `Unidad`).
Unit org.Unit `json:"unit,omitempty" jsonschema:"title=Unit"`
// Name of the fuel (maps to `NombreCombustible`).
Name string `json:"name" jsonschema:"title=Name"`
// Base price of a single unit of the fuel without taxes (maps to `ValorUnitario`).
Price num.Amount `json:"price" jsonschema:"title=Price"`
}
FuelAccountItem provides the details of a fuel purchase. Its fields map to attributes of the `ConceptoEstadoDeCuentaCombustible` node in the CFDI's complement.
func (*FuelAccountItem) Validate ¶ added in v0.60.0
func (fai *FuelAccountItem) Validate() error
Validate ensures that the item's data is valid.
type FuelAccountLine ¶ added in v0.60.0
type FuelAccountLine struct {
// Identifier of the e-wallet used to make the purchase (maps to `Identificador`).
EWalletID cbc.Code `json:"e_wallet_id" jsonschema:"title=E-wallet Identifier"`
// Date and time of the purchase (maps to `Fecha`).
PurchaseDateTime cal.DateTime `json:"purchase_date_time" jsonschema:"title=Purchase Date and Time"`
// Tax Identity Code of the fuel's vendor (maps to `Rfc`)
VendorTaxCode cbc.Code `json:"vendor_tax_code" jsonschema:"title=Vendor's Tax Identity Code"`
// Code of the service station where the purchase was made (maps to `ClaveEstacion`).
ServiceStationCode cbc.Code `json:"service_station_code" jsonschema:"title=Service Station Code"`
// Amount of fuel units purchased (maps to `Cantidad`)
Quantity num.Amount `json:"quantity" jsonschema:"title=Quantity"`
// Details of the fuel purchased.
Item *FuelAccountItem `json:"item" jsonschema:"title=Item"`
// Identifier of the purchase (maps to `FolioOperacion`).
PurchaseCode cbc.Code `json:"purchase_code" jsonschema:"title=Purchase Code"`
// Result of quantity multiplied by the unit price (maps to `Importe`).
Total num.Amount `json:"total" jsonschema:"title=Total" jsonschema_extras:"calculated=true"`
// Map of taxes applied to the purchase (maps to `Traslados`).
Taxes []*FuelAccountTax `json:"taxes" jsonschema:"title=Taxes"`
}
FuelAccountLine represents a single fuel purchase made with an e-wallet issued by the invoice's supplier. It maps to one `ConceptoEstadoDeCuentaCombustible` node in the CFDI's complement.
func (*FuelAccountLine) Validate ¶ added in v0.60.0
func (fal *FuelAccountLine) Validate() error
Validate ensures that the line's data is valid.
type FuelAccountTax ¶ added in v0.60.0
type FuelAccountTax struct {
// Category that identifies the tax ("VAT" or "IEPS", maps to `Impuesto`)
Category cbc.Code `json:"cat" jsonschema:"title=Category"`
// Percent applicable to the line total (tasa) to use instead of Rate (maps to `TasaoCuota`)
Percent *num.Percentage `json:"percent,omitempty" jsonschema:"title=Percent"`
// Rate is a fixed fee to apply to the line quantity (cuota) (maps to `TasaOCuota`)
Rate *num.Amount `json:"rate,omitempty" jsonschema:"title=Rate"`
// Total amount of the tax once the percent or rate has been applied (maps to `Importe`).
Amount num.Amount `json:"amount" jsonschema:"title=Amount" jsonschema_extras:"calculated=true"`
}
FuelAccountTax represents a single tax applied to a fuel purchase. It maps to one `Traslado` node in the CFDI's complement.
func (*FuelAccountTax) Validate ¶ added in v0.60.0
func (fat *FuelAccountTax) Validate() error
Validate ensures that the tax's data is valid.
Source Files