{"openapi":"3.0.3","info":{"title":"RutAPI","version":"1.0.0","description":"API para consultar empresas, contribuyentes y actividades económicas publicadas por el Servicio de Impuestos Internos (SII) de Chile.","contact":{"name":"RutAPI","url":"https://app.rutapi.cl"}},"servers":[{"url":"https://app.rutapi.cl","description":"Producción"}],"tags":[{"name":"Empresas","description":"Consulta y búsqueda de empresas y contribuyentes por RUT o razón social."},{"name":"Actividades económicas","description":"Consulta del catálogo de actividades económicas y sus contribuyentes asociados."}],"security":[{"bearerAuth":[]},{"apiKeyHeader":[]}],"paths":{"/api/v1/companies/ruts/{rut}":{"get":{"tags":["Empresas"],"summary":"Consultar una empresa por RUT","description":"Obtiene el registro público completo de un contribuyente, incluyendo identidad, actividades económicas vigentes, domicilio y sucursales. Requiere el scope `ruts:read`.","operationId":"consultarEmpresaPorRut","x-required-scope":"ruts:read","parameters":[{"name":"rut","in":"path","required":true,"description":"RUT chileno con dígito verificador. Puede enviarse con puntos y guion, sin puntos o sin separadores.","schema":{"type":"string","minLength":2,"maxLength":20},"examples":{"conFormato":{"summary":"Con formato","value":"76.281.808-6"},"sinPuntos":{"summary":"Sin puntos","value":"76281808-6"},"sinSeparadores":{"summary":"Sin separadores","value":"762818086"}}}],"responses":{"200":{"description":"Empresa encontrada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmpresaDetallada"}}}},"401":{"$ref":"#/components/responses/ApiKeyInvalida"},"403":{"$ref":"#/components/responses/ScopeInsuficiente"},"404":{"description":"No existe un contribuyente para el RUT indicado."},"422":{"$ref":"#/components/responses/ErrorValidacion"},"429":{"$ref":"#/components/responses/LimiteExcedido"}}}},"/api/v1/companies/search":{"get":{"tags":["Empresas"],"summary":"Buscar empresas","description":"Busca empresas por razón social y permite filtrar por actividad económica, región, comuna y tipo de entidad. Los resultados se entregan paginados. Requiere el scope `search:read`.","operationId":"buscarEmpresas","x-required-scope":"search:read","parameters":[{"$ref":"#/components/parameters/ConsultaOpcional"},{"name":"activityCode","in":"query","description":"Código de actividad económica vigente.","schema":{"type":"string","maxLength":16},"example":"620200"},{"name":"region","in":"query","description":"Nombre de la región del domicilio vigente.","schema":{"type":"string","maxLength":120},"example":"XIII REGION METROPOLITANA"},{"name":"commune","in":"query","description":"Nombre de la comuna del domicilio vigente.","schema":{"type":"string","maxLength":120},"example":"SANTIAGO"},{"name":"type","in":"query","description":"Tipo de entidad legal registrado por el SII.","schema":{"type":"string","maxLength":120}},{"$ref":"#/components/parameters/Pagina"},{"$ref":"#/components/parameters/Limite"}],"responses":{"200":{"description":"Resultados de la búsqueda.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaEmpresas"}}}},"401":{"$ref":"#/components/responses/ApiKeyInvalida"},"403":{"$ref":"#/components/responses/ScopeInsuficiente"},"422":{"$ref":"#/components/responses/ErrorValidacion"},"429":{"$ref":"#/components/responses/LimiteExcedido"}}}},"/api/v1/companies/autocomplete":{"get":{"tags":["Empresas"],"summary":"Autocompletar empresas","description":"Busca coincidencias rápidas por prefijo de RUT o fragmento de razón social. Requiere el scope `search:read`.","operationId":"autocompletarEmpresas","x-required-scope":"search:read","parameters":[{"name":"q","in":"query","required":true,"description":"RUT, prefijo de RUT o fragmento de razón social.","schema":{"type":"string","minLength":1,"maxLength":120},"example":"7628"},{"name":"limit","in":"query","description":"Cantidad máxima de sugerencias. Por defecto: 10.","schema":{"type":"integer","minimum":1,"maximum":25,"default":10}}],"responses":{"200":{"description":"Sugerencias encontradas.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SugerenciaEmpresa"}}}}},"401":{"$ref":"#/components/responses/ApiKeyInvalida"},"403":{"$ref":"#/components/responses/ScopeInsuficiente"},"422":{"$ref":"#/components/responses/ErrorValidacion"},"429":{"$ref":"#/components/responses/LimiteExcedido"}}}},"/api/v1/companies/activities/search":{"get":{"tags":["Actividades económicas"],"summary":"Buscar actividades económicas","description":"Lista códigos de actividad económica vigentes junto con la cantidad de RUT asociados. Permite buscar por descripción y entrega resultados paginados. Requiere el scope `activities:read`.","operationId":"buscarActividadesEconomicas","x-required-scope":"activities:read","parameters":[{"$ref":"#/components/parameters/ConsultaOpcional"},{"$ref":"#/components/parameters/Pagina"},{"$ref":"#/components/parameters/Limite"}],"responses":{"200":{"description":"Actividades económicas encontradas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaActividades"}}}},"401":{"$ref":"#/components/responses/ApiKeyInvalida"},"403":{"$ref":"#/components/responses/ScopeInsuficiente"},"422":{"$ref":"#/components/responses/ErrorValidacion"},"429":{"$ref":"#/components/responses/LimiteExcedido"}}}},"/api/v1/companies/activities/{code}/ruts":{"get":{"tags":["Actividades económicas"],"summary":"Listar contribuyentes de una actividad","description":"Entrega los contribuyentes actualmente registrados bajo un código de actividad económica. Los resultados se entregan paginados. Requiere el scope `activities:read`.","operationId":"listarContribuyentesPorActividad","x-required-scope":"activities:read","parameters":[{"name":"code","in":"path","required":true,"description":"Código de actividad económica del SII.","schema":{"type":"string","maxLength":16},"example":"620200"},{"$ref":"#/components/parameters/Pagina"},{"$ref":"#/components/parameters/Limite"}],"responses":{"200":{"description":"Contribuyentes asociados a la actividad.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginaContribuyentesActividad"}}}},"401":{"$ref":"#/components/responses/ApiKeyInvalida"},"403":{"$ref":"#/components/responses/ScopeInsuficiente"},"422":{"$ref":"#/components/responses/ErrorValidacion"},"429":{"$ref":"#/components/responses/LimiteExcedido"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"Envía la API key en el encabezado `Authorization: Bearer <api_key>`."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Alternativamente, envía la API key en el encabezado `X-Api-Key`."}},"parameters":{"ConsultaOpcional":{"name":"q","in":"query","description":"Texto a buscar. La comparación no distingue mayúsculas ni tildes.","schema":{"type":"string","maxLength":120}},"Pagina":{"name":"page","in":"query","description":"Número de página. Por defecto: 1.","schema":{"type":"integer","minimum":1,"default":1}},"Limite":{"name":"limit","in":"query","description":"Cantidad de resultados por página. Por defecto: 25.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}},"responses":{"ApiKeyInvalida":{"description":"La API key no fue enviada, no existe, fue revocada o expiró.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApi"},"example":{"error":{"code":"E_INVALID_API_KEY","message":"Invalid API key."}}}}},"ScopeInsuficiente":{"description":"La API key es válida, pero no posee el scope requerido por el endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorApi"},"example":{"error":{"code":"E_MISSING_API_KEY_SCOPE","message":"This API key lacks the search:read scope."}}}}},"ErrorValidacion":{"description":"Uno o más parámetros no cumplen el contrato del endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErroresValidacion"},"example":{"errors":[{"message":"The q field must be defined","rule":"required","field":"q"}]}}}},"LimiteExcedido":{"description":"La API key excedió su límite de solicitudes por minuto. Los encabezados `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset` indican cuándo reintentar.","headers":{"Retry-After":{"description":"Segundos que faltan para poder reintentar.","schema":{"type":"integer","minimum":1}},"X-RateLimit-Limit":{"description":"Cantidad máxima de solicitudes permitidas en la ventana actual.","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Solicitudes restantes en la ventana actual.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Fecha y hora ISO 8601 en que se reinicia la ventana.","schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorLimite"}}}}},"schemas":{"Empresa":{"type":"object","required":["rut","businessName","subtypeCode","subtype","type","validFrom","validTo","isCurrent"],"properties":{"rut":{"type":"string","description":"RUT canónico sin puntos y con guion.","example":"76281808-6"},"businessName":{"type":"string","description":"Razón social registrada.","example":"EMPRESA DE EJEMPLO LIMITADA"},"subtypeCode":{"type":"string","nullable":true,"description":"Código del subtipo de entidad legal."},"subtype":{"type":"string","nullable":true,"description":"Subtipo de entidad legal.","example":"SOC. RESPONSABILIDAD LIMITADA"},"type":{"type":"string","nullable":true,"description":"Tipo general de entidad legal."},"validFrom":{"type":"string","format":"date","nullable":true,"description":"Fecha desde la cual el registro tiene vigencia."},"validTo":{"type":"string","format":"date","nullable":true,"description":"Fecha hasta la cual el registro tuvo vigencia."},"isCurrent":{"type":"boolean","description":"Indica si el registro se encuentra vigente."}}},"EmpresaDetallada":{"allOf":[{"$ref":"#/components/schemas/Empresa"},{"type":"object","required":["entityImportedAt","activities","domicile","branches"],"properties":{"entityImportedAt":{"type":"string","format":"date-time","nullable":true,"description":"Fecha y hora en que el registro fue importado desde la fuente."},"activities":{"type":"array","description":"Actividades económicas vigentes del contribuyente.","items":{"$ref":"#/components/schemas/ActividadEmpresa"}},"domicile":{"type":"object","nullable":true,"description":"Domicilio vigente del contribuyente.","allOf":[{"$ref":"#/components/schemas/Direccion"}]},"branches":{"type":"array","description":"Sucursales vigentes del contribuyente.","items":{"$ref":"#/components/schemas/Direccion"}}}}]},"SugerenciaEmpresa":{"type":"object","required":["rut","businessName","subtype","type","isCurrent"],"properties":{"rut":{"type":"string","example":"76281808-6"},"businessName":{"type":"string","example":"EMPRESA DE EJEMPLO LIMITADA"},"subtype":{"type":"string","nullable":true},"type":{"type":"string","nullable":true},"isCurrent":{"type":"boolean"}}},"ActividadEmpresa":{"type":"object","required":["code","description","date","affectsIva","taxCategory"],"properties":{"code":{"type":"string","description":"Código de actividad económica.","example":"620200"},"description":{"type":"string","description":"Descripción de la actividad económica.","example":"ACTIVIDADES DE CONSULTORÍA DE INFORMÁTICA"},"date":{"type":"string","format":"date","nullable":true,"description":"Fecha asociada al inicio de la actividad."},"affectsIva":{"type":"boolean","description":"Indica si la actividad está afecta a IVA."},"taxCategory":{"type":"string","nullable":true,"description":"Categoría tributaria informada por el SII."}}},"Direccion":{"type":"object","required":["kind","vigencia","date","street","number","block","department","village","city","commune","region"],"properties":{"kind":{"type":"string","description":"Tipo de dirección.","example":"DOMICILIO"},"vigencia":{"type":"string","nullable":true,"description":"Estado de vigencia informado."},"date":{"type":"string","format":"date","nullable":true},"street":{"type":"string","nullable":true,"example":"ALAMEDA"},"number":{"type":"string","nullable":true,"example":"123"},"block":{"type":"string","nullable":true},"department":{"type":"string","nullable":true},"village":{"type":"string","nullable":true},"city":{"type":"string","nullable":true,"example":"SANTIAGO"},"commune":{"type":"string","nullable":true,"example":"SANTIAGO"},"region":{"type":"string","nullable":true,"example":"XIII REGION METROPOLITANA"}}},"ResumenActividad":{"type":"object","required":["code","description","rutsCount"],"properties":{"code":{"type":"string","example":"620200"},"description":{"type":"string","example":"ACTIVIDADES DE CONSULTORÍA DE INFORMÁTICA"},"rutsCount":{"type":"integer","minimum":0,"description":"Cantidad de RUT vigentes asociados a la actividad."}}},"ContribuyenteActividad":{"type":"object","required":["rut","businessName","activity"],"properties":{"rut":{"type":"string","example":"76281808-6"},"businessName":{"type":"string","nullable":true},"activity":{"$ref":"#/components/schemas/ActividadEmpresa"}}},"MetadataPaginacion":{"type":"object","required":["total","per_page","current_page","last_page","first_page"],"properties":{"total":{"type":"integer","minimum":0},"per_page":{"type":"integer","minimum":1},"current_page":{"type":"integer","minimum":1},"last_page":{"type":"integer","minimum":1},"first_page":{"type":"integer","minimum":1},"first_page_url":{"type":"string","nullable":true},"last_page_url":{"type":"string","nullable":true},"next_page_url":{"type":"string","nullable":true},"previous_page_url":{"type":"string","nullable":true}}},"PaginaEmpresas":{"type":"object","required":["data","metadata"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Empresa"}},"metadata":{"$ref":"#/components/schemas/MetadataPaginacion"}}},"PaginaActividades":{"type":"object","required":["data","metadata"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResumenActividad"}},"metadata":{"$ref":"#/components/schemas/MetadataPaginacion"}}},"PaginaContribuyentesActividad":{"type":"object","required":["data","metadata"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContribuyenteActividad"}},"metadata":{"$ref":"#/components/schemas/MetadataPaginacion"}}},"ErrorApi":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"ErroresValidacion":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["message","rule","field"],"properties":{"message":{"type":"string"},"rule":{"type":"string"},"field":{"type":"string"}}}}}},"ErrorLimite":{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object","required":["message","retryAfter"],"properties":{"message":{"type":"string","example":"Too many requests"},"retryAfter":{"type":"integer","minimum":1}}}}}}}}}