#Resúmenes y analítica

Estos endpoints devuelven resúmenes y analítica de los CFDIs de una Fiscal Entity: resumen mensual, trazabilidad histórica, performance financiero mensual (y su serie multi-mes), análisis de conceptos y rankings de proveedores/clientes.

Todos cuelgan de https://api.clarisfy.com/v1/cfdi/ y son tenant-gated: tu organización debe tener una conexión activa al RFC (fiscalEntityId), o el endpoint responde 404.

#Resumen mensual del RFC

GET/cfdi/summary

Conteos y totales agregados de un periodo específico.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`year`	integer	Requerido. Año del periodo (2010–2100).
`month`	integer	Requerido. Mes del periodo (1–12).

curl "https://api.clarisfy.com/v1/cfdi/summary?fiscalEntityId=fe_9a1c2b3d4e5f6071&year=2026&month=6" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "period_year": 2026,
  "period_month": 6,
  "issued_count": 42,
  "issued_total": "580000.00",
  "issued_cancelled_count": 3,
  "issued_cancelled_total": "12500.00",
  "received_count": 61,
  "received_total": "310450.75",
  "payment_count": 18,
  "payroll_count": 8,
  "distinct_suppliers": 22,
  "distinct_clients": 15,
  "efos_supplier_count": 1,
  "last_refreshed_at": "2026-07-24T04:05:11+00:00"
}

Campo	Tipo	Descripción
`issued_count` / `issued_total`	integer / string	CFDIs emitidos vigentes (tipo I/E) y su suma.
`issued_cancelled_count` / `issued_cancelled_total`	integer / string	Emitidos cancelados en el periodo.
`received_count` / `received_total`	integer / string	CFDIs recibidos vigentes.
`payment_count`	integer	Complementos de pago (tipo P) del periodo.
`payroll_count`	integer	CFDIs de nómina (tipo N) del periodo.
`distinct_suppliers`	integer	Emisores distintos entre los recibidos.
`distinct_clients`	integer	Receptores distintos entre los emitidos.
`efos_supplier_count`	integer	Proveedores del periodo marcados en la lista 69-B (EFOS).
`last_refreshed_at`	string	Última vez que se refrescó este rollup (ISO 8601).

Montos (*_total) son NUMERIC serializados como string.

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado.
`404`	No hay resumen para ese periodo (sincroniza primero), o tu organización no tiene conexión activa al RFC.

#Trazabilidad mensual

GET/cfdi/summary/monthly

Serie mensual de conteos, del mes más reciente al más antiguo: emitidas y recibidas, vigentes vs. canceladas, con sus totales. Pensado para la trazabilidad histórica en reportes.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`months`	integer	Cuántos meses regresar (1–36, por defecto 6).

curl "https://api.clarisfy.com/v1/cfdi/summary/monthly?fiscalEntityId=fe_9a1c2b3d4e5f6071&months=3" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

[
  {
    "period_year": 2026,
    "period_month": 6,
    "issued_count": 42,
    "issued_total": "580000.00",
    "issued_cancelled_count": 3,
    "issued_cancelled_total": "12500.00",
    "received_count": 61,
    "received_total": "310450.75",
    "received_cancelled_count": 2
  },
  {
    "period_year": 2026,
    "period_month": 5,
    "issued_count": 38,
    "issued_total": "512300.00",
    "issued_cancelled_count": 1,
    "issued_cancelled_total": "4100.00",
    "received_count": 55,
    "received_total": "289900.00",
    "received_cancelled_count": 0
  }
]

Arreglo de filas MonthlySummaryRow, ordenado de más reciente a más antiguo. Montos (*_total) son NUMERIC serializados como string.

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado.
`404`	Tu organización no tiene conexión activa al RFC.

#Reporte de performance mensual

GET/cfdi/performance

Estado de resultados del periodo derivado de CFDIs: revenue (emitidos tipo I vigentes), cogs (recibidos tipo E vigentes), ebitda = revenue - cogs - opex.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`year`	integer	Requerido. Año del periodo (2010–2100).
`month`	integer	Requerido. Mes del periodo (1–12).

