Análisis con IA Carpeta Tributaria

Este endpoint devuelve el análisis con IA de una Carpeta Tributaria: conclusiones y nivel de riesgo por sección (IVA, ventas, declaraciones e indicadores) más un resumen global, generados sobre una carpeta en particular.

• El análisis se solicita con Generar Análisis con IA y se genera de forma asíncrona. Este endpoint permite consultarlo de forma periódica (polling) hasta que su estado sea SUCCEEDED o FAILED.
• Por defecto devuelve el análisis de la Carpeta Tributaria SUCCEEDED más reciente del RUT; con carpetaTributariaId devuelve el de una carpeta puntual del historial.
• El análisis corresponde siempre a una sola carpeta; no existe análisis sobre el consolidado.
• Si la carpeta no tiene análisis, o el RUT no tiene ninguna Carpeta Tributaria SUCCEEDED, el campo data será un objeto vacío {}.
• Como alternativa al polling, puedes recibir el resultado automáticamente vía webhook (processTaxFolderAnalysis); consulta Generar Análisis con IA.

Detalle de API

Request

• URL: /helper/carpetaTributaria/{rut}/analisis
• Método: GET

Parámetros

• rut (requerido, path): El RUT cuya Carpeta Tributaria se desea consultar. Formato del rut "12345678-9".
• carpetaTributariaId (opcional, query): Identificador de la Carpeta Tributaria cuyo análisis se desea consultar (número entero mayor o igual a 1). Debe estar SUCCEEDED y pertenecer a tu alcance. Si se omite, se consulta la más reciente. Los identificadores se obtienen con Historial Carpeta Tributaria.

Ejemplo request con curl

curl -X 'GET' \
  'https://prod.api.thesheriff.cl/api/clients/v2/helper/carpetaTributaria/12345678-9/analisis?carpetaTributariaId=12345' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9EjemploDeToken123' \
  -H 'x-client-identifier: SheriffSecureClient-v1'

Response

Success

• Status code: 200

