Panel del Portal

Panel ejecutivo con KPIs, gráficos, tendencias de facturación mensual y análisis de variación para el portal de proveedores.

GET/apidev/v1/reports/portal/dashboard

PermisoAPICLI_RPTPORTALPROVEEDOR_DASHBOARD

Límite de solicitudes10 req/min (ventana deslizante)

Caché120s (2 min)

Resumen

Devuelve datos agregados sobre estados de facturas, liquidaciones, principales proveedores y tendencias de variación. Diseñado para alimentar paneles ejecutivos con una sola llamada a la API.

Presets de período — usá periodo para rangos rápidos (30d, 90d, 6m, 1a) o custom con fechas explícitas
Filtrado por proveedor — opcionalmente, restringí a un único proveedor
KPIs detallados — facturas pendientes, tasa de aprobación, variación promedio, diferencia acumulada y más
Datos listos para gráficos — facturas por estado, comparación de facturación mensual, tendencias de variación, principales proveedores, liquidaciones por estado

Límite del rango de fechas (solo modo personalizado)

Los presets de período (30d, 90d, 6m, 1a) no tienen restricción adicional — 1a cubre un año completo. Al enviar fechas personalizadas (periodo=custom u omitido), tanto startdate como enddate son obligatorios y el rango no debe superar los 93 días.

Solicitud

Encabezados de la solicitud

Every request to a protected endpoint requires these headers:

Header	Required	Description
`Authorization`	Yes	Bearer token obtained from the Login endpoint. Format: `Bearer <token>`
`X-API-Key`	Yes	Company integration key provided during onboarding. Format: `gtk_xxx...`
`tenant`	Yes	Your assigned tenant domain (default: `geotareas.com`) — always send your assigned tenant
`Content-Type`	Conditional	`application/json` — required for `POST` and `PUT` requests

Parámetros de consulta

Parámetro	Tipo	Obligatorio	Por defecto	Descripción
`periodo`	string	No	`30d`	Preset de período: `30d`, `90d`, `6m`, `1a`, `custom`
`startdate`	string	No	—	Fecha de inicio ISO 8601. Obligatoria cuando `periodo=custom`
`enddate`	string	No	—	Fecha de fin ISO 8601. Obligatoria cuando `periodo=custom`. Rango máximo 93 días
`provider_id`	string	No	Todos	Filtrar por un único ID de proveedor

Ejemplos de código

cURL
JavaScript
Python

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

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/portal/dashboard?periodo=90d`,
  { headers }
);
const { data } = await response.json();
console.log(`Pending invoices: ${data.kpis.pending_invoices}`);

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/portal/dashboard",
    headers=headers,
    params={"periodo": "90d"},
)
result = response.json()
kpis = result["data"]["kpis"]

Campos de la respuesta

KPIs

Campo	Tipo	Descripción
`pending_invoices`	number	Cantidad de facturas pendientes de revisión
`review_invoices`	number	Cantidad de facturas actualmente en revisión
`approval_rate`	number	Tasa de aprobación como porcentaje (0–100)
`avg_variation`	number	Porcentaje de variación promedio entre los montos del sistema y del proveedor
`active_settlements`	number	Cantidad de liquidaciones abiertas/activas
`accumulated_difference`	number	Diferencia neta acumulada (sistema − proveedor)
`active_providers`	number	Cantidad de proveedores con actividad en el período
`total_invoiced`	number	Monto total facturado por el sistema

Gráficos

Campo	Tipo	Descripción
`charts.invoices_by_state[].state`	string	Código de estado
`charts.invoices_by_state[].name`	string	Nombre legible del estado
`charts.invoices_by_state[].count`	number	Cantidad de facturas en este estado
`charts.invoices_by_state[].amount`	number	Monto total para este estado
`charts.monthly_billing[].month`	string	Mes en formato `YYYY-MM`
`charts.monthly_billing[].system`	number	Total de facturación calculado por el sistema
`charts.monthly_billing[].provider`	number	Total de facturación reportado por el proveedor
`charts.variation_trend[].month`	string	Mes en formato `YYYY-MM`
`charts.variation_trend[].variation_pct`	number	Porcentaje de variación del mes
`charts.top_providers[].provider_id`	string	Identificador del proveedor
`charts.top_providers[].provider_name`	string	Nombre visible del proveedor
`charts.top_providers[].amount`	number	Monto total facturado
`charts.top_providers[].count`	number	Cantidad de facturas
`charts.settlements_by_state[].state`	string	Código de estado de la liquidación
`charts.settlements_by_state[].name`	string	Nombre legible del estado de la liquidación
`charts.settlements_by_state[].count`	number	Cantidad de liquidaciones
`charts.settlements_by_state[].amount`	number	Monto total de la liquidación

Ejemplo de respuesta

{
  "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 }
      ]
    }
  }
}

Errores

Código	HTTP	Descripción
`VALIDATION_ERROR`	400	Formato de fecha inválido, el rango de fechas personalizado supera los 93 días
`INVALID_DATE_RANGE`	400	El rango personalizado supera los 93 días o solo se proporcionó una de `startdate`/`enddate`
`UNAUTHORIZED`	401	tenant / Authorization / X-API-Key ausente, inválido o expirado
`FORBIDDEN`	403	El usuario no tiene el permiso `APICLI_RPTPORTALPROVEEDOR_DASHBOARD`
`RATE_LIMITED`	429	Se superaron 10 req/min
`INTERNAL_ERROR`	500	Error inesperado del servidor

Facturas del Portal — Endpoints de gestión de facturas
Liquidaciones del Portal — Endpoints de gestión de liquidaciones
Reporte de Diferencias — Comparación detallada entre sistema y proveedor
Reporte de Facturación — Facturación agregada por proveedor

Resumen​

Solicitud​

Encabezados de la solicitud​

Parámetros de consulta​

Ejemplos de código​

Campos de la respuesta​

KPIs​

Gráficos​

Ejemplo de respuesta​

Errores​

Relacionado​