#Hechos financieros

El modelo de hechos financieros convierte los CFDIs de una Fiscal Entity en una serie de devengo por periodo de efecto (period-of-effect), distinta de los rollups de facturas vigentes: una factura I/E se cuenta en su mes de emisión aunque después se cancele (accrual), y una cancelación que cruza de mes genera una reversa (reversal) negativa en el mes en que ocurrió.

#Resumen por periodo con reversas

Devuelve los hechos financieros del RFC en un rango de periodos YYYY-MM:

• accrual (devengo): toda factura I/E emitida en el periodo, incluidas las que después se cancelaron — congela la serie como se declaró. origin_period == period, monto positivo.
• reversal (reversa): factura I/E cancelada en el periodo cuyo mes de emisión fue anterior (cancelación cruza-periodo). Monto negativo, con origin_period = el mes de emisión reversado. Las cancelaciones intra-periodo netean solas contra su devengo y no generan reversa.

net_by_period agrega el neto de cada periodo (Σ devengos + Σ reversas). Alcance: tipo I/E (excluye P/N/T), ambas direcciones, bucketing en America/Mexico_City.

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

{
  "items": [
    {
      "period": "2026-01",
      "fact_type": "accrual",
      "origin_period": "2026-01",
      "direction": "emitida",
      "cfdi_type": "I",
      "invoice_count": 2,
      "total_amount": "100000.00"
    },
    {
      "period": "2026-03",
      "fact_type": "reversal",
      "origin_period": "2026-01",
      "direction": "emitida",
      "cfdi_type": "I",
      "invoice_count": 1,
      "total_amount": "-100000.00"
    }
  ],
  "net_by_period": [
    { "period": "2026-01", "accrual_total": "100000.00", "reversal_total": "0", "net": "100000.00" },
    { "period": "2026-03", "accrual_total": "0", "reversal_total": "-100000.00", "net": "-100000.00" }
  ]
}

#Errores

#Drill-down: CFDIs detrás de un devengo/reversa

Lista los CFDIs individuales detrás de una fila de /cfdi/financial-facts, con el mismo criterio exacto (drill-down al detalle por factura):

• factType=accrual: facturas emitidas en el rango (por issued_at), incluidas las canceladas después.
• factType=reversal: facturas canceladas en el rango (por cancelled_at) cuyo mes de emisión fue anterior al de cancelación (cruza-periodo).

Paginación por cursor, igual que /cfdi/invoices. from/to aquí son fechas, no periodos.

curl "https://api.clarisfy.com/api/v1/cfdi/financial-facts/items?fiscalEntityId=fe_9a1c2b3d4e5f6071&factType=reversal&cfdiType=I&from=2026-01-01T00:00:00Z&to=2026-06-30T23:59:59Z" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "cfdi_uuid": "12345678-1234-1234-1234-123456789abc",
      "issued_at": "2026-01-15T10:30:00+00:00",
      "cancelled_at": "2026-03-04T09:00:00+00:00",
      "folio": "00042",
      "direction": "emitida",
      "counterparty_rfc": "ACME920101AA1",
      "counterparty_name": "Cliente A SA",
      "total": "100000.00"
    }
  ],
  "next_cursor": null
}

#Errores

#Exportación CSV del detalle

Descarga el detalle por factura del reporte de hechos financieros en CSV, listo para Excel/Sheets/ERP. Usa el mismo predicado que /cfdi/financial-facts/items (misma tz America/Mexico_City, misma exclusión intra-periodo), pero sin paginación y sin los filtros factType/cfdiType/direction: trae todo el rango — devengo y reversa, ambos tipos I/E, ambas direcciones. Una misma factura puede aparecer dos veces (devengo en su mes de emisión y reversa en su mes de cancelación) si ambos caen en el rango.

curl "https://api.clarisfy.com/api/v1/cfdi/financial-facts/export?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01&to=2026-06" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -o reporte-financiero.csv

La respuesta no es JSON: es un archivo text/csv en streaming con Content-Disposition: attachment; filename="reporte-financiero_{rfc}_{from}_{to}.csv". Columnas, en orden:

#Errores

#Exportación del reporte financiero anual (esquema interno)

Serializa los hechos financieros de un ejercicio fiscal completo a un archivo XML en un esquema interno (experimental): contextos por periodo y contexto anual (1-ene a 31-dic), cada uno con el RFC del contribuyente, la unidad en pesos (MXN) y los montos anuales netos (devengo − reversa): ingresos (neto de emitidas tipo I) y costos (neto de recibidas tipo I/E).

curl "https://api.clarisfy.com/api/v1/cfdi/xbrl/financial-report/export?fiscalEntityId=fe_9a1c2b3d4e5f6071&year=2026" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe" \
  -o reporte.xml

La respuesta no es JSON: es un archivo application/xml (adjunto), listo para revisión — no para presentación directa.

#Errores