Skip to main content

​
Introduction

The DIAN in Colombia stands for Dirección de Impuestos y Aduanas Nacionales (National Directorate of Taxes and Customs). It is the government agency responsible for managing and overseeing tax collection, customs operations, and facilitating international trade. Electronic invoicing in Colombia is mandatory and operates on a real-time clearance model whereby every invoice must receive a unique identifier called a CUFE (Código Único de Factura Electrónica) issued by the DIAN; credit and debit notes receive the equivalent CUDE. Invopop has partnered with Alegra, an authorized technology provider for DIAN electronic invoicing, to issue documents in Colombia. This guide walks you through setting up the workflow that issues GOBL documents through the DIAN. For onboarding suppliers, see the companion guide: Supplier registration in Colombia. Please refer to the docs of the GOBL Colombia tax regime and the DIAN add-on to learn about the specifics of Colombian GOBL documents.

​
Prerequisites

In order to complete this guide, you will need:
  • A registered supplier: follow the supplier registration guide to create the supplier’s Alegra account and complete the DIAN enablement before issuing.
  • Customer details for B2B transactions, including name, NIT or international ID, and address, plus the DIAN municipality code for customers identified by a Colombian NIT (see When is the municipality code required?).
  • Line and item details, including quantity, price, description, and taxes to apply. Colombia can be complicated, as a single invoice may need to apply up to three different value added and retained taxes.

​
Document types

The same workflow handles all three DIAN document types: Cleared invoices can’t be cancelled or edited; correct them with a credit or debit note. Only invoices need a numbering resolution, so notes can use any series.

​
Setup

The supplier must already be registered and enabled with the DIAN. This is covered in the supplier registration guide.
1

Create the send workflow

Colombia send invoice workflow

Add to my workspace →
The Add sequential code step uses a dynamic sequence: each document series gets its own counter, starting at 1. Invoice codes must fall within the series’ numbering resolution, so if the authorized range starts elsewhere (the sandbox SETP range starts at 990000000), create a series with a matching start number and select it in the step instead.
Setup is complete. You can now use the workflow you created to issue invoices, credit notes, and debit notes in Colombia.

​
Send an invoice

Upload the invoice as a silo entry and run the workflow on it, either from the Invopop Console or via the API.
The recommended approach for running jobs is to perform two steps: first upload the document to the silo, then create a job.
On success, the workflow:
  • adds the dian-cude stamp to the envelope, holding the CUFE (invoices) or CUDE (credit and debit notes),
  • adds the dian-qr stamp with the DIAN QR code content, used by the PDF step to render a compliant invoice,
  • adds the dian-resolution stamp with the numbering resolution (invoices only) and the email-subject stamp with the subject the DIAN expects on the email notification, and,
  • attaches the signed DIAN XML (AttachedDocument) to the entry as a file.
While the DIAN hasn’t responded, the job stays queued and is checked again every 15 minutes. If the DIAN rejects the document, the job fails with the DIAN’s error details.

​
Validation notes

Before sending, the document is validated against the DIAN add-on rules plus a few DIAN transmission requirements:
  • The issue date must be the current date in Colombia: the DIAN rejects back-dated documents.
  • The code must contain digits only; letters belong in the series.
  • For invoices, the series must match one of the supplier’s numbering resolutions, and the code must be within the authorized range and validity dates. Resolutions are refreshed from the DIAN automatically once the range is linked to Alegra.
  • Every tax combo must include a percent; you can set percents explicitly or use one of the supported rates of the GOBL Colombia tax regime.
  • All line items must have a price greater than zero, and due dates cannot be earlier than the issue date.
  • Totals rounding (totals.rounding) isn’t supported.
  • Amounts in other currencies are converted to COP automatically. Invoices in a currency other than COP must include exchange_rates with a rate to COP, or the conversion fails.

​
When is the municipality code required?

