{"openapi":"3.1.0","info":{"title":"Analítica Empresarial — API pública","version":"1.0","description":"API pública versionada para consumir datos financieros de **+35.000 empresas colombianas**.\n\n**Fuentes de datos:**\n- **SIIS** — Superintendencia de Sociedades (estados financieros NIIF Plenas / PYMES)\n- **SFC** — Superintendencia Financiera (estados XBRL IFRS de entidades vigiladas)\n\n**Características:**\n- Acceso público (sin autenticación)\n- Rate limit por IP: 60 req/min (30 req/min en endpoints costosos: `/sfc`, `/screener`)\n- CORS abierto\n- Cache: 1h en edge, 24h stale-while-revalidate\n- Errores en formato RFC 7807 (Problem Details)\n\n**Ejemplos de uso:**\n- Empresa SIIS bundle: `GET /api/v1/empresa/890900943`\n- Entidad SFC: `GET /api/v1/sfc/8002161815?include=profile,ratios`\n- Screener filtrado: `GET /api/v1/screener?seccion=F&page_size=20`\n- Búsqueda unificada: `GET /api/v1/search?q=avianca`\n\n**Cita la fuente original** (SIIS o SFC) al publicar análisis derivados.","contact":{"name":"Analítica Empresarial","url":"https://www.analiticaempresarial.info"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://www.analiticaempresarial.info/api/v1","description":"Producción"},{"url":"http://localhost:3000/api/v1","description":"Desarrollo local"}],"tags":[{"name":"Empresa SIIS","description":"Datos de empresas reportadas a Supersociedades (SIIS). Estados financieros NIIF, indicadores, benchmark sectorial."},{"name":"Entidad SFC","description":"Datos XBRL IFRS de entidades vigiladas por la Superintendencia Financiera (bancos, aseguradoras, fondos)."},{"name":"Catálogos","description":"Búsqueda y listado paginado de empresas."}],"paths":{"/empresa/{nit}":{"get":{"tags":["Empresa SIIS"],"summary":"Bundle SIIS de una empresa","description":"Retorna perfil + estados financieros + indicadores. Opcionalmente benchmark sectorial.","operationId":"getEmpresa","parameters":[{"name":"nit","in":"path","required":true,"description":"NIT de la empresa (6 a 15 dígitos numéricos).","schema":{"type":"string","pattern":"^\\d{6,15}$","example":"890900943"}},{"name":"include","in":"query","required":false,"description":"Secciones a incluir, separadas por coma. Default: `profile,financials,indicators`.","schema":{"type":"string","example":"profile,financials,indicators,benchmark"}},{"name":"years","in":"query","required":false,"description":"Lista de años separada por comas (ej: `2024,2023,2022`). Si se omite, retorna todos los disponibles.","schema":{"type":"string","example":"2024,2023,2022"}}],"responses":{"200":{"description":"Bundle de datos SIIS.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/EmpresaBundle"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/empresa/{nit}/financials":{"get":{"tags":["Empresa SIIS"],"summary":"Estados financieros de una empresa","operationId":"getEmpresaFinancials","parameters":[{"name":"nit","in":"path","required":true,"description":"NIT de la empresa (6 a 15 dígitos numéricos).","schema":{"type":"string","pattern":"^\\d{6,15}$","example":"890900943"}},{"name":"statement","in":"query","required":false,"description":"Estado financiero específico. Si se omite, retorna los tres.","schema":{"type":"string","enum":["resultados","situacion_financiera","flujo_efectivo"]}},{"name":"years","in":"query","required":false,"description":"Lista de años separada por comas (ej: `2024,2023,2022`). Si se omite, retorna todos los disponibles.","schema":{"type":"string","example":"2024,2023,2022"}}],"responses":{"200":{"description":"Estados financieros NIIF (ER, ESF, EFE).","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Financials"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/empresa/{nit}/indicators":{"get":{"tags":["Empresa SIIS"],"summary":"20 indicadores financieros por año","description":"Liquidez (5), eficiencia (6), endeudamiento (4), rentabilidad (5). Cada indicador trae su fórmula y unidad en `definitions`.","operationId":"getEmpresaIndicators","parameters":[{"name":"nit","in":"path","required":true,"description":"NIT de la empresa (6 a 15 dígitos numéricos).","schema":{"type":"string","pattern":"^\\d{6,15}$","example":"890900943"}},{"name":"category","in":"query","required":false,"description":"Filtra por categoría.","schema":{"type":"string","enum":["liquidez","eficiencia","endeudamiento","rentabilidad"]}},{"name":"years","in":"query","required":false,"description":"Lista de años separada por comas (ej: `2024,2023,2022`). Si se omite, retorna todos los disponibles.","schema":{"type":"string","example":"2024,2023,2022"}}],"responses":{"200":{"description":"Indicadores calculados por año.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Indicators"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/empresa/{nit}/benchmark":{"get":{"tags":["Empresa SIIS"],"summary":"Benchmark sectorial vs peers CIIU","description":"Percentiles P25/P50/P75 + promedios de empresas peers en los 3 niveles CIIU (clase, división, sección). Incluye ranking top-N.","operationId":"getEmpresaBenchmark","parameters":[{"name":"nit","in":"path","required":true,"description":"NIT de la empresa (6 a 15 dígitos numéricos).","schema":{"type":"string","pattern":"^\\d{6,15}$","example":"890900943"}},{"name":"years","in":"query","required":false,"description":"Lista de años separada por comas (ej: `2024,2023,2022`). Si se omite, retorna todos los disponibles.","schema":{"type":"string","example":"2024,2023,2022"}},{"name":"ranking_level","in":"query","required":false,"description":"Nivel CIIU para el ranking de empresas pares.","schema":{"type":"string","enum":["clase","division","seccion"],"default":"clase"}},{"name":"ranking_limit","in":"query","required":false,"description":"Tamaño del ranking (1-100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Peer stats + ranking.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Benchmark"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/sfc/{nit}":{"get":{"tags":["Entidad SFC"],"summary":"Bundle SFC de una entidad XBRL IFRS","description":"Datos de entidades vigiladas (bancos, aseguradoras, fondos). Profile, filings, estados IFRS, ratios y notas narrativas.","operationId":"getSfcEntity","parameters":[{"name":"nit","in":"path","required":true,"description":"NIT de la empresa (6 a 15 dígitos numéricos).","schema":{"type":"string","pattern":"^\\d{6,15}$","example":"890900943"},"example":"8002161815"},{"name":"include","in":"query","required":false,"description":"Secciones a incluir. Default: `profile,filings,ratios`. `statements` y `notes` son costosos — pedir explícito.","schema":{"type":"string","example":"profile,filings,ratios,statements,notes"}},{"name":"years","in":"query","required":false,"description":"Lista de años separada por comas (ej: `2024,2023,2022`). Si se omite, retorna todos los disponibles.","schema":{"type":"string","example":"2024,2023,2022"}},{"name":"statements","in":"query","required":false,"description":"Cuando `include=statements`, especifica qué estados (separados por coma).","schema":{"type":"string","example":"financial_position,profit_loss"}}],"responses":{"200":{"description":"Bundle SFC XBRL.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SfcBundle"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/screener":{"get":{"tags":["Catálogos"],"summary":"Listado paginado y filtrable de empresas SIIS","description":"Filtra por CIIU, geografía, marco NIIF, estado, etc. Ordena por ingresos, activos, ganancia o razón social.","operationId":"getScreener","parameters":[{"name":"seccion","in":"query","schema":{"type":"string","example":"F"},"description":"CIIU sección (1 letra)."},{"name":"division","in":"query","schema":{"type":"string","example":"42"},"description":"CIIU división (2 dígitos)."},{"name":"clase","in":"query","schema":{"type":"string","example":"4290"},"description":"CIIU clase (4 dígitos)."},{"name":"departamento","in":"query","schema":{"type":"string"}},{"name":"ciudad","in":"query","schema":{"type":"string"}},{"name":"marco_niif","in":"query","schema":{"type":"string","enum":["PLENAS","PYMES"]}},{"name":"estado_actual","in":"query","schema":{"type":"string"}},{"name":"tipo_societario","in":"query","schema":{"type":"string"}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Búsqueda libre por nombre o NIT."},{"name":"sort","in":"query","schema":{"type":"string","enum":["razon_social","ingresos_operacionales","total_activos","ganancia_operacional","ganancia_neta"],"default":"ingresos_operacionales"}},{"name":"order","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Empresas + paginación.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ScreenerResult"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/search":{"get":{"tags":["Catálogos"],"summary":"Búsqueda unificada SIIS + SFC","description":"Busca empresas por nombre o NIT en ambos datasets. Una empresa que existe en ambos aparece dos veces (una por dataset).","operationId":"getSearch","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2},"description":"Término de búsqueda (mín. 2 caracteres)."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"source","in":"query","schema":{"type":"string","enum":["siis","sfc"]},"description":"Filtra por dataset."}],"responses":{"200":{"description":"Resultados de búsqueda.","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Límite de requests por ventana."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests restantes en la ventana actual."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Epoch (segundos) cuando se reinicia la ventana."}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SearchResult"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Parámetros inválidos.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"429":{"description":"Demasiadas peticiones. El header `Retry-After` indica los segundos a esperar.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Segundos a esperar antes de reintentar"}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"500":{"description":"Error inesperado del servidor.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"components":{"schemas":{"Meta":{"type":"object","required":["version","generated_at","url"],"properties":{"version":{"type":"string","example":"1.0"},"generated_at":{"type":"string","format":"date-time"},"url":{"type":"string","format":"uri"},"source":{"type":"string","description":"Fuente original del dato (SIIS, SFC, etc.)."}},"additionalProperties":true},"Problem":{"type":"object","description":"Error en formato RFC 7807.","required":["type","title","status","detail","instance"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"}},"additionalProperties":true},"EmpresaBundle":{"type":"object","description":"Bundle SIIS con secciones modulables vía `?include=`.","properties":{"profile":{"type":"object","description":"Identificación, CIIU, ubicación, contacto."},"financials":{"type":"object","properties":{"currency":{"type":"string","example":"COP"},"unit":{"type":"string","example":"units"},"estado_resultados":{"type":"array","items":{"type":"object"}},"estado_situacion_financiera":{"type":"array","items":{"type":"object"}},"estado_flujo_efectivo":{"type":"array","items":{"type":"object"}}}},"indicators":{"$ref":"#/components/schemas/Indicators"},"benchmark":{"oneOf":[{"$ref":"#/components/schemas/Benchmark"},{"type":"null"}]}}},"Financials":{"type":"object","properties":{"currency":{"type":"string"},"unit":{"type":"string"},"estado_resultados":{"type":"array","items":{"type":"object"}},"estado_situacion_financiera":{"type":"array","items":{"type":"object"}},"estado_flujo_efectivo":{"type":"array","items":{"type":"object"}}}},"Indicators":{"type":"object","properties":{"definitions":{"type":"object","description":"Metadatos de cada indicador: category, unit, formula.","additionalProperties":{"type":"object","properties":{"category":{"type":"string","enum":["liquidez","eficiencia","endeudamiento","rentabilidad"]},"unit":{"type":"string","enum":["ratio","percent","days","currency"]},"formula":{"type":"string"}}}},"by_year":{"type":"array","items":{"type":"object","required":["anio"],"properties":{"anio":{"type":"integer"}},"additionalProperties":{"type":["number","null"]}}}}},"Benchmark":{"type":"object","properties":{"empresa":{"type":"object"},"peer_stats_by_year":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"nivel":{"type":"string","enum":["clase","division","seccion"]},"num_empresas":{"type":"integer"}},"additionalProperties":true}}},"ranking":{"type":"object","properties":{"level":{"type":"string"},"limit":{"type":"integer"},"top":{"type":"array","items":{"type":"object"}}}}}},"SfcBundle":{"type":"object","description":"Bundle XBRL IFRS de SFC con secciones modulables.","properties":{"profile":{"type":"object"},"filings":{"type":"array","items":{"type":"object"}},"statements":{"type":"object","description":"Estados IFRS por nombre (financial_position, profit_loss, etc.).","additionalProperties":{"type":"object"}},"ratios":{"type":"object"},"notes":{"type":"object"}}},"ScreenerResult":{"type":"object","properties":{"empresas":{"type":"array","items":{"type":"object"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"page_size":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_next":{"type":"boolean"},"has_prev":{"type":"boolean"}}},"anio":{"type":"integer"}}},"SearchResult":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"nit":{"type":"string"},"razon_social":{"type":"string"},"source":{"type":"string","enum":["SUPERSOC","SFC"]},"href":{"type":"string"}},"additionalProperties":true}},"count":{"type":"integer"}}}}}}