#Salud financiera

Devuelve el Score de Salud Financiera Clarisfy de una Fiscal Entity: un número de 0 a 1000 con su banda, calculado sobre los propios datos fiscales del RFC (CFDIs, declaraciones, documentos y listas del SAT que Clarisfy ya descargó). Desglosa el score en cinco dimensiones con sus factores positivos y negativos, para que sepas qué está moviendo tu score y no solo el número.

#Score de salud financiera

GET/fiscal-entities/{fiscal_entity_id}/financial-health-score

#Parámetros de ruta

Parámetro	Tipo	Descripción
`fiscal_entity_id`	string	Identificador de la `FiscalEntity` (`fe_…`).

#Parámetros de query

Parámetro	Tipo	Descripción
`months`	integer	Opcional. Ventana de observación en meses, 6–36 (default `12`). Acota el periodo de CFDIs y señales que alimentan el score.

curl "https://api.clarisfy.com/v1/fiscal-entities/fe_9a1c2b3d4e5f6071/financial-health-score?months=12" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

El score y el score de cada dimensión son enteros. Los valores de razón y porcentaje (coverage_pct, weight, effective_weight) se serializan como string.

{
  "fiscal_entity_id": "fe_9a1c2b3d4e5f6071",
  "as_of": "2026-07-26T00:00:00+00:00",
  "months": 12,
  "score": 742,
  "band": "buena",
  "band_label": "Buena",
  "coverage_pct": "83.3",
  "low_confidence": false,
  "capped": false,
  "cap_reason": null,
  "dimensions": [
    {
      "key": "cumplimiento_fiscal",
      "label": "Cumplimiento fiscal",
      "weight": "0.25",
      "effective_weight": "0.30",
      "available": true,
      "score": 90,
      "signals": [
        { "label": "RFC sin coincidencias en listas negras 69-B", "impact": "positivo" },
        { "label": "Declaraciones presentadas al corriente", "impact": "positivo" }
      ]
    },
    {
      "key": "liquidez_flujo",
      "label": "Liquidez y flujo",
      "weight": "0.25",
      "effective_weight": "0.30",
      "available": true,
      "score": 68,
      "signals": [
        { "label": "Días de cobro por arriba de tu promedio", "impact": "negativo" },
        { "label": "Cartera vencida moderada", "impact": "neutral" }
      ]
    },
    {
      "key": "solvencia_rentabilidad",
      "label": "Solvencia y rentabilidad",
      "weight": "0.20",
      "effective_weight": "0.00",
      "available": false,
      "score": null,
      "signals": []
    },
    {
      "key": "comportamiento_operativo",
      "label": "Comportamiento operativo",
      "weight": "0.15",
      "effective_weight": "0.18",
      "available": true,
      "score": 74,
      "signals": [
        { "label": "Tasa de cancelación baja y estable", "impact": "positivo" },
        { "label": "Facturación consistente mes a mes", "impact": "positivo" }
      ]
    },
    {
      "key": "riesgo_contrapartes",
      "label": "Riesgo de contrapartes",
      "weight": "0.15",
      "effective_weight": "0.18",
      "available": true,
      "score": 61,
      "signals": [
        { "label": "Sin proveedores en lista 69-B", "impact": "positivo" },
        { "label": "Concentración de clientes elevada", "impact": "negativo" }
      ]
    }
  ],
  "top_factors": {
    "positivos": [
      "RFC sin coincidencias en listas negras 69-B",
      "Declaraciones presentadas al corriente",
      "Tasa de cancelación baja y estable"
    ],
    "negativos": [
      "Días de cobro por arriba de tu promedio",
      "Concentración de clientes elevada"
    ]
  },
  "methodology_note": "El Score de Salud Financiera Clarisfy es un scorecard experto y observacional construido sobre tus propios datos fiscales (CFDIs, declaraciones y listas públicas del SAT). Pondera cinco dimensiones; cuando una dimensión no tiene datos, su peso se redistribuye entre las disponibles y baja la cobertura. No es un modelo estadístico de incumplimiento ni un score de buró de crédito.",
  "disclaimer": "Este score es una señal observacional sobre tus propios datos fiscales para revisión interna. No es un score de buró de crédito, no representa una probabilidad de incumplimiento y no constituye asesoría financiera ni fiscal. Verifica con tu contador antes de tomar decisiones."
}

#Campos

Campo	Tipo	Descripción
`as_of`	string	Fecha/hora ISO en que se calculó el score.
`months`	integer	Ventana de observación efectiva (6–36).
`score`	integer	Score global 0–1000 (entero).
`band`	string	Banda del score: `excelente` \| `buena` \| `estable` \| `en_riesgo` \| `critica`.
`band_label`	string	Etiqueta de la banda para mostrar (ej. `"Buena"`).
`coverage_pct`	string	% del peso total cubierto por dimensiones con datos. NUMERIC como string.
`low_confidence`	boolean	`true` cuando `coverage_pct` < 50 — pocos datos para un score confiable.
`capped`	boolean	`true` si un tope duro forzó el score hacia abajo.
`cap_reason`	string \| null	Motivo del tope cuando `capped=true` (ej. `"RFC en lista 69-B (definitivo)"`); `null` si no aplica.
`dimensions`	array	Las cinco dimensiones (ver abajo).
`top_factors`	object	`positivos` y `negativos`: listas de los factores que más mueven el score.
`methodology_note`	string	Nota de metodología (reproduce cómo se construye el score).
`disclaimer`	string	Recordatorio de que es una señal observacional, no un score de buró ni asesoría.

#Dimensiones

Cada elemento de dimensions describe una dimensión evaluada:

Campo	Tipo	Descripción
`key`	string	Clave estable de la dimensión.
`label`	string	Nombre para mostrar.
`weight`	string	Peso nominal de la dimensión (razón, como string).
`effective_weight`	string	Peso efectivo tras redistribuir el de las dimensiones sin datos.
`available`	boolean	`false` si la dimensión no tiene datos suficientes; su `score` es `null` y su peso se redistribuye.
`score`	integer \| null	Score de la dimensión 0–100 (entero), o `null` si `available=false`.
`signals`	array	Señales explicables: `{ "label", "impact" }` con `impact` = `positivo` \| `negativo` \| `neutral`.

Las cinco dimensiones y qué observa cada una (los pesos son nominales):

Dimensión (`key`)	Peso	Qué observa
`cumplimiento_fiscal`	25%	Presencia del RFC propio en listas negras 69-B, presentación de declaraciones y régimen fiscal.
`liquidez_flujo`	25%	Días de cobro, cartera vencida y señales de flujo derivadas de tus CFDIs.
`solvencia_rentabilidad`	20%	Estructura del balance y margen tomados de tu Declaración Anual. Con datos solo si tienes Declaración Anual disponible.
`comportamiento_operativo`	15%	Cancelaciones, complementos de pago (REP), antigüedad y consistencia de tu facturación.
`riesgo_contrapartes`	15%	Exposición a proveedores en lista 69-B y concentración de clientes.

#Errores

Código HTTP	Causa
`202`	El reporte aún se está calculando. Cuerpo: `{"status":"computing","report_kind":"…","fiscal_entity_id":"fe_…","retry_after_seconds":15}`, más el header `Retry-After`. Reintenta después de los segundos indicados (`retry_after_seconds`).
`400`	`fiscal_entity_id` con formato inválido, o `months` fuera del rango 6–36.
`404`	Tu organización no tiene una conexión activa a esa Fiscal Entity.