curl "https://api.clarisfy.com/v1/cfdi/performance?fiscalEntityId=fe_9a1c2b3d4e5f6071&year=2026&month=6" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "period_year": 2026,
  "period_month": 6,
  "revenue": "580000.00",
  "cogs": "310450.75",
  "opex": "45000.00",
  "ebitda": "224549.25",
  "net_income": "224549.25",
  "issued_count": 42,
  "received_count": 61,
  "report_status": "preliminar",
  "last_refreshed_at": "2026-07-24T04:05:11+00:00"
}

Campo	Tipo	Descripción
`revenue`	string	Suma de emitidos tipo I vigentes. NUMERIC como string.
`cogs`	string	Suma de recibidos tipo E vigentes. NUMERIC como string.
`opex`	string	Gasto operativo estimado. NUMERIC como string.
`ebitda`	string	`revenue - cogs - opex`. NUMERIC como string.
`net_income`	string	Resultado neto estimado. NUMERIC como string.
`report_status`	string	`preliminar` (dentro de 30 días del cierre) o `final`.

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado.
`404`	No hay performance para ese periodo, o tu organización no tiene conexión activa al RFC.

#Serie de performance (varios meses)

GET/cfdi/performance/series

Los mismos campos del endpoint anterior, pero para varios meses en una sola llamada, del mes más reciente al más antiguo. Úsalo para graficar tendencias o comparar años en lugar de pedir /cfdi/performance mes por mes.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`months`	integer	Cuántos meses hacia atrás (1–120). Default `36`.

curl "https://api.clarisfy.com/v1/cfdi/performance/series?fiscalEntityId=fe_9a1c2b3d4e5f6071&months=24" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

[
  {
    "period_year": 2026,
    "period_month": 6,
    "revenue": "580000.00",
    "cogs": "310450.75",
    "opex": "45000.00",
    "ebitda": "224549.25",
    "net_income": "224549.25",
    "issued_count": 42,
    "received_count": 61,
    "report_status": "preliminar",
    "last_refreshed_at": "2026-07-24T04:05:11+00:00"
  },
  {
    "period_year": 2026,
    "period_month": 5,
    "revenue": "510300.00",
    "cogs": "288120.40",
    "opex": "45000.00",
    "ebitda": "177179.60",
    "net_income": "177179.60",
    "issued_count": 38,
    "received_count": 54,
    "report_status": "final",
    "last_refreshed_at": "2026-07-24T04:05:11+00:00"
  }
]

Cada elemento tiene exactamente los mismos campos que /cfdi/performance.

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado.
`404`	Tu organización no tiene conexión activa al RFC.
`422`	`months` fuera del rango 1–120.

Un RFC conectado pero sin meses procesados devuelve 200 con un arreglo vacío, no 404.

#Análisis de conceptos

GET/cfdi/concepts/analytics

Agrega las líneas ("conceptos") de los CFDIs del RFC en el rango from/to, agrupadas por (product_service_code, description, counterparty_rfc), ordenadas por total_amount descendente y limitadas a limit grupos. Solo cuenta CFDIs vigente (los cancelados se excluyen) y excluye nómina (tipo N).

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`from`	string (datetime)	Requerido. Inicio del rango sobre `issued_at`.
`to`	string (datetime)	Requerido. Fin del rango sobre `issued_at`.
`direction`	string	Opcional. `emitida` o `recibida`.
`limit`	integer	Máximo de grupos a devolver (1–100, por defecto 20).

curl "https://api.clarisfy.com/v1/cfdi/concepts/analytics?fiscalEntityId=fe_9a1c2b3d4e5f6071&from=2026-01-01T00:00:00Z&to=2026-07-01T00:00:00Z&direction=recibida&limit=20" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

{
  "items": [
    {
      "product_service_code": "01010101",
      "description": "Servicio profesional",
      "counterparty_rfc": "XAXX010101000",
      "total_amount": "50000.00000000",
      "total_quantity": "50.00000000",
      "invoice_count": 12,
      "line_count": 15
    }
  ],
  "totals": {
    "total_amount": "120000.00000000",
    "line_count": 80,
    "group_count": 34
  }
}

Campo	Tipo	Descripción
`items[].product_service_code`	string \| null	`ClaveProdServ` SAT del grupo.
`items[].description`	string	Descripción del concepto.
`items[].counterparty_rfc`	string	RFC de la contraparte (receptor en emitidas, emisor en recibidas).
`items[].total_amount`	string	Suma del grupo. NUMERIC como string.
`items[].total_quantity`	string	Cantidad acumulada. NUMERIC como string.
`items[].invoice_count`	integer	CFDIs distintos que incluyen el grupo.
`items[].line_count`	integer	Líneas ("conceptos") agregadas al grupo.
`totals`	object	Totales sobre todos los grupos que hacen match, no solo la página devuelta en `items`.

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado, o rango `from`/`to` mayor a 24 meses.
`404`	Tu organización no tiene conexión activa al RFC.

