API de Códigos Postales de México 🇲🇽

API RESTful ultra-rápida construida con Python 3.12, FastAPI, SQLite en modo WAL y Docker, diseñada para responder en < 1 ms con el catálogo oficial de Códigos Postales, Asentamientos, Municipios y Estados de México.

📜 Cláusula de Atribución Legal (Obligatoria por CC BY 4.0)

Esta API utiliza y procesa información geográfica y de códigos postales proveniente del catálogo oficial publicado por el Servicio Postal Mexicano (SEPOMEX) a través de datos.gob.mx bajo la licencia Creative Commons Attribution 4.0 International.

🚀 Características Principales

• Contrato de API y Especificación: docs/api_contract.md

• Velocidad y Desempeño: Tiempos de respuesta sub-milisegundo con SQLite en modo Write-Ahead Logging (WAL) y serialización orjson.

• Ciberseguridad: Hardening OWASP, headers de seguridad, Rate Limiting, validación estricta de regex Pydantic v2 y Docker non-root user.

• Manejo de Errores Enterprise: Formato RFC 7807 (Problem Details) con X-Correlation-ID único por petición.

• Auditoría & Logging: Logs en JSON estructurado mediante loguru con rotación diaria a medianoche (00:00), compresión .zip y retención de 30 días.

• Prevención de Deadlocks: Conexiones HTTP en modo solo lectura (mode=ro) con PRAGMA busy_timeout=5000;.

• Script de Ingesta Automático: Descarga, limpia (ISO-8859-1 a UTF-8) y puebla la base de datos de manera atómica.

📦 Instalación y Ejecución Local

1. Requisitos Previos

• Python 3.10+

• Virtualenv o Docker

2. Configurar entorno e instalar dependencias

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Ejecutar Ingesta de Datos (SEPOMEX / datos.gob.mx)

python scripts/ingest_sepomex.py

Este comando descargará el archivo CPdescarga.txt oficial y generará sepomex.db con más de 148,000 asentamientos e índices optimizados.

4. Iniciar Servidor de Desarrollo

uvicorn app.main:app --reload --port 8000

Visita la documentación interactiva en: http://localhost:8000/docs

🐳 Ejecución con Docker

Opción A: Docker Build & Run

docker build -t codigos-postales-api .
docker run -p 8000:8000 codigos-postales-api

Opción B: Docker Compose

docker-compose up -d

🔐 Autenticación & Rate Limiting (API Key & JWT)

La API cuenta con un esquema de autenticación híbrido configurable desde .env:

1. Modos de Operación (REQUIRE_AUTH)

• REQUIRE_AUTH=False (Modo API Pública, por defecto): Los endpoints son de acceso libre. El control de peticiones se realiza mediante Rate Limiting por IP (120 req/min por defecto).

• REQUIRE_AUTH=True (Modo API Protegida Empresarial): Requiere que cada petición envíe credenciales válidas en los headers.

2. Opciones de Autenticación Soportadas

1. Header X-API-Key:

   curl -H "X-API-Key: key-dev-12345" http://localhost:8000/api/v1/codigo-postal/01000

2. Token JWT Bearer (Authorization: Bearer <token>):

   • Canje de token JWT (válido por 24 horas):

     curl -X POST http://localhost:8000/api/v1/auth/token -H "X-API-Key: key-dev-12345"

   • Petición con el Token devuelto:

     curl -H "Authorization: Bearer <tu_jwt_token>" http://localhost:8000/api/v1/codigo-postal/01000

🛠️ Endpoints Disponibles

📦 Clientes SDK Oficiales (mx-postal-client)

El proyecto incluye dos paquetes clientes SDK livianos para consumir la API fácilmente sin escribir peticiones HTTP manuales:

• Python SDK (sdk/python):

  pip install ./sdk/python

  from mx_postal_client import MXPostalClient
  client = MXPostalClient(base_url="http://localhost:8080")
  cp_data = client.get_codigo_postal("01000", colonia="San Ángel")

• TypeScript / Node.js SDK (sdk/typescript):

  npm install ./sdk/typescript

  import { MXPostalClient } from 'mx-postal-client';
  const client = new MXPostalClient({ baseUrl: 'http://localhost:8080' });
  const detail = await client.getCodigoPostal('01000');

🤖 Integración con Agentes de IA (Model Context Protocol - MCP)

La API cuenta con un Servidor MCP oficial (scripts/mcp_server.py) que permite a Agentes de IA (Claude Desktop, ChatGPT, Antigravity IDE, LangChain, AutoGPT) consultar e interactuar con la base de datos geográfica oficial de México en lenguaje natural.

Herramientas Expuestas para IA:

1. consultar_codigo_postal(cp): Retorna la ficha geográfica completa y lista de colonias.

2. validar_direccion_postal(codigo_postal, colonia, estado, municipio): Valida en tiempo real la coincidencia de datos con SEPOMEX.

3. buscar_asentamientos_por_nombre(nombre_colonia, limite): Búsqueda en lenguaje natural por palabras clave.

Configuración en Claude Desktop / Antigravity IDE (mcp.json):

{
  "mcpServers": {
    "mx-postal-codes": {
      "command": "python3",
      "args": ["/ruta/absoluta/a/codigos-postales-api/scripts/mcp_server.py"]
    }
  }
}

🔄 Verificación Automática del Catálogo SEPOMEX

El contenedor ejecuta en segundo plano un planificador mensual asíncrono que comprueba la existencia de novedades en datos.gob.mx sin afectar la latencia HTTP (< 1 ms).

Para ejecutar manualmente la verificación o forzar la actualización del catálogo dentro del contenedor Docker:

docker exec codigos_postales_api python3 scripts/check_updates.py --force

🏆 Comparativa con el Estado del Arte (2026)

Comparativa técnica de nuestra solución en relación a las alternativas open-source y servicios comerciales SaaS del mercado actual:

🔬 Experimentos

El proyecto cuenta con una suite completa de pruebas de carga, geofencing GPS, normalización fiscal e interoperabilidad con Agentes de Inteligencia Artificial (MCP).

• Fase 1 (Latencia y Lote): Aceleración de 58.91x en validación en lote (POST /batch-validate).

• Fase 2 (Normalización SAT): $F_1$-Score algorítmico del 90.45% con 100% de precisión en dataset de 1,000 muestras con ruido.

• Fase 3 (Agentes IA / MCP): 99.43% de ahorro en tokens al interoperar vía el Servidor MCP.

🧪 Ejecutar Pruebas

pytest