Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/farojas85/fast-rest-api/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through everything needed to run DIAN REST API locally and send your first electronic invoice to DIAN’s habilitación (testing) environment. By the end you will have a running FastAPI server, a validated PFX certificate loaded on startup, and a confirmed SOAP round-trip to DIAN’s testing service.
1

Prerequisites

Before you begin, make sure you have the following:
  • Python 3.14 or later — required by pyproject.toml.
  • uv package manager — used exclusively for dependency management and virtual environments. Install it with:
curl -LsSf https://astral.sh/uv/install.sh | sh
  • A valid DIAN .pfx digital certificate — issued during the DIAN software registration process. This file is required for XML signing and SOAP authentication. Keep the file path and password handy.
  • DIAN habilitación credentials — provided by DIAN when you register your billing software:
    • TestSetId — identifies your test set during habilitación.
    • SoftwareID — the UUID of your registered billing software.
    • SoftwarePIN — the PIN associated with your software registration.
2

Clone and install

Clone the repository and install all dependencies in one command. uv sync reads pyproject.toml, creates an isolated virtual environment, and installs every dependency — no manual pip install needed.
git clone https://github.com/farojas85/fast-rest-api.git
cd fast-rest-api
uv sync
To also install the development dependencies (pytest, ruff):
uv sync --group dev
3

Configure environment

Copy the provided example file to create your local .env:
cp .env.example .env
Open .env and fill in your real values. The file contains the following variables:
DIAN_CERT_PATH=/ruta/absoluta/al/certificado.pfx
DIAN_CERT_PASSWORD=password_segura
DIAN_TEST_SET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DIAN_SOFTWARE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
DIAN_SOFTWARE_PIN=12345
ENVIRONMENT=local
DIAN_WSDL_URL_HABILITACION=https://vpfe-hab.dian.gov.co/WcfDianCustomerServices.mac/WcfDianCustomerServices.svc?wsdl
DIAN_WSDL_URL_PRODUCCION=https://vpfe.dian.gov.co/WcfDianCustomerServices.mac/WcfDianCustomerServices.svc?wsdl
VariableDescription
DIAN_CERT_PATHAbsolute path to your .pfx certificate file on disk.
DIAN_CERT_PASSWORDPassword for the .pfx certificate. Stored as a SecretStr — never logged.
DIAN_TEST_SET_IDTest Set ID provided by DIAN during the habilitación process.
DIAN_SOFTWARE_IDUUID of your billing software registered with DIAN.
DIAN_SOFTWARE_PINPIN for your registered DIAN software.
ENVIRONMENTRuntime environment. Any value other than production routes requests to the habilitación WSDL.
DIAN_WSDL_URL_HABILITACIONWSDL endpoint for DIAN’s testing service.
DIAN_WSDL_URL_PRODUCCIONWSDL endpoint for DIAN’s live production service.
4

Start the server

Start the FastAPI development server with hot-reload enabled:
uvicorn src.main:app --reload
On startup, Pydantic Settings loads every variable from .env and immediately attempts to open and decrypt your PFX certificate. If the file is missing, unreadable, or the password is wrong, the process exits with an error before accepting any requests — this fast-fail behavior prevents the server from running in a broken state.Once the server is up, verify it is healthy:
curl http://localhost:8000/health
Expected response:
{
  "status": "ok",
  "message": "API is running 🚀"
}
The interactive Swagger UI is available at http://localhost:8000/docs as soon as the server starts. You can explore all endpoints, view request/response schemas, and send test requests directly from your browser — no extra tooling required.
5

Send your first invoice

Submit a local consumption order (consumo local) to the invoicing endpoint. The example below uses the same payload values as the project’s test suite:
curl -X POST http://localhost:8000/api/v1/pedidos/consumo-local/ \
  -H "Content-Type: application/json" \
  -d '{
    "id_pedido_origen": "POS-100",
    "items": [
      {
        "id_producto": "B-01",
        "descripcion": "Cerveza Artesanal",
        "cantidad": 2,
        "precio_unitario": 10000.00,
        "impuestos": [
          {
            "nombre": "INC",
            "tasa": 0.08,
            "monto": 1600.00
          }
        ],
        "total_item": 21600.00
      }
    ],
    "subtotal": 20000.00,
    "propina_voluntaria": 3000.00,
    "impuestos_totales": 1600.00,
    "total_factura": 24600.00,
    "metodos_pago": [
      {
        "tipo": "Efectivo",
        "monto": 24600.00
      }
    ]
  }'
On success, the API returns HTTP 201 Created with a DIAN tracking response:
{
  "track_id": "ABC-123",
  "cufe": null,
  "status": "SUCCESS",
  "message": "Factura enviada correctamente a la DIAN"
}
Use the track_id value to query DIAN’s portal and confirm the document was received and accepted.
ENVIRONMENT=local routes all requests to the DIAN habilitación (testing) WSDL. This environment is safe for development and testing. Never set ENVIRONMENT=production unless you have completed DIAN’s official production enablement process (habilitación en producción) and are ready to emit legally binding fiscal documents.

Build docs developers (and LLMs) love

Get started for freeTalk to us