Skip to main content

Portal Dashboard

Executive dashboard with KPIs, charts, monthly billing trends, and variation analysis for the provider portal.

GET/apidev/v1/reports/portal/dashboard
PermissionAPICLI_RPTPORTAL_DASHBOARD
Rate Limit10 req/min (sliding window)
Cache120s (2 min)

Overview​

Returns aggregated data about invoice states, settlements, top providers, and variation trends. Designed to power executive dashboards with a single API call.

  • Period presets — use periodo for quick ranges (30d, 90d, 6m, 1a) or custom with explicit dates
  • Provider filtering — optionally restrict to a single provider
  • Rich KPIs — pending invoices, approval rate, average variation, accumulated difference, and more
  • Chart-ready data — invoices by state, monthly billing comparison, variation trends, top providers, settlements by state
Date range limit (custom mode only)

Period presets (30d, 90d, 6m, 1a) have no extra restriction — 1a covers a full year. When sending custom dates (periodo=custom or omitted), both startdate and enddate are required and the range must not exceed 93 days.

Query Parameters​

ParameterTypeRequiredDefaultDescription
periodostringNo30dPeriod preset: 30d, 90d, 6m, 1a, custom
startdatestringNo—ISO 8601 start date. Required when periodo=custom
enddatestringNo—ISO 8601 end date. Required when periodo=custom. Max range 93 days
provider_idstringNoAllFilter by single provider ID

Code Examples​

curl -s "https://$TENANT/apidev/v1/reports/portal/dashboard?periodo=90d" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

Response Fields​

KPIs​

FieldTypeDescription
pending_invoicesnumberCount of invoices pending review
review_invoicesnumberCount of invoices currently in review
approval_ratenumberApproval rate as percentage (0–100)
avg_variationnumberAverage variation percentage between system and provider amounts
active_settlementsnumberCount of open/active settlements
accumulated_differencenumberNet accumulated difference (system − provider)
active_providersnumberCount of providers with activity in the period
total_invoicednumberTotal system-invoiced amount

Charts​

FieldTypeDescription
charts.invoices_by_state[].statestringState code
charts.invoices_by_state[].namestringHuman-readable state name
charts.invoices_by_state[].countnumberNumber of invoices in this state
charts.invoices_by_state[].amountnumberTotal amount for this state
charts.monthly_billing[].monthstringMonth in YYYY-MM format
charts.monthly_billing[].systemnumberSystem-calculated billing total
charts.monthly_billing[].providernumberProvider-reported billing total
charts.variation_trend[].monthstringMonth in YYYY-MM format
charts.variation_trend[].variation_pctnumberVariation percentage for the month
charts.top_providers[].provider_idstringProvider identifier
charts.top_providers[].provider_namestringProvider display name
charts.top_providers[].amountnumberTotal invoiced amount
charts.top_providers[].countnumberNumber of invoices
charts.settlements_by_state[].statestringSettlement state code
charts.settlements_by_state[].namestringHuman-readable settlement state name
charts.settlements_by_state[].countnumberNumber of settlements
charts.settlements_by_state[].amountnumberTotal settlement amount

Example Response​

{
  "success": true,
  "data": {
    "kpis": {
      "pending_invoices": 47,
      "review_invoices": 12,
      "approval_rate": 82.5,
      "avg_variation": 3.2,
      "active_settlements": 8,
      "accumulated_difference": 15420.75,
      "active_providers": 23,
      "total_invoiced": 1285600.00
    },
    "charts": {
      "invoices_by_state": [
        { "state": "100", "name": "Pending", "count": 47, "amount": 234500.00 },
        { "state": "101", "name": "In Review", "count": 12, "amount": 89200.00 },
        { "state": "102", "name": "Approved", "count": 185, "amount": 845300.00 },
        { "state": "103", "name": "Rejected", "count": 9, "amount": 42100.00 }
      ],
      "monthly_billing": [
        { "month": "2026-01", "system": 412000.00, "provider": 418500.00 },
        { "month": "2026-02", "system": 438000.00, "provider": 441200.00 },
        { "month": "2026-03", "system": 435600.00, "provider": 440800.00 }
      ],
      "variation_trend": [
        { "month": "2026-01", "variation_pct": 1.58 },
        { "month": "2026-02", "variation_pct": 0.73 },
        { "month": "2026-03", "variation_pct": 1.19 }
      ],
      "top_providers": [
        { "provider_id": "504210987600", "provider_name": "Transporte Rápido S.A.", "amount": 245800.00, "count": 42 },
        { "provider_id": "504210987601", "provider_name": "Logística del Norte", "amount": 198300.00, "count": 35 },
        { "provider_id": "504210987602", "provider_name": "ServiFlota Express", "amount": 167500.00, "count": 28 }
      ],
      "settlements_by_state": [
        { "state": "200", "name": "Open", "count": 5, "amount": 312400.00 },
        { "state": "201", "name": "In Review", "count": 3, "amount": 178200.00 },
        { "state": "202", "name": "Closed", "count": 18, "amount": 795000.00 }
      ]
    }
  }
}

Errors​

CodeHTTPDescription
BAD_REQUEST400Missing required headers or invalid periodo value
VALIDATION_ERROR400Invalid date format, custom date range exceeds 93 days
INVALID_DATE_RANGE400Custom range exceeds 93 days or only one of startdate/enddate provided
UNAUTHORIZED401Invalid or expired JWT / API Key
FORBIDDEN403User lacks APICLI_RPTPORTAL_DASHBOARD permission
RATE_LIMITED429Exceeded 10 req/min
INTERNAL_ERROR500Unexpected server error