> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoicing in Colombia

> Issue invoices, credit notes, and debit notes in Colombia through the DIAN.

export const WorkflowDiagram = ({workflow}) => {
  const stateColors = {
    processing: "yellow",
    sent: "blue",
    received: "blue",
    registered: "green",
    completed: "green",
    error: "red"
  };
  const StateChip = ({state, label}) => <Badge size="sm" color={stateColors[state] || "gray"} icon="square-small" iconType="solid">
      {label.charAt(0).toUpperCase() + label.slice(1)}
    </Badge>;
  const providerIcons = {
    "silo.state": "https://silo.invopop.com/images/status.svg",
    "silo.close": "https://silo.invopop.com/images/check-badge.svg",
    "silo.if": "https://assets.invopop.com/apps/silo/if.svg",
    "silo.folder": "https://silo.invopop.com/images/folder.svg",
    "silo.modify": "https://silo.invopop.com/images/modify.svg",
    "silo.correct": "https://silo.invopop.com/images/replace.svg",
    "silo.sleep": "https://assets.invopop.com/icons/sleep.svg",
    silo: "https://assets.invopop.com/apps/silo/icon.svg",
    "sequence.enumerate": "https://sequence.invopop.com/images/enumerate.svg",
    "transform.job.create": "https://transform.invopop.com/images/jobs.svg",
    webhook: "https://webhook.invopop.com/icon.svg",
    lookup: "magnifying-glass",
    dropbox: "https://dropbox.invopop.com/icon.png",
    pdf: "https://pdf.invopop.com/file-pdf.svg",
    peppol: "https://assets.invopop.com/apps/peppol/icon.svg",
    ubl: "https://assets.invopop.com/apps/ubl/logo.svg",
    cii: "https://assets.invopop.com/apps/cii/logo.svg",
    "gov-co": "https://assets.invopop.com/flags/co.svg",
    "gov-dk": "https://assets.invopop.com/flags/dk.svg",
    "gov-fi": "https://assets.invopop.com/flags/fi.svg",
    "gov-fr": "https://assets.invopop.com/flags/fr.svg",
    "chorus-pro": "https://assets.invopop.com/apps/chroruspro/icon.svg",
    "gov-es": "https://assets.invopop.com/apps/gov-es/icon.svg",
    "gov-es.sii": "https://assets.invopop.com/apps/sii/icon.svg",
    "gov-es.ticketbai": "https://assets.invopop.com/apps/ticketbai/icon.svg",
    "gov-es.facturae": "https://assets.invopop.com/apps/facturae/icon.svg",
    verifactu: "https://assets.invopop.com/apps/verifactu/icon.svg",
    "gov-pl": "https://assets.invopop.com/apps/ksef/icon.svg",
    "gov-sa": "https://assets.invopop.com/apps/zatca/icon.svg",
    "gov-ar": "https://assets.invopop.com/apps/arca/icon.svg",
    "at-pt": "https://assets.invopop.com/apps/at-pt/icon.svg",
    "sat-mx": "https://assets.invopop.com/apps/sat-mexico/icon.svg",
    "sw-sapien": "https://assets.invopop.com/apps/sw-sapien/icon.svg",
    "sdi-it": "https://assets.invopop.com/apps/sdi-italy/icon.svg",
    "ticket-it": "https://assets.invopop.com/apps/agenzia-entrate/icon.svg",
    "nfe-br": "https://assets.invopop.com/apps/notas-fiscais-eletronicas-brazil/icon.svg",
    chargebee: "https://assets.invopop.com/apps/chargebee/icon.svg",
    stripe: "https://assets.invopop.com/apps/stripe/icon.svg",
    email: "https://assets.invopop.com/apps/email/icon.svg",
    cron: "https://assets.invopop.com/apps/cron/icon.svg",
    tables: "https://assets.invopop.com/apps/tables/icon.svg",
    ilyda: "https://assets.invopop.com/apps/ilyda/icon.svg",
    invoicexpress: "https://assets.invopop.com/apps/invoicexpress/icon.svg"
  };
  const iconFor = provider => {
    const parts = (provider || "").split(".");
    for (let i = parts.length; i > 0; i--) {
      const url = providerIcons[parts.slice(0, i).join(".")];
      if (url) return url;
    }
    return null;
  };
  const StepIcon = ({provider}) => {
    const url = iconFor(provider);
    return <span title={provider} className="flex h-7 w-7 shrink-0 items-center justify-center rounded-md border border-gray-950/10 bg-white dark:border-white/10 dark:bg-white/5">
        {url && url.startsWith("http") ? <img src={url} alt="" className="h-4 w-4" /> : null}
        {url && !url.startsWith("http") ? <Icon icon={url} iconType="solid" size={14} /> : null}
      </span>;
  };
  const renderSummary = summary => {
    const nodes = [];
    const re = /`([^`]+)`(\{[^}]*\})?/g;
    let last = 0;
    let m;
    let k = 0;
    while ((m = re.exec(summary)) !== null) {
      if (m.index > last) nodes.push(summary.slice(last, m.index));
      const attrs = m[2] || "";
      if (attrs.indexOf(".state") >= 0) {
        const state = (attrs.match(/\.state\s+\.([\w-]+)/) || [])[1] || m[1];
        nodes.push(<StateChip key={k++} state={state} label={m[1]} />);
      } else if (attrs) {
        nodes.push(<span key={k++} className="text-sm font-medium text-gray-700 dark:text-gray-300">
            {m[1]}
          </span>);
      } else {
        nodes.push(<code key={k++} className="text-sm rounded bg-gray-100 px-1 font-mono text-sm dark:bg-white/10">
            {m[1]}
          </code>);
      }
      last = m.index + m[0].length;
    }
    if (last < summary.length) nodes.push(summary.slice(last));
    return nodes;
  };
  const NoteRow = ({text}) => <div className="mt-4 mb-1 font-mono text-sm leading-5 text-gray-400 dark:text-gray-500">{"// " + text}</div>;
  const renderSteps = (steps, counter) => (steps || []).map(step => {
    counter.n += 1;
    const n = counter.n;
    const branches = (step.next || []).filter(b => b.steps && b.steps.length > 0);
    return <div key={step.id || "step-" + n}>
          {step.notes ? <NoteRow text={step.notes} /> : null}
          <div className="mt-2.5 flex items-center">
            <span className="absolute left-0 w-10 text-center font-mono text-sm text-gray-400 select-none dark:text-gray-500">
              {n}
            </span>
            <div className="flex min-w-0 flex-1 items-center gap-2 rounded-xl border border-gray-950/5 bg-white px-2 py-2 dark:border-white/10 dark:bg-gray-900">
              <StepIcon provider={step.provider} />
              <span className="text-sm shrink-0 font-medium text-gray-900 dark:text-gray-100">{step.name}</span>
              {step.summary ? <span className="text-sm min-w-0 truncate text-gray-500 dark:text-gray-400">{renderSummary(step.summary)}</span> : null}
            </div>
          </div>
          {branches.length > 0 ? <div className="ml-5 border-l border-gray-200 -my-1 py-1 pl-6 dark:border-white/10">
              {branches.map((branch, bi) => <div key={branch.code || branch.status || bi}>
                  <div className="mt-4">
                    <span className="rounded-md bg-gray-200/70 px-2 py-1 font-mono text-sm text-gray-600 dark:bg-white/10 dark:text-gray-300">
                      {branch.code || branch.status}
                    </span>
                  </div>
                  {renderSteps(branch.steps, counter)}
                </div>)}
            </div> : null}
        </div>;
  });
  const counter = {
    n: 0
  };
  const wf = workflow || ({});
  return <div className="not-prose relative my-5 rounded-2xl border border-gray-950/5 bg-gray-50 py-3 pr-4 pb-5 pl-12 dark:border-white/10 dark:bg-white/[0.03]">
      {renderSteps(wf.steps, counter)}
      {wf.rescue && wf.rescue.length > 0 ? <div className="mt-6 border-t border-dashed border-gray-300 dark:border-white/10">
          <NoteRow text="If any step fails" />
          {renderSteps(wf.rescue, counter)}
        </div> : null}
    </div>;
};

export const coSendInvoiceWorkflow = {
  "name": "Colombia send invoice",
  "description": "Issue an invoice through the DIAN and generate a PDF",
  "schema": "bill/invoice",
  "steps": [{
    "id": "4ede1ca2-7550-4ca9-b007-ebef2bd58dac",
    "name": "Set state",
    "provider": "silo.state",
    "summary": "Set state to `processing`{.state .processing}",
    "config": {
      "state": "processing"
    }
  }, {
    "id": "1e35463c-2fb3-4157-a589-4afbafe5fc5b",
    "name": "Add sequential code",
    "provider": "sequence.enumerate",
    "summary": "Dynamic · DIAN · 1",
    "config": {
      "name": "Colombia",
      "padding": 1,
      "prefix": "",
      "start": 1
    }
  }, {
    "id": "ade3b20b-5d0c-4663-8907-b439f6e7baaa",
    "name": "Sign envelope",
    "provider": "silo.close"
  }, {
    "id": "20d33e51-2086-4507-a170-946168ba14af",
    "name": "Send to DIAN",
    "provider": "gov-co.send"
  }, {
    "id": "3cbd4b30-4259-46b4-9be1-ec7bad1d7cda",
    "name": "Generate PDF",
    "provider": "pdf",
    "summary": "Spanish · Letter",
    "config": {
      "date_format": "%Y-%m-%d",
      "layout": "Letter",
      "locale": "es",
      "logo_height": 40
    }
  }, {
    "id": "871259a3-85f0-4066-b7cc-655f383ec66d",
    "name": "Set state",
    "provider": "silo.state",
    "summary": "Set state to `sent`{.state .sent}",
    "config": {
      "state": "sent"
    }
  }],
  "rescue": [{
    "id": "58582217-f8c2-4b5f-8b1f-576b0680ad84",
    "name": "Set state",
    "provider": "silo.state",
    "summary": "Set state to `error`{.state .error}",
    "config": {
      "state": "error"
    }
  }]
};

## Introduction

The [DIAN](https://www.dian.gov.co/) 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](https://www.alegra.com), 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](https://docs.gobl.org) documents through the DIAN. For onboarding suppliers, see the companion guide: [Supplier registration in Colombia](/guides/co-dian-registration).

| - | Sandbox | Live |
| - | - | - |
| **Supplier** | Only Alegra's test NIT (`9005590882`) | Registered supplier required |
| **Series** | `SETP` with codes `990000000`–`995000000` (shared range) | Series from the supplier's DIAN numbering resolutions |

Please refer to the docs of the [GOBL Colombia tax regime](https://docs.gobl.org/regimes/co) and the [DIAN add-on](https://docs.gobl.org/addons/co-dian-v2) 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](/guides/co-dian-registration) 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, address, and municipality code for Colombian customers.
* 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:

| Type | DIAN identifier | Requirements |
| - | - | - |
| `standard` invoice | CUFE | Series and code within an active numbering resolution |
| `credit-note` | CUDE | References the corrected invoice in `preceding`; the correction concept comes from the [`co-dian-credit-code`](https://docs.gobl.org/addons/co-dian-v2) extension. When the preceding entry carries no `dian-cude` stamp, the note is cleared as a *nota crédito sin referencia* |
| `debit-note` | CUDE | Every `preceding` entry must carry the `dian-cude` stamp of the original invoice; the concept comes from the `co-dian-debit-code` extension |

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

<Info>
  The supplier must already be registered and enabled with the DIAN. This is covered in the [supplier registration guide](/guides/co-dian-registration).
</Info>

<Steps>
  <Step title="Create the send workflow">
    <Card iconType="duotone" title="Colombia send invoice workflow" icon="code-branch" href="https://console.invopop.com/redirect/workflows/new?template=co-send-invoice" horizontal>
      Add to my workspace →
    </Card>

    <Tabs>
      <Tab title="Workflow">
        <WorkflowDiagram workflow={coSendInvoiceWorkflow} />
      </Tab>

      <Tab title="Code">
        Copy and paste into a new [Empty Invoice workflow](https://console.invopop.com/redirect/workflows/new?template=empty-invoice) code view.

        ```json Colombia send invoice workflow theme={"system"}
        {
            "name": "Colombia send invoice",
            "description": "Issue an invoice through the DIAN and generate a PDF",
            "schema": "bill/invoice",
            "steps": [
                {
                    "id": "4ede1ca2-7550-4ca9-b007-ebef2bd58dac",
                    "name": "Set state",
                    "provider": "silo.state",
                    "summary": "Set state to `processing`{.state .processing}",
                    "config": {
                        "state": "processing"
                    }
                },
                {
                    "id": "1e35463c-2fb3-4157-a589-4afbafe5fc5b",
                    "name": "Add sequential code",
                    "provider": "sequence.enumerate",
                    "summary": "Dynamic · DIAN · 1",
                    "config": {
                        "name": "Colombia",
                        "padding": 1,
                        "prefix": "",
                        "start": 1
                    }
                },
                {
                    "id": "ade3b20b-5d0c-4663-8907-b439f6e7baaa",
                    "name": "Sign envelope",
                    "provider": "silo.close"
                },
                {
                    "id": "20d33e51-2086-4507-a170-946168ba14af",
                    "name": "Send to DIAN",
                    "provider": "gov-co.send"
                },
                {
                    "id": "3cbd4b30-4259-46b4-9be1-ec7bad1d7cda",
                    "name": "Generate PDF",
                    "provider": "pdf",
                    "summary": "Spanish · Letter",
                    "config": {
                        "date_format": "%Y-%m-%d",
                        "layout": "Letter",
                        "locale": "es",
                        "logo_height": 40
                    }
                },
                {
                    "id": "871259a3-85f0-4066-b7cc-655f383ec66d",
                    "name": "Set state",
                    "provider": "silo.state",
                    "summary": "Set state to `sent`{.state .sent}",
                    "config": {
                        "state": "sent"
                    }
                }
            ],
            "rescue": [
                {
                    "id": "58582217-f8c2-4b5f-8b1f-576b0680ad84",
                    "name": "Set state",
                    "provider": "silo.state",
                    "summary": "Set state to `error`{.state .error}",
                    "config": {
                        "state": "error"
                    }
                }
            ]
        }
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