The co-dian-municipality extension in a party’s ext identifies its municipality. Whether a party needs it depends on how it’s identified:
  • The value is the 5-digit DIAN municipality code (DIVIPOLA), such as 11001 for Bogotá or 05001 for Medellín, not the 6-digit postal code. See the DIAN list of municipality codes.
  • When a required code is missing, the GOBL build fails with extension 'co-dian-municipality' is required on $.supplier.ext or $.customer.ext, so the invoice never reaches the DIAN.
  • Invopop can’t derive the code from the NIT, so collect it with the rest of your customer data for each Colombian business customer, for example in your customer form. Foreign and consumer customers don’t need the field.

​
Transmitting invoices issued during a contingency

The DIAN defines what to do when invoices can’t be issued electronically in Resolución 000165 de 2023. The required action depends on where the outage is:

​
While offline: issue on paper

During the outage, invoices are issued by hand or printed from any other system (facturas de talonario o de papel). These paper invoices:
  • Must be numbered from a contingency range, which the supplier needs to request from the DIAN ahead of time.
  • Can only be issued while the outage lasts, and are valid support for the sale for both the supplier and the customer.

​
Once back online: transmit the invoices

Within 48 hours of the outage ending, each paper invoice must be captured and sent to the DIAN through Invopop.
Before sending, the supplier’s contingency resolution must be uploaded to Invopop. Invopop rejects contingency invoices without one, and in production the DIAN rejects those whose number isn’t within it.
  1. Create a GOBL invoice replicating the paper invoice, with the same customer, lines, and taxes, and with these specifics:
    • The series and code are the paper invoice’s contingency prefix and number.
    • The issue_date is the date the paper invoice was issued.
    • The co-dian-invoice-type extension in tax.ext is set to 03.
    This partial example shows only the contingency-specific fields. Complete the document with the supplier, customer, and lines copied from the paper invoice.
  2. Run your regular send workflow on the document. It’s sent to the DIAN as a type 03 invoice and gets the same stamps as a regular invoice, with a CUDE instead of a CUFE.
Keep in mind:
  • Credit and debit notes have no contingency procedure: wait until the systems are back and issue them with your usual note series. They can correct a transmitted contingency invoice like any other invoice.
  • Outages on the DIAN’s side (type 04 contingency) are handled by Invopop and need no changes to your documents.
  • In sandbox, upload a contingency resolution with any values first, such as prefix CONT and range 1–5000. The DIAN test environment doesn’t check contingency ranges, but Invopop still checks the invoice’s code and date against the uploaded resolution.

​
Example invoices

The following examples are of GOBL documents you can copy and paste directly into the Invopop Console or store via the API as silo entries. Then, you must run the Colombia workflow created during setup. GOBL Invoices sent to the DIAN require the following properties to perform the correct normalization and validation steps:
  • $schema to be set to https://gobl.org/draft-0/bill/invoice
  • $addons to include co-dian-v2, so the document is validated with the DIAN rules
  • supplier.tax_id.country to be set to CO
  • supplier.ext to include the DIAN municipality code under the co-dian-municipality extension. Customers identified by a Colombian NIT need it too; foreign and simplified B2C customers don’t. See When is the municipality code required?.
The examples are ready for the sandbox: they use Alegra’s NIT 9005590882 and the SETP test series. Before sending, set the issue date to today and change the code to another one between 990000000 and 995000000, since the range is shared.
In this example, we’re issuing a B2B invoice from a Colombian supplier to another Colombian business customer.Notice:
  • the $schema is set to https://gobl.org/draft-0/bill/invoice,
  • we’ve added the co-dian-v2 addon, so the document is validated with the DIAN rules built into GOBL and gets its defaults, such as the R-99-PN fiscal responsibility,
  • the supplier uses Alegra’s sandbox NIT and the series is the SETP test series, so the example can be sent in the sandbox,
  • both parties carry the DIAN municipality code in the co-dian-municipality extension, required here because the customer is identified by a Colombian NIT,
  • the invoice includes VAT at the standard Colombian rate of 19%,
  • payment terms are specified with a due date and payment amount, and,
  • there are no calculations in some fields; these will be made automatically when uploading.