• Example response body:

  {
    "success": true,
    "data": {
      "carpetaTributariaId": 12345,
      "estado": "SUCCEEDED",
      "resultado": {
        "iva": {
          "conclusiones": "El contribuyente declara IVA mensualmente y presenta sus formularios dentro de plazo en los últimos 12 períodos. El débito fiscal supera al crédito de forma sostenida, con impuesto a pagar en todos los meses.",
          "riesgo": "Riesgo Bajo"
        },
        "ventas": {
          "conclusiones": "Las ventas netas muestran una tendencia creciente en el último año, con estacionalidad marcada en los meses de verano y sin caídas abruptas.",
          "riesgo": "Riesgo Bajo"
        },
        "declaraciones": {
          "conclusiones": "Las declaraciones de Renta de los últimos tres años fueron presentadas y no registran rectificatorias. Se observan diferencias menores entre los ingresos anuales del F22 y la suma de ventas del F29.",
          "riesgo": "Riesgo Medio"
        },
        "indicadores": {
          "conclusiones": "La relación compras/ventas se mantiene estable en torno al 60%. El margen implícito es consistente con el rubro declarado.",
          "riesgo": "Riesgo Bajo"
        },
        "resumenGlobal": {
          "conclusiones": "Contribuyente con comportamiento tributario regular, ventas crecientes y declaraciones al día. Se recomienda revisar las diferencias detectadas entre F22 y F29.",
          "riesgo": "Riesgo Bajo"
        }
      },
      "error": null,
      "updatedAt": "20-06-2026 09:00:00",
      "regenerations": 0
    }
  }

  A continuación se describen los campos devueltos en la respuesta JSON.

  Campo	Tipo	Descripción
  success	bool	Indica si la operación fue exitosa.
  data	object	Análisis con IA de la Carpeta Tributaria. {} si no existe.

  Campos dentro de data:

  Campo	Tipo	Descripción
  carpetaTributariaId	number	Identificador de la Carpeta Tributaria analizada.
  estado	string	Estado del análisis: IN PROGRESS, SUCCEEDED o FAILED.
  resultado	object	Conclusiones por sección (ver estructura abajo). null mientras no exista un análisis exitoso. Durante una regeneración conserva el resultado del análisis anterior hasta que termine la nueva corrida.
  error	string	Mensaje de error cuando estado es FAILED; null en caso contrario.
  updatedAt	string	Fecha y hora de la última actualización del análisis (ISO 8601, UTC).
  regenerations	number	Regeneraciones ya consumidas por esta carpeta (máximo 2). Ver las reglas en Generar Análisis con IA.

  El campo estado puede tomar uno de los siguientes valores:

  Valor	Descripción
  IN PROGRESS	El análisis se está generando. Sigue consultando.
  SUCCEEDED	El análisis terminó correctamente; las conclusiones están en resultado.
  FAILED	El análisis falló; error describe el motivo. Puedes solicitarlo nuevamente sin consumir cupo de regeneraciones.

  Estructura del objeto resultado:

  Campo	Tipo	Descripción
  iva	object	Conclusiones sobre las declaraciones de IVA (Formulario 29).
  ventas	object	Conclusiones sobre el comportamiento de las ventas declaradas.
  declaraciones	object	Conclusiones sobre el cumplimiento y la consistencia de las declaraciones presentadas.
  indicadores	object	Conclusiones sobre los indicadores derivados de la información tributaria.
  resumenGlobal	object	Conclusión general de la carpeta, que integra las secciones anteriores.

  Estructura de cada sección (iva, ventas, declaraciones, indicadores y resumenGlobal):

  Campo	Tipo	Descripción
  conclusiones	string	Texto con las conclusiones de la IA para la sección. Se entrega sin saltos de línea.
  riesgo	string	Nivel de riesgo asignado por la IA a la sección (ej: "Riesgo Bajo").

  Tiempo de espera

  Si un análisis permanece más de 15 minutos en IN PROGRESS, al consultarlo se marca automáticamente como FAILED (con el mensaje "El análisis quedó sin completarse. Intenta generarlo nuevamente.") para que no quedes consultando indefinidamente. Puedes volver a solicitarlo sin consumir cupo de regeneraciones.

  nota

  La API no expone el modelo de IA utilizado para generar el análisis, y los textos de conclusiones se entregan sin saltos de línea.

  tip

  Los campos carpetaTributariaId, estado, resultado y error son los mismos que se entregan vía webhook (processTaxFolderAnalysis) cuando el análisis fue solicitado a través de la API. Ver Generar Análisis con IA.

  Si la carpeta no tiene análisis (o el RUT no tiene ninguna Carpeta Tributaria SUCCEEDED), la respuesta será:

  {
    "success": true,
    "data": {}
  }

  Errores

  Para este endpoint, un 400 indica que el parámetro carpetaTributariaId no es un número entero válido (mayor o igual a 1).

  400 - Solicitud inválida

  {
    "success": false,
    "code": 400,
    "error": "Solicitud inválida"
  }

  401 - No autorizado

  {
    "success": false,
    "code": 401,
    "error": "No autorizado"
  }

  403 - No tienes permiso para acceder a este recurso

  {
    "success": false,
    "code": 403,
    "error": "No tienes permiso para acceder a este recurso"
  }

  404 - Recurso no encontrado

  {
    "success": false,
    "code": 404,
    "error": "Recurso no encontrado"
  }

  408 - Tiempo de espera agotado

  {
    "success": false,
    "code": 408,
    "error": "Tiempo de espera agotado"
  }

  429 - Demasiadas solicitudes

  {
    "success": false,
    "code": 429,
    "error": "Demasiadas solicitudes"
  }

  500 - Error interno del servidor

  {
    "success": false,
    "code": 500,
    "error": "Error interno del servidor"
  }