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.

The DIAN REST API is a FastAPI-based REST service for submitting electronic invoices, credit notes, and debit notes to Colombia’s DIAN tax authority via SOAP. All endpoints accept and return JSON. The API is built on FastAPI and exposes interactive, auto-generated documentation at /docs (Swagger UI) and /redoc (ReDoc) — no additional tooling required to explore the available operations.

​
Base URL

All requests are made to the host where the service is running. During local development the server binds on port 8000 by default: 
http://localhost:8000
Every business endpoint is scoped under the /api/v1 version prefix: 
http://localhost:8000/api/v1
The version prefix is defined directly on each APIRouter. The current router for dine-in orders uses prefix="/api/v1/pedidos/consumo-local", ensuring all future routers follow the same /api/v1/... convention.

​
Available Endpoints

GET /health

Health CheckReturns the current service status. Useful for load-balancer probes and uptime monitors. No request body required.Response:
{
  "status": "ok",
  "message": "API is running 🚀"
}

POST /api/v1/pedidos/consumo-local/

Facturar Pedido de Consumo LocalSubmits a dine-in restaurant order (consumo local) for DIAN electronic invoicing. Accepts a full POS order payload, validates it, builds the XML invoice, and dispatches it to the DIAN SOAP service.Tag: Facturación LocalReturns HTTP 201 Created on success.
Planned endpoints — The following routes follow the same /api/v1/pedidos/ pattern and are listed in the project vision as upcoming features:
MethodPathDescription
POST/api/v1/pedidos/domicilio/Submit a delivery order for DIAN invoicing
POST/api/v1/notas/credito/Issue a credit note (nota crédito) against an existing invoice
POST/api/v1/notas/debito/Issue a debit note (nota débito) against an existing invoice
These endpoints are not yet implemented. The DIAN adapter already includes a send_credit_note() stub that currently returns "Not implemented yet".

​
Response Format

All successful responses are JSON objects. The POST /api/v1/pedidos/consumo-local/ endpoint returns HTTP 201 Created with the following structure (defined by the PedidoLocalResponse Pydantic model): 
{
  "track_id": "<DIAN ZipKey>",
  "cufe": "<Código Único de Factura Electrónica>",
  "status": "Procesado Correctamente",
  "message": "Factura enviada correctamente a la DIAN"
}
FieldTypeDescription
track_idstringThe ZipKey returned by the DIAN SOAP service (SendTestSetAsync). Used to query the invoice status later.
cufestring | nullCódigo Único de Factura Electrónica. May be null in environments where the full XML signing pipeline is not yet active.
statusstringHuman-readable processing status, e.g. "Procesado Correctamente".
messagestringConfirmation message from the API.
The GET /health endpoint always returns HTTP 200 OK: 
{
  "status": "ok",
  "message": "API is running 🚀"
}

​
Error Responses

When the DIAN SOAP submission fails, the controller returns HTTP 500 Internal Server Error with a structured JSON body that wraps the raw adapter error: 
{
  "message": "Error enviando a la DIAN",
  "details": {
    "success": false,
    "error": "<error type>",
    "message": "<error description>"
  }
}
Example — DIAN connection timeout: 
{
  "message": "Error enviando a la DIAN",
  "details": {
    "success": false,
    "error": "Timeout",
    "message": "La DIAN tardó demasiado en responder."
  }
}
The details object maps directly to the dictionary returned by DianSoapAdapter.send_invoice(). The error field holds the Python exception class name (e.g. "TimeoutException", "ConnectionError"). HTTP status codes summary:
CodeMeaningWhen it occurs
200 OKSuccessGET /health
201 CreatedInvoice submittedPOST /api/v1/pedidos/consumo-local/ on DIAN success
422 Unprocessable EntityValidation failurePydantic rejects the request body (missing fields, wrong types, total_factura mismatch)
500 Internal Server ErrorDIAN submission failureDIAN SOAP call raises an exception (timeout, auth error, malformed XML)
The 422 response body is automatically generated by FastAPI and lists every field that failed validation, making it straightforward to debug malformed payloads during integration.

​
Interactive Documentation

FastAPI auto-generates fully interactive API documentation from the source code. No separate documentation deployment is needed during development.
InterfaceURLDescription
Swagger UIhttp://localhost:8000/docsTry requests directly in the browser. Includes example payloads for every field.
ReDochttp://localhost:8000/redocClean, readable reference layout. Best for sharing with stakeholders.
OpenAPI JSONhttp://localhost:8000/openapi.jsonRaw OpenAPI 3.x schema. Import into Postman, Insomnia, or any API client.
The FastAPI application is initialised with the following metadata in src/main.py:
app = FastAPI(
    title="DIAN REST API",
    description="API REST para el envío de facturas y notas a la DIAN",
    version="1.0.0",
)
This metadata is reflected in the Swagger UI title bar, the ReDoc header, and the info block of the OpenAPI JSON schema.

Build docs developers (and LLMs) love

Get started for freeTalk to us