co

README

🇨🇴 GOBL Colombia Tax Regime

Example CO GOBL files can be found in the examples (YAML uncalculated documents) and examples/out (JSON calculated envelopes) subdirectories.

Colombia specifics

Invoice Series & Code

Invoices ("Facturas de Venta") as expected in many countries require a series and unique sequential code to be issued for each document. The DIAN in colombia however have gone a step further and require invoice series to be pre-registered with the government.

Details on how to do this are available here.

Municipality codes

The DIAN requires that Colombian addresses in the invoice specificy its municipality code. The list of municipality codes is available here.

In a GOBL invoice, you can provide the supplier's or customer's municipality code using the co-dian-municipality extension. For example:

"supplier": {
  "name": "EXAMPLE SUPPLIER S.A.S.",
  "tax_id": {
    "country": "CO",
    "code": "9014514812"
  },
  "ext": {
    "co-dian-municipality": "11001" // Bogotá, D.C.
  },
  // [...]
},
"customer": {
  "name": "EXAMPLE CUSTOMER S.A.S.",
  "tax_id": {
    "country": "CO",
    "code": "9014514805"
  },
  "ext": {
    "co-dian-municipality": "05001" // Medellín
  },
  // [...]
},

Customer identities

While the DIAN requires suppliers of invoices to identify themselves using their NIT, in the case of customers, it allows various identification types. Each identification type has a specific code that must be sent to the DIAN.

B2B

In a GOBL invoice, Colombian business customers are required to provide a Tax ID with the company's NIT to be reported with the 31 (NIT) DIAN ID type. Foreign business customers must also provide a Tax ID with their country's VAT code, and that will be reported to the DIAN using the 50 (NIT de otro país) type.

For example:

"customer": {
  "name": "EXAMPLE CUSTOMER S.A.S.",
  "tax_id": {
    "country": "CO",
    "code": "9014514805" // NIT. DIAN type 31
  },
  "ext": {
    "co-dian-municipality": "11001"
  },
  "addresses": [
    {
      "street": "CRA 8 113 31 OF 703",
      "locality": "Bogotá, D.C.",
      "region": "Bogotá",
      "country": "CO"
    }
  ]
}

B2C

In the case of non-business customers, the GOBL invoice will need to include the tax tag simplified. That will allow to omit the customer or identify it with any of the other document types accepted by the DIAN. They'll just need to include an Identity object with any of the keys below:

GOBL Identity Key	DIAN ID type	Description
co-civil-register	11	Registro civil
co-id-card	12	Tarjeta de identidad
co-citizen-id	13	Cédula de ciudadanía
co-foreigner-id-card	21	Tarjeta de extranjería
co-foreigner-id	22	Cédula de extranjería
co-passport	41	Pasaporte
co-foreign-id	42	Documento de identificación extranjero
co-pep	47	PEP (Permiso Especial de Permanencia)
co-nuip	91	NUIP

For example:

"tax": {
  "tags": ["simplified"]
},
"customer": {
  "name": "Ángel Pérez",
  "identities": [
    {
      "key": "co-passport", // DIAN type 41
      "code": "1234567890"
    }
  ]
}

Note that GOBL simplified invoices don't require a customer (or its identity) to be present. In the lack of a customer identity, the reserved code for final consumers (222222222222) will be automatically sent to the DIAN (i.e., no need to set it explicitly)

For example:

"tax": {
  "tags": ["simplified"]
},
"customer": { // The customer could be fully omitted as well
  "name": "Juan Fernández"
}

Credit and debit correction codes

The DIAN requires credit and debit notes sent to them to specify a code with a cause of the correction.

In a GOBL invoice, you'll need to include the extension co-dian-credit-code (for credit notes) or co-dian-debit-code (for debit notes) as part of the Preceding section of the document. Each extension allows a different set of values:

co-dian-credit-code

Code	Description
1	Partial refund
2	Revoked
3	Discount
4	Adjustment
5	Other

co-dian-debit-code

Code	Description
1	Interest
2	Pending charges
3	Change in value
4	Other

For example:

"preceding": [
  {
    "uuid": "0190e063-7676-7000-8c58-2db7172a4e58",
    "type": "standard",
    "series": "SETT",
    "code": "1010006",
    "issue_date": "2024-07-23",
    "reason": "Reason",
    "stamps": [
      {
          "prv": "dian-cude",
          "val": "57601dd1ab69213ccf8cfd5894f2e9fbfe23643f3a24e2f2526a5bb88d058a0842fffcb339694b6704dc105a9d813327"
      }
    ],
    "ext": {
      "co-dian-debit-code": "3"
    }
  }
],

Documentation

Overview

Package co handles tax regime data for Colombia.

Index

• Constants
• func New() *tax.RegimeDef
• func Normalize(doc any)
• func Validate(doc interface{}) error

Constants

const (
	StampProviderDIANCUDE cbc.Key = "dian-cude"
	StampProviderDIANQR   cbc.Key = "dian-qr"
)

DIAN official codes to include in stamps.

const (
	KeyDIAN                    cbc.Key = "dian"
	KeyDIANCompanyID           cbc.Key = "dian-company-id"
	KeyDIANAdditionalAccountID cbc.Key = "dian-additional-account-id"
)

Special keys to use in meta data.

const (
	ExtKeyDIANMunicipality cbc.Key = "co-dian-municipality"
	ExtKeyDIANCreditCode   cbc.Key = "co-dian-credit-code"
	ExtKeyDIANDebitCode    cbc.Key = "co-dian-debit-code"
)

Extension keys used in Colombia.

const (
	IdentityKeyCivilRegister   cbc.Key = "co-civil-register"
	IdentityKeyIDCard          cbc.Key = "co-id-card"
	IdentityKeyCitizenID       cbc.Key = "co-citizen-id"
	IdentityKeyForeignerIDCard cbc.Key = "co-foreigner-id-card"
	IdentityKeyForeignerID     cbc.Key = "co-foreigner-id"
	IdentityKeyPassport        cbc.Key = "co-passport"
	IdentityKeyForeignID       cbc.Key = "co-foreign-id"
	IdentityKeyPEP             cbc.Key = "co-pep"
	IdentityKeyNUIP            cbc.Key = "co-nuip"
)

Known base tax identity types for Colombia

const (
	TaxCategoryIC        cbc.Code = "IC"  // Impuesto Consumo
	TaxCategoryICA       cbc.Code = "ICA" // Impuesto de Industria y Comercio
	TaxCategoryINC       cbc.Code = "INC"
	TaxCategoryReteIVA   cbc.Code = "RVAT" // ReteIVA
	TaxCategoryReteRenta cbc.Code = "RR"   // ReteRenta
	TaxCategoryReteICA   cbc.Code = "RICA" // ReteICA
)

Local tax categories.

const (
	TaxCodeFinalCustomer cbc.Code = "222222222222"
)

Known base tax identity types for Colombia

Functions

func New

func New() *tax.RegimeDef

New provides the tax region definition

func Normalize

func Normalize(doc any)

Normalize will attempt to clean the object passed to it.

func Validate

func Validate(doc interface{}) error

Validate checks the document type and determines if it can be validated.