{"openapi":"3.0.3","info":{"title":"Marketing Calendar Intelligence API","version":"1.0.0","description":"API REST para consultar oportunidades comerciales basadas en eventos, fechas, industrias, ubicación y ventanas de campaña."},"servers":[{"url":"https://mktcalendar.intelector.com","description":"Servidor actual"}],"tags":[{"name":"Opportunities","description":"Oportunidades priorizadas y ventanas de campaña"}],"paths":{"/api/marketing-calendar/opportunities":{"get":{"tags":["Opportunities"],"summary":"Obtener oportunidades de marketing","operationId":"getMarketingOpportunities","description":"Devuelve eventos relevantes ordenados por urgencia y relevancia. Requiere API key.","security":[{"ApiKeyAuth":[]}],"parameters":[{"name":"business_id","in":"query","required":false,"description":"Perfil de negocio que determina industria y ubicación automáticamente.","schema":{"type":"integer"}},{"name":"industry","in":"query","required":false,"description":"Slug de industria. Ejemplo: coffee_shop.","schema":{"type":"string"}},{"name":"country","in":"query","required":false,"description":"Código ISO alpha-2.","schema":{"type":"string","default":"MX"}},{"name":"state","in":"query","required":false,"description":"Código de estado. Ejemplo: JAL.","schema":{"type":"string"}},{"name":"days","in":"query","required":false,"description":"Horizonte entre 1 y 366 días.","schema":{"type":"integer","default":60,"minimum":1,"maximum":366}},{"name":"min_score","in":"query","required":false,"description":"Score mínimo entre 0 y 100.","schema":{"type":"number","default":0,"minimum":0,"maximum":100}},{"name":"limit","in":"query","required":false,"description":"Máximo de resultados entre 1 y 100.","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}}],"responses":{"200":{"description":"Consulta exitosa","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpportunityResponse"},"example":{"success":true,"data":[{"event":{"id":35,"name":"Día Internacional del Café","date":"2027-10-01","type":"institutional","official":false,"confidence":95,"source":{"name":"Calendario cultural de referencia","type":"cultural","url":null}},"score":91.5,"urgency":84.2,"campaign":{"prepare_date":"2027-09-10","start_date":"2027-09-17","peak_start":"2027-09-29","peak_end":"2027-10-01","end_date":"2027-10-02"},"reason":"Alta afinidad con cafeterías y potencial comercial.","actions":["Crear bebida o combo temático","Activar contenido en Instagram y WhatsApp"]}],"meta":{"count":1,"today":"2027-09-01"},"errors":[]}}}},"401":{"description":"API key ausente, inválida o expirada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parámetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit excedido","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"También se acepta Authorization: Bearer {API_KEY}."}},"schemas":{"CampaignWindow":{"type":"object","properties":{"prepare_date":{"type":"string","format":"date"},"start_date":{"type":"string","format":"date"},"peak_start":{"type":"string","format":"date"},"peak_end":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"}}},"Opportunity":{"type":"object","properties":{"event":{"type":"object"},"score":{"type":"number","format":"float"},"urgency":{"type":"number","format":"float"},"campaign":{"$ref":"#/components/schemas/CampaignWindow"},"reason":{"type":"string"},"actions":{"type":"array","items":{"type":"string"}}}},"OpportunityResponse":{"type":"object","required":["success","data","meta","errors"],"properties":{"success":{"type":"boolean","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}},"meta":{"type":"object"},"errors":{"type":"array","items":{"type":"object"}}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"data":{"nullable":true},"meta":{"type":"object"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}