#Top proveedores del periodo

GET/cfdi/suppliers

Proveedores agregados por RFC emisor, ordenados por total_amount descendente. Cada fila incluye is_efos / efos_status: el flag de la lista 69-B (EFOS) publicada por el SAT.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`year`	integer	Requerido. Año del periodo (2010–2100).
`month`	integer	Requerido. Mes del periodo (1–12).
`limit`	integer	Máximo de filas (1–500, por defecto 50).

curl "https://api.clarisfy.com/v1/cfdi/suppliers?fiscalEntityId=fe_9a1c2b3d4e5f6071&year=2026&month=6&limit=50" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

[
  {
    "emisor_rfc": "PRVA850505CC3",
    "emisor_name_last": "Proveedor A SA de CV",
    "invoice_count": 14,
    "total_amount": "185000.50",
    "cancelled_count": 1,
    "last_invoice_at": "2026-06-28T09:15:00+00:00",
    "is_efos": false,
    "efos_status": null
  },
  {
    "emisor_rfc": "AAA080808HL8",
    "emisor_name_last": "Asesores en Avalúos SA de CV",
    "invoice_count": 3,
    "total_amount": "42000.00",
    "cancelled_count": 0,
    "last_invoice_at": "2026-06-10T11:00:00+00:00",
    "is_efos": true,
    "efos_status": "Definitivo"
  }
]

Campo	Tipo	Descripción
`emisor_rfc`	string	RFC del proveedor (emisor).
`emisor_name_last`	string \| null	Última razón social vista en sus CFDIs.
`invoice_count`	integer	CFDIs recibidos de este proveedor en el periodo.
`total_amount`	string	Suma de `total`. NUMERIC como string.
`cancelled_count`	integer	De esos, cuántos están cancelados.
`last_invoice_at`	string \| null	Fecha del CFDI más reciente (ISO 8601).
`is_efos`	boolean	`true` si el RFC aparece en la lista 69-B (EFOS) del SAT.
`efos_status`	string \| null	Situación en la lista 69-B (p. ej. `Definitivo`, `Presunto`). `null` si `is_efos` es `false`.

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado.
`404`	Tu organización no tiene conexión activa al RFC.

#Top clientes del periodo

GET/cfdi/clients

Espejo de /cfdi/suppliers pero agregando por RFC receptor. Útil para identificar concentración de ingresos.

Parámetro (query)	Tipo	Descripción
`fiscalEntityId`	string	Requerido. Identificador de la Fiscal Entity (`fe_…`).
`year`	integer	Requerido. Año del periodo (2010–2100).
`month`	integer	Requerido. Mes del periodo (1–12).
`limit`	integer	Máximo de filas (1–500, por defecto 50).

curl "https://api.clarisfy.com/v1/cfdi/clients?fiscalEntityId=fe_9a1c2b3d4e5f6071&year=2026&month=6&limit=50" \
  -H "Authorization: Bearer clf_live_secret_9K3mZ1pQ7rTx8vB4nH6dLwYe"

[
  {
    "receptor_rfc": "CLI900101XY2",
    "receptor_name_last": "Mi Cliente SA de CV",
    "invoice_count": 9,
    "total_amount": "220000.00",
    "cancelled_count": 0,
    "last_invoice_at": "2026-06-29T16:40:00+00:00"
  }
]

Campo	Tipo	Descripción
`receptor_rfc`	string	RFC del cliente (receptor).
`receptor_name_last`	string \| null	Última razón social vista en sus CFDIs.
`invoice_count`	integer	CFDIs emitidos a este cliente en el periodo.
`total_amount`	string	Suma de `total`. NUMERIC como string.
`cancelled_count`	integer	De esos, cuántos están cancelados.
`last_invoice_at`	string \| null	Fecha del CFDI más reciente (ISO 8601).

#Errores

Código HTTP	Causa
`400`	`fiscalEntityId` malformado.
`404`	Tu organización no tiene conexión activa al RFC.