Skip to main content

​
GET /api/invoices/metrics

Retrieves aggregated metrics and statistics for invoices and expenses, including totals, tax amounts, and payment status summaries. Supports filtering by profile and time period.

​
Authentication

Requires Bearer token authentication. The token must be included in the Authorization header.

​
Query Parameters

​
profileId
string
Filter metrics by profile UUID. If not provided, returns metrics across all user’s profiles.
​
mes
number
Filter by month (1-12). Must be provided together with año for period-specific metrics.
​
año
number
Filter by year. Valid range: 2001-2099. Must be provided together with mes for period-specific metrics.

​
Response

​
filters
object
Applied filters
​
profileId
string
Profile UUID used for filtering (null if not specified)
​
mes
number
Month used for filtering (null if not specified)
​
año
number
Year used for filtering (null if not specified)
​
period_id
string
UUID of the fiscal period (only returned when profileId, mes, and año are provided). Used for creating manual income entries.
​
metrics
object
Aggregated metrics data
​
ingresos
object
Income metrics
​
total
number
Total income amount
​
subtotal
number
Subtotal before taxes
​
iva
number
Total IVA amount
​
retencionIVA
number
Total IVA withholdings
​
retencionISR
number
Total ISR withholdings
​
count
number
Number of invoices
​
gastos
object
Expense metrics
​
total
number
Total expense amount
​
subtotal
number
Subtotal before taxes
​
iva
number
Total IVA amount
​
ivaDeducible
number
Deductible IVA amount
​
retencionIVA
number
Total IVA withholdings
​
retencionISR
number
Total ISR withholdings
​
count
number
Number of expenses
​
cobros
object
Payment collections metrics (from payment complements)
​
total
number
Total amount collected
​
count
number
Number of payment complements received
​
pagos
object
Payment disbursements metrics (from payment complements)
​
total
number
Total amount paid
​
count
number
Number of payment complements issued
​
utilidadBruta
number
Gross profit (ingresos.total - gastos.total)
​
ivaFavorContra
number
Net IVA position (ingresos.iva - gastos.ivaDeducible)
​
regimenFiscal
object
Breakdown by fiscal regime (only when profileId is specified)
​
[regimeCode]
object
Metrics for specific regime code (e.g., “612”, “605”)
​
ingresos
number
Income for this regime
​
gastos
number
Expenses for this regime
​
count
number
Number of transactions

​
Error Codes

​
400
error
Bad Request - Invalid parameters
  • Month must be between 1 and 12
  • Year must be between 2001 and 2099
​
401
error
Unauthorized - User not authenticated
​
500
error
Internal Server Error - Error calculating metrics

​
Example Request (All-Time Metrics)

curl -X GET "https://api.tresacontafy.com/api/invoices/metrics" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Request (Period-Specific Metrics)

curl -X GET "https://api.tresacontafy.com/api/invoices/metrics?profileId=550e8400-e29b-41d4-a716-446655440000&mes=3&año=2024" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response (Period-Specific)

{
  "filters": {
    "profileId": "550e8400-e29b-41d4-a716-446655440000",
    "mes": 3,
    "año": 2024
  },
  "period_id": "9f3e5680-9647-62fg-c936-g29he3h12cg9",
  "metrics": {
    "ingresos": {
      "total": 116000.00,
      "subtotal": 100000.00,
      "iva": 16000.00,
      "retencionIVA": 1066.67,
      "retencionISR": 1000.00,
      "count": 10
    },
    "gastos": {
      "total": 34800.00,
      "subtotal": 30000.00,
      "iva": 4800.00,
      "ivaDeducible": 4800.00,
      "retencionIVA": 0.00,
      "retencionISR": 0.00,
      "count": 5
    },
    "cobros": {
      "total": 58000.00,
      "count": 8
    },
    "pagos": {
      "total": 17400.00,
      "count": 3
    },
    "utilidadBruta": 81200.00,
    "ivaFavorContra": 11200.00,
    "regimenFiscal": {
      "612": {
        "ingresos": 116000.00,
        "gastos": 0.00,
        "count": 10
      },
      "601": {
        "ingresos": 0.00,
        "gastos": 23200.00,
        "count": 3
      },
      "605": {
        "ingresos": 0.00,
        "gastos": 11600.00,
        "count": 2
      }
    }
  }
}

​
Example Response (All-Time, All Profiles)

{
  "filters": {
    "profileId": null,
    "mes": null,
    "año": null
  },
  "period_id": null,
  "metrics": {
    "ingresos": {
      "total": 580000.00,
      "subtotal": 500000.00,
      "iva": 80000.00,
      "retencionIVA": 5333.33,
      "retencionISR": 5000.00,
      "count": 50
    },
    "gastos": {
      "total": 174000.00,
      "subtotal": 150000.00,
      "iva": 24000.00,
      "ivaDeducible": 24000.00,
      "retencionIVA": 0.00,
      "retencionISR": 0.00,
      "count": 25
    },
    "cobros": {
      "total": 290000.00,
      "count": 40
    },
    "pagos": {
      "total": 87000.00,
      "count": 15
    },
    "utilidadBruta": 406000.00,
    "ivaFavorContra": 56000.00,
    "regimenFiscal": {}
  }
}

​
Example Response (Invalid Month)

{
  "error": "Parámetro inválido",
  "message": "El mes debe ser un número entre 1 y 12"
}

​
Example Response (Invalid Year)

{
  "error": "Parámetro inválido",
  "message": "El año debe ser un número válido"
}

​
Notes

  • When no filters are provided, returns aggregated metrics across all profiles and time periods for the authenticated user
  • The period_id is only returned when all three parameters (profileId, mes, año) are provided, and is used by the frontend to enable manual income entry
  • utilidadBruta (gross profit) = total income - total expenses
  • ivaFavorContra (IVA position) = IVA charged on income - deductible IVA on expenses
    • Positive value indicates IVA payable to tax authority
    • Negative value indicates IVA refund due from tax authority
  • Fiscal regime breakdown (regimenFiscal) is only provided when filtering by a specific profile
  • Metrics include both PUE (paid in full) and PPD (installment) invoices
  • Payment complements are tracked separately in cobros (collections) and pagos (disbursements)

Build docs developers (and LLMs) love

Get started for freeTalk to us