🚀 Correos Tracking API & Bot

API REST y Bot de Telegram para el seguimiento automatizado de envíos de Correos España con notificaciones en tiempo real.

✨ Características

• 🚀 API REST: Endpoints para gestionar envíos programáticamente
• 📚 Documentación OpenAPI: Interfaz Swagger UI integrada
• 🤖 Bot de Telegram: Notificaciones y comandos interactivos
• 🔄 Monitorización Continua: Seguimiento automático de envíos
• 📱 Notificaciones: Alertas en tiempo real de cambios de estado
• 💾 Persistencia: Almacenamiento de datos entre reinicios
• 🔐 Configuración Segura: Variables de entorno separadas

📁 Estructura del Proyecto

proyecto/
├── api.py              # API FastAPI
├── config.py           # Configuración y constantes
├── correos_tracker.py  # Clase principal del tracker
├── requirements.txt    # Dependencias del proyecto
├── .gitignore         # Archivos a ignorar
└── README.md          # Documentación

🚀 Instalación

1. Clona el repositorio:

git clone https://github.com/yourusername/correos-track-api.git
cd correos-track-api

2. Instala las dependencias:

pip install -r requirements.txt

3. Configura las variables en config.py:

TELEGRAM_BOT_TOKEN = "TU_BOT_TOKEN"
TELEGRAM_CHAT_ID = "TU_CHAT_ID"

💻 Uso

Iniciar la API y el Bot:

python api.py

La API estará disponible en http://localhost:8000

Documentación API:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Endpoints API:

# Añadir envío
POST /shipments/
{
    "tracking_number": "PKAPBQ0714089710148130G"
}

# Listar envíos
GET /shipments/

# Obtener estado
GET /shipments/{tracking_number}

# Eliminar envío
DELETE /shipments/{tracking_number}

Comandos del Bot:

• /add NUMERO - Añade un envío
• /status NUMERO - Muestra el estado
• /list - Lista todos los envíos
• /remove NUMERO - Elimina un envío
• /help - Muestra la ayuda

🛠️ Tecnologías

• FastAPI - Framework web moderno
• Python Telegram Bot - API de Telegram
• Uvicorn - Servidor ASGI
• Pydantic - Validación de datos
• Requests - Cliente HTTP

📡 Ejemplos de API

Python

import requests

# Añadir envío
response = requests.post(
    "http://localhost:8000/shipments/",
    json={"tracking_number": "PKAPBQ0714089710148130G"}
)

cURL

# Añadir envío
curl -X POST "http://localhost:8000/shipments/" \
     -H "Content-Type: application/json" \
     -d '{"tracking_number":"PKAPBQ0714089710148130G"}'

📱 Capturas de pantalla

🤝 Contribuir

1. Fork el proyecto
2. Crea tu rama (git checkout -b feature/AmazingFeature)
3. Commit tus cambios (git commit -m 'Add: nueva característica')
4. Push a la rama (git push origin feature/AmazingFeature)
5. Abre un Pull Request

📝 Licencia

Distribuido bajo la Licencia MIT. Ver LICENSE para más información.

📧 Contacto

Link del Proyecto: https://github.com/vgvr0/correos-tracking-api