Supplier registration in Colombia

​

Introduction

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

​

Prerequisites

• 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 the supplier’s invoices (see When is the municipality code required?).
• The supplier’s legal representative, with access to the email on their own RUT (the DIAN’s Habilitación portal sends its login links there) and, for numbering, a MUISCA account with a DIAN electronic signature.
• For live issuing, a numbering range authorization (resolución de numeración) from the DIAN for each invoice series. See Numbering resolutions.

{
    "$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"
    }
}

​

Setup

{
    "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

​

Register a supplier

1

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"
    }
}

2

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.

3

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.

4

Register as electronic invoicer at the DIAN

The legal representative opens the DIAN’s Habilitación portal (also linked from dian.gov.co under Factura Electrónica) and logs in as Empresa (or Persona for individuals). The DIAN emails an access link, valid for 60 minutes, to the address on the RUT of the person logging in, the legal representative for companies.

The first time they open Registro y habilitación → Documentos electrónicos, the Registrar facturador screen appears: they enter the Correo electrónico para recepción de facturas and click Registrar. They then log out and log back in with a new access link before continuing.

5

Select Alegra as technology provider at the DIAN

Back in the Habilitación portal, the legal representative:

1. Goes to Registro y habilitación → Documentos electrónicos → Factura electrónica and clicks Configurar modos de operación.

2. Under Seleccione el modo de operación, picks Software de un proveedor tecnológico.
3. Under Datos de empresa y software, sets Nombre empresa proveedora to Soluciones Alegra S.A.S and Nombre del software to Alegra’s software from the list, then clicks Asociar.

4. Under Listado de modos de operación asociados, clicks the eye icon in Acciones. If asked for a Tipo de documento, they choose Factura electrónica and click Set de pruebas. They copy the TestSetId shown in the ¡Importante! banner.

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

6

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, signed with its own digital certificate, so the supplier doesn’t need one.

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

7

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. The DIAN then asks the supplier for their production start date, when their RUT is updated with responsibility 52 (Facturador electrónico). If the DIAN rejects the test set, the workflow fails and the DIAN’s reason is recorded in the job’s faults; see Failed enablement for where to read it and how to start again.

​

Numbering resolutions

1

Request the numbering range

In the DIAN’s MUISCA system (Usuario Registrado on dian.gov.co), under Numeración de Facturación → Solicitar numeración de facturación, the legal representative:

1. Checks that the RUT is up to date (name, address, invoicing responsibility, and establishments).
2. Clicks Autorizar Rangos and fills in Prefijo (up to four letters or digits, which becomes the invoice series), Tipo Facturación set to FACTURA ELECTRÓNICA DE VENTA, and Rango Desde / Rango Hasta, then clicks Agregar.
3. Signs the request with their DIAN electronic signature (firma electrónica), first as form 1302 and then as form 1876, which the DIAN issues with the authorized ranges and validity.

See Request for invoice numbering authorization.

2

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, pick Soluciones Alegra S.A.S under Proveedor - Software and the range under Prefijo, and click Agregar.

If production shows Empresa no se encuentra habilitada, or Alegra’s operation mode doesn’t appear there, click Sincronizar Contribuyente a producción on the Facturador electrónico page of the Habilitación portal:

The DIAN explains this in sections 3 and 4 of Registration and operation mode selection.

​

Renew a range

1

Open the range

In MUISCA, under Numeración de Facturación → Solicitar numeración de facturación, the legal representative clicks Habilitar Rangos.

2

Request the extension

They enter the same Prefijo and Tipo Facturación, click Consultar, review the range shown (editing Rango Desde if prompted), and click Borrador.

3

Sign it

They sign form 1302 and then form 1876, which carries the new validity.

​

Contingency range

​

Complete the enablement via the API

​

Failed enablement

• The Console: open the supplier entry and check its job history.
• The API: fetch the job and read its faults array. Prefer the job’s faults over the faults field on the silo entry.
• A webhook: with a Send Webhook step in the error handling flow, the payload includes the same faults.

1. Fix the cause, for example by correcting the supplier details in the entry or getting a new TestSetId from the DIAN portal.
2. Re-run the registration workflow on the same entry. Until you do, Submit test set responds 400.
3. Submit the test set again, from the portal or via the API.

​

Sandbox

• 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.

​

Migrate from Plemsi

​

FAQ

🇨🇴 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