API Documentation - Eventos Cerveceros Colombia

Inicio Rápido

🚀 Sin Autenticación

Todas nuestras APIs son públicas y no requieren autenticación ni API keys.

📊 Formato JSON

Todas las respuestas están en formato JSON con estructura consistente.

🔄 Rate Limiting

Límites de velocidad generosos para uso responsable de las APIs.

🌐 CORS Enabled

Headers CORS configurados para permitir peticiones desde cualquier origen.

Ejemplo de uso básico

curl -X GET "https://eventos-cerveceros-colombia.com/api/eventos.json"

fetch('https://eventos-cerveceros-colombia.com/api/eventos.json')
  .then(response => response.json())
  .then(data => console.log(data.eventos));

Endpoints Disponibles

Eventos

GET

/api/eventos.json

Obtiene todos los eventos cerveceros próximos publicados

Rate Limit: 100 solicitudes por 1 hora

Cache: 5 minutos

Estructura de respuesta

                    {
  "eventos": [
    {
      "id": "string",
      "name": "string",
      "date": "string (YYYY-MM-DD)",
      "time": "string (HH:MM:SS)",
      "brewery": "string",
      "location": "string",
      "city": "string",
      "price": "number | null",
      "description": "string | null",
      "category": "string | null",
      "created_at": "string (ISO)",
      "updated_at": "string (ISO)"
    }
  ],
  "count": "number",
  "last_updated": "string (ISO)"
}

Ejemplo de respuesta

                    {
  "eventos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Tap Takeover IPA Session",
      "date": "2025-09-15",
      "time": "18:30:00",
      "brewery": "Cervecería Artesanal",
      "location": "Calle 10 #15-25, El Poblado",
      "city": "Medellín",
      "price": 35000,
      "description": "Degustación de 5 IPAs especiales",
      "category": "tap-takeover",
      "created_at": "2025-09-04T10:30:00.000Z",
      "updated_at": "2025-09-04T10:30:00.000Z"
    }
  ],
  "count": 1,
  "last_updated": "2025-09-04T15:45:00.000Z"
}

Códigos de error

500 Error interno del servidor o base de datos

429 Demasiadas solicitudes (rate limit excedido)

Probar endpoint →

Cervecerías

GET

/api/cervecerías.json

Obtiene todas las cervecerías verificadas en la plataforma

Rate Limit: 100 solicitudes por 1 hora

Cache: 10 minutos

Estructura de respuesta

                    {
  "cervecerías": [
    {
      "id": "string",
      "name": "string",
      "verified": "boolean",
      "approved_events": "number | null",
      "instagram": "string | null",
      "website": "string | null",
      "created_at": "string (ISO)",
      "updated_at": "string (ISO)"
    }
  ],
  "count": "number",
  "last_updated": "string (ISO)"
}

Ejemplo de respuesta

                    {
  "cervecerías": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Cervecería Artesanal",
      "verified": true,
      "approved_events": 15,
      "instagram": "@cerveceriaartesanal",
      "website": "https://cerveceriaartesanal.com",
      "created_at": "2025-08-15T09:00:00.000Z",
      "updated_at": "2025-09-01T12:00:00.000Z"
    }
  ],
  "count": 1,
  "last_updated": "2025-09-04T15:45:00.000Z"
}

Códigos de error

500 Error interno del servidor o base de datos

Probar endpoint →

Búsqueda

GET

/api/search.json

Busca eventos por diferentes criterios

Rate Limit: 200 solicitudes por 1 hora

Cache: 2 minutos

Parámetros de consulta

Parámetro	Tipo	Requerido	Descripción
`q`	string	No	Término de búsqueda en nombre, descripción o cervecería
`city`	string	No	Filtrar por ciudad específica
`category`	string	No	Filtrar por categoría de evento
`brewery`	string	No	Filtrar por nombre de cervecería
`date_from`	string	No	Fecha mínima (YYYY-MM-DD)
`date_to`	string	No	Fecha máxima (YYYY-MM-DD)
`limit`	number	No	Número máximo de resultados (1-100, default: 50)

Estructura de respuesta

                    {
  "eventos": "Array<Event>",
  "count": "number",
  "total_matches": "number",
  "query": "object",
  "last_updated": "string (ISO)"
}

Ejemplo de respuesta

                    {
  "eventos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Festival Cervecero Medellín",
      "date": "2025-09-20",
      "time": "14:00:00",
      "brewery": "Múltiples",
      "location": "Parque Explora",
      "city": "Medellín",
      "price": 25000,
      "description": "Gran festival con 20+ cervecerías",
      "category": "festival"
    }
  ],
  "count": 1,
  "total_matches": 1,
  "query": {
    "q": "festival",
    "city": "Medellín",
    "limit": 50
  },
  "last_updated": "2025-09-04T15:45:00.000Z"
}

Códigos de error

400 Parámetros de búsqueda inválidos

500 Error interno del servidor

429 Demasiadas solicitudes (rate limit excedido)

Probar endpoint →

Guías de Uso

🎯 Mejores Prácticas

Implementa cache en tu aplicación para reducir solicitudes
Maneja errores de red y respuestas 5xx apropiadamente
Respeta los rate limits para evitar bloqueos temporales
Usa parámetros de búsqueda para filtrar datos específicos

⚠️ Limitaciones

Solo eventos futuros son retornados por defecto
Máximo 100 resultados por solicitud en búsquedas
Los datos se actualizan en tiempo real
No hay soporte para webhooks actualmente

📈 Uso Responsable

No hagas polling excesivo - usa cache apropiadamente
Implementa backoff exponencial en reintentos
Considera usar SSE o polling inteligente
Respeta la propiedad intelectual de los datos

🔧 Soporte Técnico

Reporta bugs o problemas vía Telegram
Documentación siempre actualizada en esta página
Cambios breaking se anuncian con anticipación
Status de API disponible en headers de respuesta

Librerías y Herramientas

Nuestras APIs REST son compatibles con cualquier lenguaje de programación. Aquí algunos ejemplos de uso en diferentes tecnologías:

JavaScript / Node.js

const response = await fetch('/api/eventos.json');
const result = await response.json();
console.log(`${result.count} eventos encontrados`);

Python

import requests

response = requests.get('https://eventos-cerveceros-colombia.com/api/eventos.json')
result = response.json()
print(f"${result['count']} eventos encontrados")

PHP

$response = file_get_contents('https://eventos-cerveceros-colombia.com/api/eventos.json');
$data = json_decode($response, true);
echo $data['count'] . " eventos encontrados";

curl

curl -H "Accept: application/json" \
  "https://eventos-cerveceros-colombia.com/api/search.json?city=Medellín&limit=10"