Get Metrics

Retrieve financial metrics for a specific period

GET /api/metrics

Get Metrics

cURL

curl --request GET \
  --url https://api.example.com/api/metrics

200

{
  "period": {
    "id": "<string>",
    "start": "<string>",
    "end": "<string>"
  },
  "flujo": {
    "ingresos_cobrados": 123,
    "egresos_pagados": 123,
    "flujo_neto": 123,
    "ingresos_cobrados_sin_conciliar": 123,
    "egresos_pagados_sin_conciliar": 123
  },
  "devengado": {
    "ingresos_devengados": 123,
    "egresos_devengados": 123,
    "resultado_devengado": 123
  },
  "impuestos": {
    "iva_trasladado": {
      "cobrado": 123,
      "devengado": 123,
      "pagado": 123
    },
    "iva_acreditable": {
      "cobrado": 123,
      "devengado": 123,
      "pagado": 123
    },
    "retenciones_iva": {
      "cobrado": 123,
      "devengado": 123,
      "pagado": 123
    },
    "retenciones_isr": {
      "cobrado": 123,
      "devengado": 123,
      "pagado": 123
    }
  },
  "pendientes": {
    "por_cobrar": 123,
    "por_pagar": 123
  }
}

Authentication

This endpoint requires authentication. Include your access token in the Authorization header.

Authorization: Bearer YOUR_ACCESS_TOKEN

Query Parameters

profile_id · string

Filter metrics by profile ID

mes · number

Month to retrieve metrics for (1-12)

año · number

Year to retrieve metrics for

regimen_fiscal · string

Filter by tax regime code

Response

period · object

Period information

Show Period

id · string

Period identifier

start · string

Period start date in ISO format

end · string

Period end date in ISO format

flujo · object

Cash flow metrics (base de flujo - actual payments)

Show Flujo

ingresos_cobrados · number

Income collected (actual cash received)

egresos_pagados · number

Expenses paid (actual cash paid out)

flujo_neto · number

Net cash flow (ingresos_cobrados - egresos_pagados)

ingresos_cobrados_sin_conciliar · number

Part of collected income from payment complements without related PPD invoice

egresos_pagados_sin_conciliar · number

Part of paid expenses from payment complements without related PPD expense

devengado · object

Accrual metrics (base devengada - invoice date basis)

Show Devengado

ingresos_devengados · number

Accrued income (total from invoices issued)

egresos_devengados · number

Accrued expenses (total from expenses received)

resultado_devengado · number

Accrual result (ingresos_devengados - egresos_devengados)

impuestos · object

Tax metrics

Show Impuestos

iva_trasladado · object

IVA charged on invoices issued

Show ImpuestosItem

cobrado · number

Collected amount

devengado · number

Accrued amount

pagado · number

Paid amount

iva_acreditable · object

IVA creditable from expenses

Show ImpuestosItem

cobrado · number

Collected amount

devengado · number

Accrued amount

pagado · number

Paid amount

retenciones_iva · object

IVA withholdings

Show ImpuestosItem

cobrado · number

Collected amount

devengado · number

Accrued amount

pagado · number

Paid amount

retenciones_isr · object

ISR withholdings

Show ImpuestosItem

cobrado · number

Collected amount

devengado · number

Accrued amount

pagado · number

Paid amount

pendientes · object

Pending amounts

Show Pendientes

por_cobrar · number

Accounts receivable (invoices not yet collected)

por_pagar · number

Accounts payable (expenses not yet paid)

Example Request

curl -X GET "https://api.contafy.com/api/metrics?profile_id=prof_123&mes=3&año=2026" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response

{
  "period": {
    "id": "period_2026_03",
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "flujo": {
    "ingresos_cobrados": 150000.00,
    "egresos_pagados": 80000.00,
    "flujo_neto": 70000.00,
    "ingresos_cobrados_sin_conciliar": 0,
    "egresos_pagados_sin_conciliar": 0
  },
  "devengado": {
    "ingresos_devengados": 200000.00,
    "egresos_devengados": 100000.00,
    "resultado_devengado": 100000.00
  },
  "impuestos": {
    "iva_trasladado": {
      "cobrado": 24000.00,
      "devengado": 32000.00
    },
    "iva_acreditable": {
      "pagado": 12800.00,
      "devengado": 16000.00
    },
    "retenciones_iva": {
      "cobrado": 1500.00,
      "devengado": 2000.00
    },
    "retenciones_isr": {
      "cobrado": 1000.00,
      "devengado": 1333.33
    }
  },
  "pendientes": {
    "por_cobrar": 50000.00,
    "por_pagar": 20000.00
  }
}

Error Responses

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing access token"
}

404 Not Found

When the user has no subscription or no data for the specified period, the endpoint returns default metrics with all values set to zero.

{
  "period": { "id": "", "start": "", "end": "" },
  "flujo": {
    "ingresos_cobrados": 0,
    "egresos_pagados": 0,
    "flujo_neto": 0
  },
  "devengado": {
    "ingresos_devengados": 0,
    "egresos_devengados": 0,
    "resultado_devengado": 0
  },
  "impuestos": {
    "iva_trasladado": {},
    "iva_acreditable": {},
    "retenciones_iva": {},
    "retenciones_isr": {}
  },
  "pendientes": {
    "por_cobrar": 0,
    "por_pagar": 0
  }
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Notes

• Metrics are calculated based on two accounting methods:
  • Flujo (Cash basis): Based on actual payment dates from payment complements
  • Devengado (Accrual basis): Based on invoice dates
• Tax metrics include both collected/paid amounts and accrued amounts
• If no period parameters are provided, metrics for the current month are returned
• The endpoint handles missing data gracefully by returning zero values