<Note>
  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](/console/series) with a matching start number and select it in the step instead.
</Note>

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](https://console.invopop.com) or via the API.

<Info>
  The recommended approach for running jobs is to perform two steps: first upload the document to the [silo](/api-ref/silo/entries/create-an-entry-put), then [create a job](/api-ref/transform/jobs/create-a-job-post).
</Info>

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](https://docs.gobl.org/addons/co-dian-v2) 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.
* 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](https://docs.gobl.org/regimes/co).
* 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.

## Example invoices

The following examples are of [GOBL](https://docs.gobl.org) documents you can copy and paste directly into the [Invopop Console](https://console.invopop.com) or store via the API as silo entries. Then, you must run the Colombia workflow created during setup.

[GOBL Invoices](https://docs.gobl.org/draft-0/bill/invoice) 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`
* `supplier.tax_id.country` to be set to `CO`
* `supplier.ext` to include the DIAN municipality code under the [`co-dian-municipality`](https://docs.gobl.org/addons/co-dian-v2) extension. Colombian customers need it too.

<Info>
  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.
</Info>

<AccordionGroup>
  <Accordion title="Example B2B invoice">
    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`](https://docs.gobl.org/draft-0/bill/invoice),
    * 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,
    * 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.

    <CodeGroup>
      ```json Colombia B2B invoice theme={"system"}
      {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "series": "SETP",
        "code": "990001001",
        "issue_date": "2026-10-13",
        "currency": "COP",
        "supplier": {
          "name": "EXAMPLE SUPPLIER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9005590882"
          },
          "addresses": [
            {
              "street": "CRA 15 88 64 OF 502",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "customer": {
          "name": "EXAMPLE CUSTOMER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9014514805"
          },
          "addresses": [
            {
              "street": "CRA 8 113 31 OF 703",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "emails": [
            {
              "addr": "benito.ortiz@example.com"
            }
          ],
          "telephones": [
            {
              "num": "3114131811"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "lines": [
          {
            "quantity": "1",
            "item": {
              "name": "Servicios de consultoría",
              "price": "200000.00"
            },
            "taxes": [
              {
                "cat": "VAT",
                "percent": "19%"
              }
            ]
          }
        ],
        "payment": {
          "terms": {
            "due_dates": [
              {
                "date": "2026-11-12",
                "percent": "100%"
              }
            ]
          }
        }
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "CO",
      	"type": "standard",
      	"series": "SETP",
      	"code": "990001001",
      	"issue_date": "2026-10-13",
      	"currency": "COP",
      	"supplier": {
      		"name": "EXAMPLE SUPPLIER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9005590882",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 15 88 64 OF 502",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"customer": {
      		"name": "EXAMPLE CUSTOMER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9014514805",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 8 113 31 OF 703",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"emails": [
      			{
      				"addr": "benito.ortiz@example.com"
      			}
      		],
      		"telephones": [
      			{
      				"num": "3114131811"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"lines": [
      		{
      			"i": 1,
      			"quantity": "1",
      			"item": {
      				"name": "Servicios de consultoría",
      				"price": "200000.00"
      			},
      			"sum": "200000.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"percent": "19%"
      				}
      			],
      			"total": "200000.00"
      		}
      	],
      	"payment": {
      		"terms": {
      			"due_dates": [
      				{
      					"date": "2026-11-12",
      					"amount": "238000.00",
      					"percent": "100%"
      				}
      			]
      		}
      	},
      	"totals": {
      		"sum": "200000.00",
      		"total": "200000.00",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"base": "200000.00",
      							"percent": "19%",
      							"amount": "38000.00"
      						}
      					],
      					"amount": "38000.00"
      				}
      			],
      			"sum": "38000.00"
      		},
      		"tax": "38000.00",
      		"total_with_tax": "238000.00",
      		"payable": "238000.00"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Example B2C invoice">
    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*,
    * 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.

    <CodeGroup>
      ```json Colombia B2C invoice theme={"system"}
      {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "series": "SETP",
        "code": "990001002",
        "issue_date": "2026-10-13",
        "currency": "COP",
        "tax": {
          "tags": [
            "simplified"
          ]
        },
        "supplier": {
          "name": "EXAMPLE SUPPLIER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9005590882"
          },
          "addresses": [
            {
              "street": "CRA 15 88 64 OF 502",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "lines": [
          {
            "quantity": "1",
            "item": {
              "name": "Servicios de consultoría",
              "price": "200000.00"
            },
            "taxes": [
              {
                "cat": "VAT",
                "percent": "19%"
              }
            ]
          }
        ],
        "payment": {
          "advances": [
            {
              "description": "Prepaid",
              "percent": "100%"
            }
          ]
        }
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "CO",
      	"$tags": [
      		"simplified"
      	],
      	"type": "standard",
      	"series": "SETP",
      	"code": "990001002",
      	"issue_date": "2026-10-13",
      	"currency": "COP",
      	"tax": {},
      	"supplier": {
      		"name": "EXAMPLE SUPPLIER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9005590882",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 15 88 64 OF 502",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"lines": [
      		{
      			"i": 1,
      			"quantity": "1",
      			"item": {
      				"name": "Servicios de consultoría",
      				"price": "200000.00"
      			},
      			"sum": "200000.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"percent": "19%"
      				}
      			],
      			"total": "200000.00"
      		}
      	],
      	"payment": {
      		"advances": [
      			{
      				"description": "Prepaid",
      				"percent": "100%",
      				"amount": "238000.00"
      			}
      		]
      	},
      	"totals": {
      		"sum": "200000.00",
      		"total": "200000.00",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"base": "200000.00",
      							"percent": "19%",
      							"amount": "38000.00"
      						}
      					],
      					"amount": "38000.00"
      				}
      			],
      			"sum": "38000.00"
      		},
      		"tax": "38000.00",
      		"total_with_tax": "238000.00",
      		"payable": "238000.00",
      		"advance": "238000.00",
      		"due": "0.00"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Example credit note">
    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`](https://docs.gobl.org/addons/co-dian-v2) 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.

    <CodeGroup>
      ```json Colombia credit note theme={"system"}
      {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "type": "credit-note",
        "series": "NCTP",
        "code": "1",
        "issue_date": "2026-10-13",
        "currency": "COP",
        "preceding": [
          {
            "type": "standard",
            "series": "SETP",
            "code": "990001001",
            "issue_date": "2026-10-13",
            "reason": "Servicios no prestados",
            "ext": {
              "co-dian-credit-code": "1"
            }
          }
        ],
        "supplier": {
          "name": "EXAMPLE SUPPLIER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9005590882"
          },
          "addresses": [
            {
              "street": "CRA 15 88 64 OF 502",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "customer": {
          "name": "EXAMPLE CUSTOMER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9014514805"
          },
          "addresses": [
            {
              "street": "CRA 8 113 31 OF 703",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "emails": [
            {
              "addr": "benito.ortiz@example.com"
            }
          ],
          "telephones": [
            {
              "num": "3114131811"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "lines": [
          {
            "quantity": "1",
            "item": {
              "name": "Servicios de consultoría",
              "price": "200000.00"
            },
            "taxes": [
              {
                "cat": "VAT",
                "percent": "19%"
              }
            ]
          }
        ]
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "CO",
      	"type": "credit-note",
      	"series": "NCTP",
      	"code": "1",
      	"issue_date": "2026-10-13",
      	"currency": "COP",
      	"preceding": [
      		{
      			"type": "standard",
      			"issue_date": "2026-10-13",
      			"series": "SETP",
      			"code": "990001001",
      			"reason": "Servicios no prestados",
      			"ext": {
      				"co-dian-credit-code": "1"
      			}
      		}
      	],
      	"supplier": {
      		"name": "EXAMPLE SUPPLIER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9005590882",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 15 88 64 OF 502",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"customer": {
      		"name": "EXAMPLE CUSTOMER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9014514805",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 8 113 31 OF 703",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"emails": [
      			{
      				"addr": "benito.ortiz@example.com"
      			}
      		],
      		"telephones": [
      			{
      				"num": "3114131811"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"lines": [
      		{
      			"i": 1,
      			"quantity": "1",
      			"item": {
      				"name": "Servicios de consultoría",
      				"price": "200000.00"
      			},
      			"sum": "200000.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"percent": "19%"
      				}
      			],
      			"total": "200000.00"
      		}
      	],
      	"totals": {
      		"sum": "200000.00",
      		"total": "200000.00",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"base": "200000.00",
      							"percent": "19%",
      							"amount": "38000.00"
      						}
      					],
      					"amount": "38000.00"
      				}
      			],
      			"sum": "38000.00"
      		},
      		"tax": "38000.00",
      		"total_with_tax": "238000.00",
      		"payable": "238000.00"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Example debit note">
    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`](https://docs.gobl.org/addons/co-dian-v2) 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.

    <CodeGroup>
      ```json Colombia debit note theme={"system"}
      {
        "$schema": "https://gobl.org/draft-0/bill/invoice",
        "type": "debit-note",
        "series": "NDTP",
        "code": "1",
        "issue_date": "2026-10-13",
        "currency": "COP",
        "preceding": [
          {
            "type": "standard",
            "series": "SETP",
            "code": "990001001",
            "issue_date": "2026-10-13",
            "reason": "Ajuste del valor de los servicios",
            "stamps": [
              {
                "prv": "dian-cude",
                "val": "3f8c1c9b6e0a4f2d8b7a5c3e1d9f0a2b4c6e8d0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8"
              }
            ],
            "ext": {
              "co-dian-debit-code": "3"
            }
          }
        ],
        "supplier": {
          "name": "EXAMPLE SUPPLIER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9005590882"
          },
          "addresses": [
            {
              "street": "CRA 15 88 64 OF 502",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "customer": {
          "name": "EXAMPLE CUSTOMER S.A.S.",
          "tax_id": {
            "country": "CO",
            "type": "tin",
            "code": "9014514805"
          },
          "addresses": [
            {
              "street": "CRA 8 113 31 OF 703",
              "locality": "Bogotá, D.C.",
              "region": "Bogotá",
              "country": "CO"
            }
          ],
          "emails": [
            {
              "addr": "benito.ortiz@example.com"
            }
          ],
          "telephones": [
            {
              "num": "3114131811"
            }
          ],
          "ext": {
            "co-dian-municipality": "11001"
          }
        },
        "lines": [
          {
            "quantity": "1",
            "item": {
              "name": "Ajuste de precio de los servicios de consultoría",
              "price": "50000.00"
            },
            "taxes": [
              {
                "cat": "VAT",
                "percent": "19%"
              }
            ]
          }
        ]
      }
      ```

      ```json Built version theme={"system"}
      {
      	"$schema": "https://gobl.org/draft-0/bill/invoice",
      	"$regime": "CO",
      	"type": "debit-note",
      	"series": "NDTP",
      	"code": "1",
      	"issue_date": "2026-10-13",
      	"currency": "COP",
      	"preceding": [
      		{
      			"type": "standard",
      			"issue_date": "2026-10-13",
      			"series": "SETP",
      			"code": "990001001",
      			"reason": "Ajuste del valor de los servicios",
      			"stamps": [
      				{
      					"prv": "dian-cude",
      					"val": "3f8c1c9b6e0a4f2d8b7a5c3e1d9f0a2b4c6e8d0f1a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0c2d4e6f8a0b2c4d6e8"
      				}
      			],
      			"ext": {
      				"co-dian-debit-code": "3"
      			}
      		}
      	],
      	"supplier": {
      		"name": "EXAMPLE SUPPLIER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9005590882",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 15 88 64 OF 502",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"customer": {
      		"name": "EXAMPLE CUSTOMER S.A.S.",
      		"tax_id": {
      			"country": "CO",
      			"code": "9014514805",
      			"type": "tin"
      		},
      		"addresses": [
      			{
      				"street": "CRA 8 113 31 OF 703",
      				"locality": "Bogotá, D.C.",
      				"region": "Bogotá",
      				"country": "CO"
      			}
      		],
      		"emails": [
      			{
      				"addr": "benito.ortiz@example.com"
      			}
      		],
      		"telephones": [
      			{
      				"num": "3114131811"
      			}
      		],
      		"ext": {
      			"co-dian-municipality": "11001"
      		}
      	},
      	"lines": [
      		{
      			"i": 1,
      			"quantity": "1",
      			"item": {
      				"name": "Ajuste de precio de los servicios de consultoría",
      				"price": "50000.00"
      			},
      			"sum": "50000.00",
      			"taxes": [
      				{
      					"cat": "VAT",
      					"key": "standard",
      					"percent": "19%"
      				}
      			],
      			"total": "50000.00"
      		}
      	],
      	"totals": {
      		"sum": "50000.00",
      		"total": "50000.00",
      		"taxes": {
      			"categories": [
      				{
      					"code": "VAT",
      					"rates": [
      						{
      							"key": "standard",
      							"base": "50000.00",
      							"percent": "19%",
      							"amount": "9500.00"
      						}
      					],
      					"amount": "9500.00"
      				}
      			],
      			"sum": "9500.00"
      		},
      		"tax": "9500.00",
      		"total_with_tax": "59500.00",
      		"payable": "59500.00"
      	}
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="My GOBL document for a Colombian invoice fails to build because of the postal code">
    The DIAN expects a 5-digit [municipal code](https://www.dian.gov.co/atencionciudadano/formulariosinstructivos/Formularios/2007/Codigos_municipios_2007.pdf), not a 6-digit postal code, in the supplier's [`co-dian-municipality`](https://docs.gobl.org/addons/co-dian-v2) extension.
  </Accordion>

  <Accordion title="How does Invopop issue invoices in Colombia?">
    Through [Alegra](https://www.alegra.com), an authorized DIAN technology provider. The [send workflow](/guides/co-dian-invoicing) signs the GOBL envelope, clears it with the DIAN, stamps the CUFE and QR code, and generates a compliant PDF.
  </Accordion>

  <Accordion title="What does a GOBL invoice need to be accepted by the DIAN?">
    Set `$schema` to `https://gobl.org/draft-0/bill/invoice`, the supplier's `tax_id.country` to `CO`, and include the supplier's and customer's DIAN municipality codes via the [`co-dian-municipality`](https://docs.gobl.org/addons/co-dian-v2) extension in each party's `ext`. See the [GOBL Colombia tax regime](https://github.com/invopop/gobl/blob/main/regimes/co/README.md) for the full field reference and examples.
  </Accordion>

  <Accordion title="Which taxes can appear on a Colombian invoice?">
    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](https://docs.gobl.org/regimes/co#tax-categories).
  </Accordion>

  <Accordion title="Which document types can I issue in Colombia?">
    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.
  </Accordion>

  <Accordion title="What are the sandbox limitations for Colombia?">
    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.
  </Accordion>

  <Accordion title="Why was my invoice rejected for its series or number?">
    The series, code, and issue date must fall within an active DIAN numbering resolution. Resolutions are refreshed automatically, so a rejection usually means it expired or ran out and the supplier needs a new one from the DIAN.
  </Accordion>
</AccordionGroup>

More available in our [Colombia FAQ](/faq/colombia) section

***

<AccordionGroup>
  <Accordion title="🇨🇴 Invopop resources for Colombia">
    | | |
    | - | - |
    | Compliance | <Icon icon="https://assets.invopop.com/flags/co.svg" /> [Invoicing compliance in Colombia](/compliance/colombia)<br /> <Icon icon="timeline" /> [Compliance timeline](/timelines/colombia) |
    | Apps | <Icon icon="https://assets.invopop.com/flags/co.svg" /> [Colombia](/apps/colombia) |
    | Guides | <Icon icon="book" /> [Supplier registration](/guides/co-dian-registration)<br /> <Icon icon="book" /> [Issuing invoices](/guides/co-dian-invoicing) |
    | FAQ | <Icon icon="square-question" /> [Colombia FAQ](/faq/colombia) |
    | GOBL | <Icon icon="https://assets.invopop.com/icons/gobl.svg" />  [Colombia Tax Regime](https://docs.gobl.org/regimes/co)<br /> <Icon icon="https://assets.invopop.com/icons/gobl.svg" /> [Colombia DIAN Addon](https://docs.gobl.org/addons/co-dian-v2) |
  </Accordion>
</AccordionGroup>

<Card title="Participate in our community" icon="forumbee" href="https://community.invopop.com" arrow="true" horizontal>
  Ask and answer questions about invoicing in Colombia →
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.