使用说明

API SICETAC

Esta API expone el cálculo de costos operativos bajo la metodología SICETAC y lo vuelve consumible para sistemas, integraciones y agentes.

Su foco no es solo responder una consulta puntual. Su foco es permitir que una empresa conecte comercial, operación, finanzas y asistentes internos a una misma base de referencia.

Documentación

Qué incluye hoy

API HTTP con FastAPI
Resumen y detalle de cálculo SICETAC
Detalle de peajes por ruta y configuración
Resolución por nombre o código DANE
Respuesta compacta para agentes y WhatsApp
Servidor MCP para herramientas agentic
Generación de snapshot consolidado a Excel

Endpoints principales

POST /consulta
POST /consulta_resumen
POST /consulta_texto
GET /peajes/detalle
POST /refresh
POST /snapshot/generate
GET /health

Contrato comercial versionado:

GET /v1/health
POST /v1/quotes
POST /v1/prequotes
POST /v1/feedback/terms
GET /v1/catalog/body-types
GET /v1/catalog/vehicles
GET /v1/catalog/municipalities
GET /v1/usage

Consulta la documentación de la API comercial para API keys, cuotas, auditoría y puesta en producción.

Arranque rápido

Instalación:

pip install -r requirements.txt

Ejecución local:

uvicorn main:app --reload

Health check:

curl http://localhost:8000/health

Consulta rápida:

curl -X POST http://localhost:8000/consulta \
  -H "Content-Type: application/json" \
  -d '{
        "origen": "Bogotá",
        "destino": "Medellín",
        "vehiculo": "C3S3",
        "mes": 202504,
        "resumen": true
      }'

Para comparar H4 y H8 contra diciembre de 2025, agrega "modo_aumento": true. El cliente debe reenviar ese indicador mientras el modo esté activo y enviarlo como false cuando el usuario indique “modo aumento off”.

Consulta rápida con detalle de peajes:

curl -X POST http://localhost:8000/consulta \
  -H "Content-Type: application/json" \
  -d '{
        "origen": "Bogotá",
        "destino": "Barranquilla",
        "vehiculo": "C3S3",
        "resumen": true,
        "peajes": true
      }'

Variables mínimas de entorno

SUPABASE_URL
SUPABASE_SERVICE_ROLE_KEY o SUPABASE_KEY

Variables útiles:

CORS_ORIGINS
SICETAC_API_ACCESS_MODE (api_key es el valor seguro por defecto; public sólo se admite si se declara de forma explícita para una demo aislada)
SICETAC_API_KEYS_JSON o SICETAC_API_CONSUMERS_DB
SICETAC_USAGE_PERSISTENCE
SICETAC_ADMIN_TOKEN para /refresh y /snapshot/generate
SICETAC_CACHE_TTL_SECONDS
SICETAC_TABLE_MUNICIPIOS
SICETAC_TABLE_VEHICULOS
SICETAC_TABLE_PARAMETROS
SICETAC_TABLE_COSTOS_FIJOS
SICETAC_TABLE_VALOR_PLAZA_PUERTOS (por defecto valor_en_plaza_puertos_desagregada; lectura interna con service_role)
SICETAC_TABLE_PEAJES
SICETAC_TABLE_PEAJES_DETALLE
SICETAC_TABLE_PEAJES_RESUMEN
SICETAC_TABLE_PEAJES_INVENTARIO
SICETAC_TABLE_RUTAS
SICETAC_TABLE_SICETAC_VACIO (por defecto sicetac_vacio_vigentes)

Cuando modo_viaje=VACIO, la API consulta la tabla oficial vigente por ruta, configuración y carrocería. Este modo representa un vehículo sin carga; un contenedor vacío transportado sigue siendo una operación CARGADO.

Para un portacontenedores, declara tipo_contenedor como CARGADO o VACIO. La segunda opción usa la serie SICETAC oficial de contenedor vacío y no aplica valor en plaza. Para un viaje redondo usa viaje_redondo: true: la API calcula la ida cargada, invierte la ruta y calcula el regreso con contenedor vacío. Cuando una dirección tiene variantes SICETAC, la respuesta solicita rutasid_ida y rutasid_regreso para que el consumidor seleccione cada ruta.

{
  "origen": "Bogotá",
  "destino": "Medellín",
  "vehiculo": "C3S3",
  "carroceria": "Portacontenedores",
  "modo_viaje": "CARGADO",
  "viaje_redondo": true,
  "tipo_contenedor": "CARGADO",
  "tipo_contenedor_regreso": "VACIO",
  "resumen": true
}

Agentes

Para conectar un tercero, usa commercial_mcp_server.py: expone catálogos, consumo y cotización mediante la API comercial con la clave del cliente. Instala requirements-client.txt y sigue la guía de conexión. Este puente usa MCP por stdio y HTTPS hacia ATIEMPPO; no requiere acceso a la base de datos.

Los ejemplos siguientes conservan la integración legacy.

Cliente Node de ejemplo:

SICETAC_API_URL="https://sicetac-api-mcp.onrender.com" node agent_client.js "Bogotá" "Barranquilla"

Servidor MCP:

python mcp_server.py

Tool principal:

calcular_sicetac_tool

Licencia y uso

Esta API fue desarrollada por IMETRICA para análisis y simulación de costos de transporte terrestre en Colombia, integrando fuentes oficiales y datos de operación real.