{"openapi":"3.1.0","info":{"title":"API de PUC Colombia","version":"1.0.0","summary":"API REST de solo lectura sobre el Plan Único de Cuentas de Colombia.","description":"API REST de solo lectura sobre el **Plan Único de Cuentas** de Colombia (Decreto 2650): cuentas y su dinámica, equivalencias NIIF, reportes oficiales (DIAN, Supersociedades, CGN, UGPP), estados financieros NIIF, indicadores macroeconómicos y glosario.\n\n## Autenticación\nEnvía tu llave en la cabecera `x-api-key` o como `Authorization: Bearer <token>`. El plan **Free** ofrece 3 solicitudes/día con llave autoservicio desde el perfil; **Pro** 100/día y **Studio** 5000/día. Sin llave válida se responde 401.\n\n## Límites de tasa\nLa cuota se cuenta por día calendario UTC. Cada respuesta incluye `RateLimit`, `RateLimit-Policy` y `X-RateLimit-Limit/Remaining/Reset`; un 429 incluye `Retry-After`.\n\n## Paginación\nLos listados aceptan `limit` (1–100) y `offset` y devuelven un objeto `pagination` con `limit`, `offset` y `total`.\n\n## Versionado\nLa versión va en la ruta (`/api/v1`). Un cambio incompatible estrena una versión nueva; una operación en retiro se anuncia con las cabeceras `Deprecation` y `Sunset` con al menos 6 meses de preaviso.\n\n## Errores\nTodos los errores usan `{ \"error\": { \"code\", \"message\" } }` con el código HTTP correspondiente (400/401/402/404/429/500).\n\nEl contenido es informativo y no constituye asesoría. Términos: https://puccol.com/terms","termsOfService":"https://puccol.com/terms","contact":{"name":"PUC Colombia","url":"https://puccol.com/developers","email":"contacto@puccol.com"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://puccol.com/api/v1","description":"Producción (v1)"}],"externalDocs":{"description":"Portal de desarrolladores","url":"https://puccol.com/developers"},"security":[{"apiKey":[]},{"oauth2":["puc.read"]}],"paths":{"/cuentas":{"get":{"operationId":"listCuentas","summary":"Listar cuentas del PUC","description":"Devuelve cuentas de un plan jurisdiccional con búsqueda por código (prefijo) o nombre (ILIKE), filtro por nivel y paginación.","parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 del país (default CO).","schema":{"type":"string","default":"CO"}},{"name":"q","in":"query","required":false,"description":"Búsqueda por código o nombre.","schema":{"type":"string"}},{"name":"nivel","in":"query","required":false,"description":"Nivel jerárquico (1–6).","schema":{"type":"integer","minimum":1,"maximum":6}},{"name":"limit","in":"query","required":false,"description":"Tamaño de página (1–100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Desplazamiento para paginación.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Cuenta"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"country":{"type":"string"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/cuentas/{codigo}":{"get":{"operationId":"getCuenta","summary":"Detalle de una cuenta","description":"Devuelve la cuenta y su contexto: dinámica débito/crédito, mapeo NIIF, reportes oficiales, ejemplos de asiento e historial normativo.","parameters":[{"name":"codigo","in":"path","required":true,"description":"Código numérico de la cuenta.","schema":{"type":"string","pattern":"^\\d{1,6}$"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","default":"CO"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/CuentaDetalle"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reportes":{"get":{"operationId":"listReportes","summary":"Listar reportes oficiales","description":"Catálogo de reportes oficiales (DIAN, Supersociedades, Supersolidaria, Superfinanciera, CGN, UGPP).","parameters":[{"name":"autoridad","in":"query","required":false,"schema":{"type":"string"}},{"name":"sigla","in":"query","required":false,"description":"Coincidencia parcial sobre la sigla.","schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Tamaño de página (1–100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Desplazamiento para paginación.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reporte"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/reportes/{autoridad}/{sigla}":{"get":{"operationId":"getReporte","summary":"Detalle de un reporte","description":"Devuelve el reporte, sus conceptos (filas/columnas oficiales) y la cantidad de cuentas PUC mapeadas.","parameters":[{"name":"autoridad","in":"path","required":true,"schema":{"type":"string"}},{"name":"sigla","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"description":"Si se omite, la más reciente.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ReporteDetalle"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estados":{"get":{"operationId":"listEstados","summary":"Listar estados financieros NIIF","description":"Índice de los estados financieros NIIF disponibles (ESF, ERI, ECP, EFE) con sus variantes.","parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EstadoIndice"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/estados/{estado}":{"get":{"operationId":"getEstado","summary":"Estructura de un estado financiero NIIF","description":"Devuelve la estructura de presentación de un estado financiero conectada al PUC, como árbol de renglones.","parameters":[{"name":"estado","in":"path","required":true,"description":"esf | eri | ecp | efe.","schema":{"type":"string","enum":["esf","eri","ecp","efe"]}},{"name":"variante","in":"query","required":false,"description":"Código de variante (por defecto la principal).","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/EstadoDetalle"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/indicadores":{"get":{"operationId":"listIndicadores","summary":"Listar indicadores macroeconómicos","description":"Indicadores (UVT, SMMLV, TRM, IBR, IPC, DTF…) con su último valor, fecha y fuente oficial.","parameters":[{"name":"categoria","in":"query","required":false,"schema":{"type":"string"}},{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Tamaño de página (1–100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Desplazamiento para paginación.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Indicador"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/indicadores/{clave}":{"get":{"operationId":"getIndicador","summary":"Detalle de un indicador (con serie)","description":"Devuelve un indicador por clave o slug, con su último valor y la serie histórica. La serie de los últimos 365 días es pública; el histórico completo requiere plan Pro.","parameters":[{"name":"clave","in":"path","required":true,"description":"Clave o slug del indicador.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/IndicadorDetalle"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/glosario":{"get":{"operationId":"listGlosario","summary":"Términos del glosario contable","description":"Diccionario trilingüe (es/en/pt) con definición, norma de referencia y cuentas relacionadas.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Tamaño de página (1–100).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"offset","in":"query","required":false,"description":"Desplazamiento para paginación.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GlosarioTermino"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"description":"Parámetro inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Falta la API key o es inválida/revocada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"El plan no incluye acceso a la API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Recurso no encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Cuota diaria superada (ver Retry-After).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error interno.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Llave de API (formato pucol_live_…). Genérala en tu perfil; plan Free 3 req/día."},"oauth2":{"type":"oauth2","description":"OAuth 2.1 (authorization code + PKCE) del OAuth Server de Supabase. Ver /auth.md y /.well-known/oauth-protected-resource.","flows":{"authorizationCode":{"authorizationUrl":"https://vtlfdeoprrdcoqtyzahf.supabase.co/auth/v1/oauth/authorize","tokenUrl":"https://vtlfdeoprrdcoqtyzahf.supabase.co/auth/v1/oauth/token","scopes":{"puc.read":"Leer cuentas, estados y glosario del PUC.","reportes.read":"Leer reportes oficiales.","indicadores.read":"Leer indicadores (últimos 365 días).","indicadores.full":"Leer el histórico completo de indicadores (plan de pago)."}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Código de error legible por máquina.","examples":["bad_request","unauthorized","payment_required","not_found","rate_limit_exceeded","internal"]},"message":{"type":"string","description":"Descripción legible por humanos."},"retry_after":{"type":["integer","null"],"description":"Segundos hasta reintentar (solo en 429)."}}}}},"Pagination":{"type":"object","required":["limit","offset","total"],"properties":{"limit":{"type":"integer","description":"Tamaño de página aplicado."},"offset":{"type":"integer","description":"Desplazamiento aplicado."},"total":{"type":"integer","description":"Total de elementos que cumplen el filtro."}}},"Cuenta":{"type":"object","properties":{"id":{"type":"string","description":"Identificador interno de la cuenta."},"code":{"type":"string","description":"Código PUC (1 a 6 dígitos).","examples":["1105"]},"name":{"type":"string","examples":["Caja"]},"type":{"type":"string","description":"Nivel: clase, grupo, cuenta o subcuenta."},"level":{"type":"integer","description":"Nivel jerárquico (1=clase … 6=subcuenta)."},"nature":{"type":"string","description":"Naturaleza contable.","examples":["debito","credito"]},"balance":{"type":"string","description":"Tipo de saldo.","examples":["deudor","acreedor"]}}},"CuentaDetalle":{"allOf":[{"$ref":"#/components/schemas/Cuenta"},{"type":"object","properties":{"dinamica":{"type":["object","null"],"additionalProperties":true},"ifrs":{"type":["object","null"],"additionalProperties":true},"reportes":{"type":"array","items":{"type":"object","additionalProperties":true}},"ejemplos":{"type":"array","items":{"type":"object","additionalProperties":true}},"historial":{"type":"array","items":{"type":"object","additionalProperties":true}}}}]},"Reporte":{"type":"object","properties":{"id":{"type":"string"},"autoridad":{"type":"string","examples":["DIAN","SUPERSOCIEDADES"]},"sigla":{"type":"string","examples":["EXOGENA-1005"]},"nombre":{"type":"string"},"formato":{"type":["string","null"]},"version":{"type":["string","null"]},"periodo":{"type":["string","null"]},"url":{"type":["string","null"]},"notas":{"type":["string","null"]}}},"ReporteDetalle":{"allOf":[{"$ref":"#/components/schemas/Reporte"},{"type":"object","properties":{"conceptos":{"type":"array","items":{"type":"object","additionalProperties":true}},"mapeos_count":{"type":"integer"}}}]},"EstadoIndice":{"type":"object","properties":{"estado":{"type":"string"},"default":{"$ref":"#/components/schemas/EstadoVariante"},"variantes":{"type":"array","items":{"$ref":"#/components/schemas/EstadoVariante"}}}},"EstadoVariante":{"type":"object","properties":{"codigo":{"type":"string"},"nombre":{"type":"string"},"norma":{"type":["string","null"]},"es_default":{"type":"boolean"},"premium":{"type":"boolean"}}},"EstadoDetalle":{"type":"object","properties":{"estado":{"type":"string"},"variante":{"$ref":"#/components/schemas/EstadoVariante"},"variantes":{"type":"array","items":{"$ref":"#/components/schemas/EstadoVariante"}},"nodes":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Indicador":{"type":"object","properties":{"clave":{"type":"string","examples":["uvt","trm"]},"slug":{"type":"string"},"nombre":{"type":"string"},"categoria":{"type":["string","null"]},"unidad":{"type":["string","null"]},"periodicidad":{"type":["string","null"]},"decimales":{"type":["integer","null"]},"fuente":{"type":["string","null"]},"url_fuente":{"type":["string","null"]},"descripcion":{"type":["string","null"]},"ultimo_valor":{"type":["object","null"],"properties":{"valor":{"type":"number"},"fecha":{"type":["string","null"],"format":"date"},"periodo":{"type":["string","null"]}}}}},"IndicadorDetalle":{"allOf":[{"$ref":"#/components/schemas/Indicador"},{"type":"object","properties":{"serie":{"type":"array","items":{"$ref":"#/components/schemas/SeriePunto"}}}}]},"SeriePunto":{"type":"object","properties":{"fecha":{"type":"string","format":"date"},"valor":{"type":"number"}}},"GlosarioTermino":{"type":"object","properties":{"slug":{"type":"string"},"termino":{"type":"object","properties":{"es":{"type":"string"},"en":{"type":["string","null"]},"pt":{"type":["string","null"]}}},"norma":{"type":["string","null"]}}}}}}