#Riesgo

Los endpoints /cfdi/risk/* calculan señales de riesgo derivadas de los CFDIs de una Fiscal Entity: visibilidad sobre problemas de flujo de caja, cancelaciones desincronizadas, retenciones, contrapartes en la lista 69-B, concentración de clientes y deducciones/retenciones de ISR en riesgo.

#El patrón summary → items

Las 7 familias de riesgo comparten la misma forma: un endpoint summary agrega el riesgo por periodo (tendencia mensual, para graficar) y un endpoint items hace drill-down: lista los CFDIs concretos detrás de una categoría/severidad/bucket seleccionada en el summary.

Todos requieren fiscalEntityId (fe_…) y están tenant-gated: 404 si tu organización no tiene una conexión activa a ese RFC.
summary toma from/to como periodos YYYY-MM inclusivos (ej. from=2026-01&to=2026-06), rango máximo 24 meses.
items toma from/to como fechas (no periodos) sobre issued_at, mismo tope de 24 meses, y siempre un selector adicional obligatorio (category, severity, taxCode, status o rfc según la familia) que reproduce el mismo predicado exacto del summary. Usa paginación por cursor igual que /cfdi/invoices (parámetros cursor/pageSize).
Los montos son NUMERIC serializados como string.

Parámetro	Aplica a	Descripción
`fiscalEntityId`	Todos	Requerido. ID de la `FiscalEntity` (`fe_…`).
`from` / `to`	`summary`	Requeridos. Periodos `YYYY-MM` inclusivos, rango ≤24 meses.
`from` / `to`	`items`	Requeridos. Fechas ISO sobre `issued_at`, rango ≤24 meses.
`cursor`	`items`	Cursor opaco de la página anterior.
`pageSize`	`items`	Tamaño de página, 1–200 (default 50).

#1. Riesgo de flujo de caja

GET/cfdi/risk/cash-flow/summary

GET/cfdi/risk/cash-flow/items

Marca discrepancias método-de-pago/forma-de-pago/REP que detonan requisitos de IVA del SAT, sobre CFDIs vigente tipo I/E (ambas direcciones). Tres categorías no mutuamente excluyentes (un CFDI puede caer en más de una):

Categoría	Descripción
`pue_forma_indefinida`	PUE con forma de pago `99` (por definir) — un PUE debe declarar una forma concreta.
`ppd_forma_invalida`	PPD con una forma de pago distinta de `99` — un PPD debe declarar `99`.
`ppd_sin_rep`	PPD que sigue `sin_pagar`/`parcial` — complemento de pago (REP) faltante o incompleto.

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).
`category`	string	Requerido en `items`. `pue_forma_indefinida` \| `ppd_forma_invalida` \| `ppd_sin_rep`.
`direction`	string	Opcional. `emitida` \| `recibida`.

curl "https://api.clarisfy.com/api/v1/cfdi/risk/cash-flow/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "period": "2026-04",
      "direction": "recibida",
      "category": "ppd_sin_rep",
      "invoice_count": 3,
      "total_amount": "4200.00"
    }
  ],
  "totals": {
    "pue_forma_indefinida": { "invoice_count": 0, "total_amount": "0" },
    "ppd_forma_invalida": { "invoice_count": 0, "total_amount": "0" },
    "ppd_sin_rep": { "invoice_count": 7, "total_amount": "9800.00" }
  }
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/cash-flow/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&category=ppd_sin_rep&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "issued_at": "2026-04-15T10:30:00+00:00",
      "folio": "00042",
      "counterparty_rfc": "PRVA850505CC3",
      "counterparty_name": "Proveedor A SA",
      "total": "800.00",
      "payment_method": "PPD",
      "payment_form": "99",
      "payment_status": "sin_pagar"
    }
  ],
  "next_cursor": null
}

Errores: 400 (identificador o rango inválido), 404 (sin conexión activa al RFC).

#2. Riesgo de cancelación

GET/cfdi/risk/cancellation/summary

GET/cfdi/risk/cancellation/items

Clasifica cada emitida cancelada (I/E) por qué tanto desincroniza periodos fiscales ya declarados (primer criterio que aplica, en orden):

Severidad	Descripción
`critico_cross_year`	Se canceló en un año calendario posterior al de emisión (Art. 29-A CFF; multa 5-10%).
`alto_cross_month`	Mismo año, cancelada en un mes calendario posterior (desincroniza el pago provisional).
`moderado_fin_mes`	Mismo mes, cancelada el día 28+ con emisión antes del día 20 (cierre de mes).

Cancelaciones dentro de 72 horas de la emisión (error de captura) se excluyen. period es el YYYY-MM de issued_at (el periodo en riesgo), no el mes de cancelación. El summary también trae rate: la tasa de cancelación de todas las emitidas I/E del rango (no solo las 3 severidades).

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).
`severity`	string	Requerido en `items`. `critico_cross_year` \| `alto_cross_month` \| `moderado_fin_mes`.

curl "https://api.clarisfy.com/api/v1/cfdi/risk/cancellation/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    { "period": "2026-04", "severity": "alto_cross_month", "invoice_count": 2, "total_amount": "3500.00" }
  ],
  "totals": {
    "critico_cross_year": { "invoice_count": 0, "total_amount": "0" },
    "alto_cross_month": { "invoice_count": 4, "total_amount": "7200.00" },
    "moderado_fin_mes": { "invoice_count": 0, "total_amount": "0" }
  },
  "rate": { "cancelled_count": 6, "issued_count": 120, "cancellation_rate": 0.05 }
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/cancellation/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&severity=alto_cross_month&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "folio": "00042",
      "issued_at": "2026-04-15T10:30:00+00:00",
      "cancelled_at": "2026-05-20T12:00:00+00:00",
      "counterparty_rfc": "ACME920101AA1",
      "counterparty_name": "Cliente ACME SA",
      "total": "2000.00",
      "severity": "alto_cross_month"
    }
  ],
  "next_cursor": null
}

Errores: 400 (identificador, to antes de from, o rango >24 meses), 404 (sin conexión activa al RFC).

#3. Retenciones ISR/IVA

GET/cfdi/risk/retentions/summary

GET/cfdi/risk/retentions/items

Suma las retenciones ISR (taxCode 001) e IVA (002) que los propios CFDIs declaran, por periodo y dirección. No compara contra lo declarado ante el SAT — solo expone lo que reportan los CFDIs. Alcance: vigente, tipo I/E, ambas direcciones.

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).
`taxCode`	string	Requerido en `items`. `001` (ISR) \| `002` (IVA).
`direction`	string	Opcional. `emitida` \| `recibida`.

curl "https://api.clarisfy.com/api/v1/cfdi/risk/retentions/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    { "period": "2026-04", "direction": "emitida", "tax_code": "002", "retained_amount": "160.00", "invoice_count": 3 }
  ],
  "totals": {
    "emitida": { "isr": "500.00", "iva": "320.00" },
    "recibida": { "isr": "0", "iva": "0" }
  }
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/retentions/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&taxCode=002&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "folio": "00042",
      "issued_at": "2026-04-15T10:30:00+00:00",
      "direction": "recibida",
      "counterparty_rfc": "PRVA850505CC3",
      "counterparty_name": "Proveedor A SA",
      "total": "800.00",
      "retained_amount": "64.00"
    }
  ],
  "next_cursor": null
}

Errores: 400 (identificador o rango inválido), 404 (sin conexión activa al RFC).

#4. EFOS (69-B)

GET/cfdi/risk/efos/summary

GET/cfdi/risk/efos/items

Marca las CFDIs recibidas cuyo emisor está en la lista negra 69-B del SAT (EFOS — Empresas que Facturan Operaciones Simuladas). Alcance: direction=recibida, vigente, tipo I/E.

`listing_status`	Severidad	Descripción
`definitivo`	Crítico	Publicación definitiva en el 69-B.
`presunto`	Alto	Publicación presunta, aún no definitiva.

desvirtuado/sentencia_favorable se excluyen — el contribuyente ya se deslindó ante el SAT. El 69-B se actualiza periódicamente y un proveedor puede entrar o salir de la lista en cualquier momento, así que el resultado refleja el estado actual.

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).
`status`	string	Requerido en `items`. `definitivo` \| `presunto`.

curl "https://api.clarisfy.com/api/v1/cfdi/risk/efos/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    { "period": "2026-04", "listing_status": "definitivo", "invoice_count": 2, "total_amount": "12000.00" }
  ],
  "totals": {
    "definitivo": { "invoice_count": 3, "total_amount": "18500.00" },
    "presunto": { "invoice_count": 0, "total_amount": "0" }
  },
  "supplier_count": 2
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/efos/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&status=definitivo&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "folio": "00042",
      "issued_at": "2026-04-15T10:30:00+00:00",
      "emisor_rfc": "EFOS850505CC3",
      "emisor_name": "Proveedor Simulado SA",
      "legal_name": "Proveedor Simulado SA de CV",
      "listing_status": "definitivo",
      "listed_at": "2025-11-03",
      "total": "8000.00"
    }
  ],
  "next_cursor": null
}

Errores: 400 (identificador o rango inválido), 404 (sin conexión activa al RFC).

#5. Concentración de clientes

GET/cfdi/risk/client-concentration

GET/cfdi/risk/client-concentration/items

Qué tan dependiente es el ingreso de pocos clientes. Rankea los receptores por % de ingresos = share del total de CFDIs emitidos tipo I vigentes en el rango (excluye P/N/E — no son ingreso de venta). Este summary no sigue la forma items+totals del resto: devuelve directamente severity, top1_pct/top3_pct y la lista clients (orden total desc, máx. 100).

severity (umbrales de negocio, no ley): critico si un cliente ≥ 40% del ingreso; si no, alto si el top-3 ≥ 60%; si no, ok. Si total_revenue es 0, severity="ok" y clients=[].

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).
`rfc`	string	Requerido en `items`. RFC del receptor (cliente) a filtrar.

curl "https://api.clarisfy.com/api/v1/cfdi/risk/client-concentration?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "severity": "alto",
  "top1_pct": 42.5,
  "top3_pct": 71.0,
  "total_revenue": "280000.00",
  "clients": [
    { "rfc": "ACME920101AA1", "name": "Cliente ACME SA", "total": "120000.00", "pct": 42.5, "invoice_count": 12 }
  ]
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/client-concentration/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&rfc=ACME920101AA1&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    { "cfdi_uuid": "12345678-1234-1234-1234-123456789abc", "issued_at": "2026-04-15T10:30:00+00:00", "folio": "00042", "total": "8000.00" }
  ],
  "next_cursor": null
}

Errores: 400 (identificador, to antes de from, o rango >24 meses), 404 (sin conexión activa al RFC).

#6. Deducciones en riesgo

GET/cfdi/risk/deductions/summary

GET/cfdi/risk/deductions/items

Gastos (CFDIs recibidos I/E vigentes) con un problema de deducibilidad detectable desde el CFDI. Dos categorías mutuamente excluyentes:

Categoría	Descripción
`efectivo_mayor_2000`	`payment_form='01'` (Efectivo) y `total > $2,000 MXN` → no deducible (Art. 27-III LISR).
`forma_no_sustentada`	`payment_form IS NULL OR '99'` → medio de pago no sustentado, riesgo de deducibilidad.

categories en el summary trae siempre las dos (incluida la de conteo cero) para que puedas representar ambas categorías.

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).
`category`	string	Requerido en `items`. `efectivo_mayor_2000` \| `forma_no_sustentada`.

curl "https://api.clarisfy.com/api/v1/cfdi/risk/deductions/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "categories": [
    { "category": "efectivo_mayor_2000", "invoice_count": 3, "total": "9800.00" },
    { "category": "forma_no_sustentada", "invoice_count": 4, "total": "5000.00" }
  ],
  "totals": { "invoice_count": 7, "total": "14800.00" }
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/deductions/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&category=efectivo_mayor_2000&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "issued_at": "2026-04-15T10:30:00+00:00",
      "folio": "00042",
      "counterparty_rfc": "PRVA850505CC3",
      "counterparty_name": "Proveedor A SA",
      "total": "3500.00",
      "payment_form": "01"
    }
  ],
  "next_cursor": null
}

Errores: 400 (identificador o rango inválido), 404 (sin conexión activa al RFC).

#7. Discrepancia de ISR retenido

GET/cfdi/risk/isr-withholding/summary

GET/cfdi/risk/isr-withholding/items

CFDIs recibidos I/E vigentes que traen un nodo de retención de ISR (tax_code='001') cuyo monto retenido no cuadra con la tasa esperada. Supuesto explícito: la tasa esperada es 10% (retención de ISR por servicios profesionales / arrendamiento de PF, Art. 106/116 LISR). Se marca cuando |retenido − 0.10 × subtotal| > $1 (tolerancia de redondeo). No compara contra lo declarado/enterado ante el SAT — solo el XML contra la tasa esperada.

#Parámetros

Parámetro	Tipo	Descripción
`from` / `to`	string	Requeridos (`summary`: `YYYY-MM`; `items`: fecha ISO).

curl "https://api.clarisfy.com/api/v1/cfdi/risk/isr-withholding/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "invoice_count": 3,
  "total_expected": "500.00",
  "total_retained": "640.00",
  "total_discrepancy": "140.00",
  "expected_rate": "0.10"
}

curl "https://api.clarisfy.com/api/v1/cfdi/risk/isr-withholding/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "issued_at": "2026-04-15T10:30:00+00:00",
      "folio": "00042",
      "counterparty_rfc": "PRVA850505CC3",
      "counterparty_name": "Proveedor A SA",
      "subtotal": "1000.00",
      "isr_retained": "150.00",
      "isr_expected": "100.00",
      "diff": "50.00"
    }
  ],
  "next_cursor": null
}

Errores: 400 (identificador, to antes de from, o rango >24 meses), 404 (sin conexión activa al RFC).