In this example, we’re issuing a B2C simplified invoice from a Colombian supplier to a consumer.Notice:
  • we’ve set the simplified tag in the tax.tags field; this indicates the invoice is for a final consumer,
  • the customer information is omitted, as it’s not required for B2C transactions; the DIAN receives it as Consumidor final, and no customer municipality code is needed,
  • the invoice includes a prepayment advance of 100%, meaning the invoice has been fully paid,
  • the totals section shows the advance and due amounts, with the latter being zero since the invoice is fully paid, and,
  • there are no calculations in some fields; these will be made automatically when uploading.
In this example, we’re issuing a credit note (nota de crédito) that corrects a previously issued invoice.Notice:
  • the type is set to credit-note,
  • the series is set to a dedicated credit note series, separate from the invoice series,
  • the preceding array references the original invoice being corrected by its series, code, and issue_date, along with a reason for the correction,
  • the correction concept is set with the co-dian-credit-code extension on the preceding entry,
  • the lines describe the amounts being credited — a credit note can cover the full original invoice or just part of it, and,
  • there are no calculations in some fields; these will be made automatically when uploading.
In this example, we’re issuing a debit note (nota de débito) that increases the amount of a previously cleared invoice.Notice:
  • the type is set to debit-note,
  • the series is set to a dedicated debit note series, separate from the invoice series; notes don’t need a numbering resolution,
  • the preceding array references the original invoice by its series, code, and issue_date, along with a reason for the adjustment,
  • the preceding entry carries the dian-cude stamp of the original invoice, taken from its cleared envelope; the DIAN requires it for every debit note,
  • the adjustment concept is set with the co-dian-debit-code extension on the preceding entry,
  • the lines describe only the additional amount being charged, and,
  • there are no calculations in some fields; these will be made automatically when uploading.

​
FAQ

The DIAN expects a 5-digit municipal code, not a 6-digit postal code, in the co-dian-municipality extension of the supplier and of customers identified by a Colombian NIT. For example, use 11001 for Bogotá.
Through Alegra, an authorized DIAN technology provider. The send workflow signs the GOBL envelope, clears it with the DIAN, stamps the CUFE and QR code, and generates a compliant PDF.
Set $schema to https://gobl.org/draft-0/bill/invoice, the supplier’s tax_id.country to CO, and include the supplier’s DIAN municipality code via the co-dian-municipality extension in its ext. Customers identified by a Colombian NIT need the extension too; foreign customers and simplified B2C invoices don’t (see When is the municipality code required?). See the GOBL Colombia tax regime for the full field reference and examples.
No. The co-dian-municipality extension is only required on customers identified by a Colombian NIT, that is, with tax_id.country set to CO and a tax_id.code. Foreign customers, simplified B2C invoices without a customer, and consumers identified only by a cédula build without it. Invopop can’t derive the code from the NIT, so collect it for each Colombian business customer.
VAT (IVA, 19% standard or 5% reduced), consumption taxes (IC, INC), the industry and commerce tax (ICA), and the retained taxes ReteIVA, ReteICA, and Retefuente. A single invoice may need to combine up to three value added and retained taxes, all supported by the GOBL Colombia tax regime.
Invoices, credit notes, and debit notes. Credit and debit notes reference the corrected invoice in the preceding array; debit notes require every preceding entry to carry the dian-cude stamp of the original invoice.
Only Alegra’s NIT (9005590882) can be the supplier. Invoices use series SETP with codes 990000000–995000000 (shared across users, so avoid common codes) and today’s date in Colombia.
The series, code, and issue date must fall within an active DIAN numbering resolution. Resolutions are refreshed automatically, so a rejection usually means the range isn’t linked to Alegra yet, or it expired or ran out and the supplier needs a new one. See Numbering resolutions.
More available in our Colombia FAQ section

Participate in our community

Ask and answer questions about invoicing in Colombia →