Supplier registration in Colombia

Introduction

The DIAN is the Colombian government agency responsible for managing and overseeing tax collection, customs operations, and facilitating international trade. Before issuing electronic invoices, a business must be registered with the DIAN with an active RUT (Registro Único Tributario), pass the DIAN enablement (habilitación) with its chosen technology provider, and hold an authorized numbering range for its invoices. Invopop has partnered with Alegra, a DIAN-authorized technology provider, to onboard suppliers and issue documents on their behalf. Registering a supplier involves three steps:

Invopop: a workflow creates the supplier’s Alegra account and publishes a portal link.
DIAN: the supplier selects Alegra as their technology provider and submits the enablement test set through that portal.
Numbering (live only): the supplier links their authorized numbering range to Alegra in the DIAN portal.

Once a supplier is registered, continue with the companion guide: Invoicing in Colombia.

The previous Plemsi integration is deprecated and no longer maintained. If your suppliers still issue through Plemsi, follow Migrate from Plemsi to move them to this integration.

-	Sandbox	Live
Supplier	Only Alegra’s test NIT (`9005590882`)	Any Colombian supplier with an active RUT
Enablement	Simulated with fixed TestSetIds	DIAN enablement, once per supplier
Resolution	Fixed test resolution (`SETP`), seeded automatically	The supplier’s numbering ranges linked to Alegra

Prerequisites

To register a supplier in Colombia, you will need:

Supplier details to build the GOBL party: legal name, NIT with the verification digit, and email. The address and the co-dian-municipality extension are optional here but required on invoices.
The supplier’s legal representative, with access to the DIAN e-invoicing portal, to select Alegra and run the enablement.
For live issuing, a numbering range authorization (resolución de numeración) from the DIAN for each invoice series. See Numbering resolutions.

Colombia supplier

The name, NIT with the verification digit, and an email address are required for registration. The example also includes the address and the co-dian-municipality extension identifying where the supplier is registered, and uses Alegra’s sandbox NIT so it can be registered in the sandbox.

Colombia supplier example

{
    "$schema": "https://gobl.org/draft-0/org/party",
    "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"
        }
    ],
    "emails": [
        {
            "addr": "facturacion@examplesupplier.co"
        }
    ],
    "ext": {
        "co-dian-municipality": "11001"
    }
}

If the supplier has special tax obligations, set them with the co-dian-fiscal-responsibility extension: O-13 Gran contribuyente, O-15 Autorretenedor, O-23 Agente de retención IVA, or O-47 Régimen simple de tributación. It defaults to R-99-PN when none apply.

Setup

All of the following steps must be carried out from the Invopop Console.

Connect the Colombia app

Navigate to Configuration → Apps
Find Colombia in the app discovery list
Click Connect to activate

Create the registration workflow

Colombia register supplier workflow

Add to my workspace →

Workflow
Code

Copy and paste into a new Empty Party workflow code view.

Colombia register supplier workflow

{
    "name": "Colombia register supplier",
    "description": "Register a supplier with the DIAN through Alegra",
    "schema": "org/party",
    "steps": [
        {
            "id": "9cb7f64d-95df-414d-9945-b204a1993d4b",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `processing`{.state .processing}",
            "config": {
                "state": "processing"
            }
        },
        {
            "id": "19ad51e4-7277-4ce7-909d-30bd6aeca68d",
            "name": "Register supplier",
            "provider": "gov-co.register"
        },
        {
            "id": "8b9fd00a-fa37-466f-9c89-c44a4a680d39",
            "name": "Wait for DIAN enablement",
            "provider": "gov-co.wait.enablement"
        },
        {
            "id": "0f69cd97-bbc3-46e6-bd53-7ccd44945107",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `registered`{.state .registered}",
            "config": {
                "state": "registered"
            }
        }
    ],
    "rescue": [
        {
            "id": "65de083c-5053-4f87-b269-fc2028cd74f8",
            "name": "Set state",
            "provider": "silo.state",
            "summary": "Set state to `error`{.state .error}",
            "config": {
                "state": "error"
            }
        }
    ]
}

How it works

Set state → Processing

Sets the state of the silo entry to Processing.

Validates the party’s name, NIT, and email, creates the supplier’s company in Alegra, and publishes a public enablement portal link under the registration-link key in the entry’s meta section.

Wait for DIAN enablement

Pauses until the DIAN accepts the enablement test set the supplier submits from the portal. The step resumes automatically as soon as the DIAN responds.

Set state → Registered

Sets the state of the silo entry to Registered.

Register a supplier

Each supplier NIT can be registered once per workspace and environment. For each supplier:

Upload the supplier party

Create a silo entry with the supplier’s details as a GOBL org.Party document, either from the Console or via the API:

Colombia supplier example

{
    "$schema": "https://gobl.org/draft-0/org/party",
    "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"
        }
    ],
    "emails": [
        {
            "addr": "facturacion@examplesupplier.co"
        }
    ],
    "ext": {
        "co-dian-municipality": "11001"
    }
}

Run the registration workflow

Run the workflow created during setup on the supplier entry, from the Console or by creating a job. The job creates the Alegra company and pauses at the Wait for DIAN enablement step.

Share the portal link

Open the supplier entry in the Console and copy the registration-link from its meta section. Share it with the supplier’s legal representative: it is public and needs no Invopop account.Via the API, fetch the silo entry and read the link_url of the meta row with the key registration-link:

{
  "meta": [
    {
      "key": "registration-link",
      "link_scope": "public",
      "link_url": "https://gov-co.invopop.app/portal/{silo_entry_id}"
    }
  ]
}

To skip the portal entirely, submit the TestSetId yourself as described in Complete the enablement via the API.

Select Alegra as technology provider at the DIAN

In the DIAN Habilitación portal, the legal representative:

Goes to Registro y habilitación → Documentos electrónicos → Factura electrónica.
Selects Software de un proveedor tecnológico as the operation mode.
Selects Soluciones Alegra S.A.S as the provider and Alegra’s software, then clicks Asociar.
Opens the test set details and copies the TestSetId.

The DIAN explains these screens in sections 1 and 2 of Registration and operation mode selection.

Submit the test set

The legal representative pastes the TestSetId into the Invopop portal and clicks Enviar set de pruebas. Alegra sends the required test documents to the DIAN automatically.

Enablement portal with the DIAN TestSetId field and the Enviar set de pruebas button — Enablement portal

To submit the TestSetId without the hosted portal, use the Submit test set endpoint.

Wait for the DIAN response

The portal refreshes while the DIAN processes the test set. Once accepted, the workflow resumes and the entry moves to the registered state. If the DIAN rejects the test set, the workflow fails with the DIAN’s error details; fix the cause and re-run the registration workflow to start again.

Re-running the registration workflow on the same entry is safe: it restarts the enablement if it hasn’t been accepted yet, and does nothing once the supplier is enabled.

Numbering resolutions

In live, every invoice series needs a DIAN numbering range authorization linked to Alegra. This isn’t needed in the sandbox, which uses the fixed SETP test resolution.

Request the numbering range

The legal representative requests the range in the DIAN’s MUISCA system (Numeración de Facturación → Solicitar numeración de facturación → Autorizar Rango), choosing a prefix of up to four letters or digits, which becomes the invoice series. Once signed, the DIAN issues form 1876 with the authorized ranges and validity. See Request for invoice numbering authorization.

Link the range to Alegra

Once the DIAN has accepted the test set, and about two hours after the range request, log in to the production environment through Facturando Electrónicamente. Go to Configuración → Rangos de numeración, select Alegra’s software (Soluciones Alegra S.A.S) and the authorized range, and click Agregar. If the operation mode doesn’t show in production, use Sincronizar a Producción in the test set details of the Habilitación portal. The DIAN explains this in sections 3 and 4 of Registration and operation mode selection.

Invopop fetches the supplier’s linked resolutions automatically before sending, so no further action is needed. Check them anytime with List resolutions. To extend a range that is about to expire with numbers left, see Request for invoice numbering extension; once a range is used up, request a new one.

Complete the enablement via the API

For platforms that want to drive the enablement programmatically instead of sharing the hosted portal, use the enablement API (both endpoints under /apps/gov-co/v1/entries/{silo_entry_id}/enablement). The entry must belong to the authenticated workspace and have been registered first.

Submit the test set

Submit test set with the TestSetId from the DIAN enablement portal. It responds 400 when a test set is already awaiting the DIAN outcome, the supplier is already enabled, or a previous enablement failed. Run the registration workflow again to restart a failed enablement.

Track the outcome

Fetch the enablement status: status moves from pending to accepted or failed once the DIAN responds. The workflow’s Wait for DIAN enablement step picks up the outcome exactly as it does for portal submissions.

Sandbox

The same registration flow runs in sandbox workspaces against the DIAN test environment, with a few differences:

Only Alegra’s own NIT (9005590882) can be registered, since the DIAN test registry accepts documents from that emitter alone. A NIT can be registered once per workspace, so each workspace has a single sandbox supplier.
The fixed DIAN test resolution (series SETP, codes 990000000–995000000) is seeded automatically on registration. The range is shared with other users testing in the sandbox, so pick codes unlikely to collide.
The enablement is simulated: instead of a real DIAN TestSetId, enter one of the following values in the portal to choose the outcome.

TestSetId	Simulated result
`a70562e0-631e-4ceb-aa65-36887b57dc17`	Accepted (completes the registration)
`r70562e0-631e-4ceb-aa65-36887b57dc17`	Rejected
`p70562e0-631e-4ceb-aa65-36887b57dc17`	Processing (stays pending)
`f70562e0-631e-4ceb-aa65-36887b57dc17`	Failed

Use the accepted value to complete a supplier registration end to end; the other values let you test how your integration handles rejected, pending, and failed outcomes.

Migrate from Plemsi

Moving a supplier from the old Plemsi integration takes the same steps as a new registration. At the DIAN, the supplier simply adds Alegra as another technology provider.

Set up the Colombia app

Connect the app and create the registration workflow as described in Setup, and the send workflow from the invoicing guide.

Follow Register a supplier: run the registration workflow, add Alegra as technology provider at the DIAN, and submit the test set. The Plemsi enablement doesn’t carry over, so this is needed even for suppliers already issuing.

Set up the numbering ranges

Under Configuración → Rangos de numeración (see Numbering resolutions), choose one of:

Move the existing range: unlink it from Plemsi and link it to Alegra. The series stays the same, and new invoices must continue after the last number issued through Plemsi.
Add a new range: request a new range with a new prefix and link it to Alegra. Invoices sent through Alegra start a fresh series, while the old range stays with Plemsi until it’s no longer needed.

Switch to the new send workflow

Send new invoices with the Colombia send workflow, using the series from the previous step. Once they clear, stop using the Plemsi workflow.

At this point, you’re ready to start sending invoices on behalf of the supplier. Head over to the Invoicing in Colombia guide to continue.

FAQ

What does a supplier need before issuing invoices in Colombia?

The supplier must be registered with the DIAN with an active RUT (Registro Único Tributario), complete the DIAN habilitación, and hold a valid billing numbering range authorization. The supplier registration guide walks through each step.

How do I register a supplier in Colombia?

Upload a GOBL party with the supplier’s name, NIT (with verification digit), and email, then run the registration workflow. It publishes an enablement portal link under registration-link in the entry’s meta; the supplier’s legal representative completes the DIAN enablement there, and the workflow finishes once the DIAN accepts it. See the supplier registration guide.

What is the DIAN habilitación?

A one-time DIAN certification required before issuing real invoices. The supplier submits a TestSetId from the DIAN portal through the hosted portal, Alegra sends the test documents, and the supplier is enabled once the DIAN accepts them.

Do I need to register suppliers in the sandbox?

Yes, but only Alegra’s NIT (9005590882) can be registered. The enablement is simulated: enter the TestSetId a70562e0-631e-4ceb-aa65-36887b57dc17 for an instant acceptance. Other outcomes are in the sandbox section of the guide.

Does the billing numbering range authorization expire?

Yes, both by number limit and by date. Before a range with unused numbers expires, the supplier can extend it (extension request); once it’s used up, they request a new one (new authorization). Updated resolutions are picked up automatically.

More available in our Colombia FAQ section

🇨🇴 Invopop resources for Colombia


Compliance	Invoicing compliance in Colombia Compliance timeline
Apps	Colombia
Guides	Supplier registration Issuing invoices
FAQ	Colombia FAQ
GOBL	Colombia Tax Regime Colombia DIAN Addon

Participate in our community

Ask and answer questions about invoicing in Colombia →

Networks

Countries

Set-up

GOBL

Apps

API

Features

Supplier registration in Colombia

Introduction

Prerequisites

Setup

Colombia register supplier workflow

How it works

Register a supplier

Numbering resolutions

Complete the enablement via the API

Sandbox

Migrate from Plemsi

FAQ

Participate in our community

​Introduction

​Prerequisites

​Setup

Colombia register supplier workflow

​How it works

​Register a supplier

​Numbering resolutions

​Complete the enablement via the API

​Sandbox

​Migrate from Plemsi

​FAQ

Participate in our community

Introduction

Prerequisites

Setup

How it works

Register a supplier

Numbering resolutions

Complete the enablement via the API

Sandbox

Migrate from Plemsi

FAQ