Portal Proveedores — Dashboard & Tolerance

Aggregated dashboard metrics and tolerance analysis endpoints for the supplier portal.

Operator-scoped JWT

All endpoints filter results by the ciaid (tenant/company ID) embedded in the JWT. The Dashboard endpoint can optionally filter by a single provider.

---

Dashboard Report

Retrieve aggregated KPIs and chart data for the portal dashboard. Includes invoice/settlement counts, billing trends, variation analysis, and top providers.

GET/apidev/v1/reports/portal/dashboard

PermissionAPICLI_RPTPORTAL_DASHBOARD

Rate Limit10 req/min (sliding window)

Cache120s

Request Headers

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 company hostname (e.g., yourcompany.geotareas.com)
Content-Type	Conditional	application/json — required for POST and PUT requests

Query Parameters

Parameter	Type	Required	Default	Description
periodo	string	No	custom	Preset period: 30d, 90d, 6m, 1a, custom
startdate	string (ISO 8601)	No	—	Start date (required when periodo=custom)
enddate	string (ISO 8601)	No	—	End date (required when periodo=custom)
provider_id	string	No	—	Single provider ID to scope the dashboard

Response Fields — data.kpis

Field	Type	Description
pending_invoices	number	Count of pending invoices
review_invoices	number	Count of invoices in review
approval_rate	number	Overall approval rate (percentage)
avg_variation	number	Average variation between system and provider amounts
active_settlements	number	Count of active/open settlements
accumulated_difference	number	Accumulated net difference
active_providers	number	Count of active providers
total_invoiced	number	Total invoiced amount

Response Fields — data.charts

Field	Type	Description
invoices_by_state[]	array	{ state, name, count, amount } — invoices grouped by state
monthly_billing[]	array	{ month, system, provider } — monthly billing comparison
variation_trend[]	array	{ month, variation_pct } — monthly variation trend
top_providers[]	array	{ provider_id, provider_name, amount, count } — top providers by amount
settlements_by_state[]	array	{ state, name, count, amount } — settlements grouped by state

Code Examples

cURL

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

JavaScript

const response = await fetch(
  'https://api.example.com/apidev/v1/reports/portal/dashboard?periodo=30d',
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);

const { data } = await response.json();
console.log(`Pending: ${data.kpis.pending_invoices}, Approval rate: ${data.kpis.approval_rate}%`);

Python

import requests

response = requests.get(
    'https://api.example.com/apidev/v1/reports/portal/dashboard',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'X-API-Key': APIKEY,
        'tenant': TENANT,
    },
    params={'periodo': '30d'}
)
kpis = response.json()['data']['kpis']

Response Example

{
  "success": true,
  "data": {
    "kpis": {
      "pending_invoices": 15,
      "review_invoices": 3,
      "approval_rate": 87.5,
      "avg_variation": 2.3,
      "active_settlements": 2,
      "accumulated_difference": 4500.00,
      "active_providers": 8,
      "total_invoiced": 250000.00
    },
    "charts": {
      "invoices_by_state": [
        { "state": "PENDIENTE", "name": "Pendiente", "count": 15, "amount": 45000.00 },
        { "state": "CONCILIADO", "name": "Conciliado", "count": 120, "amount": 180000.00 }
      ],
      "monthly_billing": [
        { "month": "2026-01", "system": 80000.00, "provider": 81200.00 },
        { "month": "2026-02", "system": 85000.00, "provider": 86100.00 }
      ],
      "variation_trend": [
        { "month": "2026-01", "variation_pct": 1.5 },
        { "month": "2026-02", "variation_pct": 1.3 }
      ],
      "top_providers": [
        { "provider_id": "5678", "provider_name": "Taller Sanca", "amount": 95000.00, "count": 42 }
      ],
      "settlements_by_state": [
        { "state": "ABIERTA", "name": "Abierta", "count": 2, "amount": 12000.00 },
        { "state": "CERRADA", "name": "Cerrada", "count": 5, "amount": 85000.00 }
      ]
    }
  },
  "meta": {}
}

Code	HTTP Status	Description	Resolution
VALIDATION_ERROR	400	Request body or query parameters failed validation	Check the error.details field for specific validation failures
UNAUTHORIZED	401	Missing, expired, or invalid JWT token or API key	Re-authenticate via Login to get a fresh token
RATE_LIMITED	429	Too many requests — rate limit exceeded	Wait until the Retry-After header time elapses. See Rate Limits
INTERNAL_ERROR	500	Unexpected server error	Retry after a brief delay. If persistent, contact support

---

Tolerance Report

Retrieve a paginated list of invoices with their tolerance analysis. Shows whether each invoice's provider amount falls within the configured tolerance for the provider.

GET/apidev/v1/reports/portal/tolerance

PermissionAPICLI_RPTPORTAL_TOLERANCIA

Rate Limit10 req/min (sliding window)

Cache300s

Query Parameters

Parameter	Type	Required	Default	Description
startdate	string (ISO 8601)	Yes	—	Start date filter
enddate	string (ISO 8601)	Yes	—	End date filter (max 93-day range)
providers	string|string[]	No	—	Comma-separated provider IDs (max 100)
anomalies_only	boolean	No	—	If true, return only invoices outside tolerance
limit	integer	No	25	Records per page. Min: 1, Max: 100
offset	integer	No	0	Number of records to skip

Response Fields — data.rows[]

Field	Type	Description
invoice_id	string	Invoice unique identifier
provider_id	string	Provider ID
provider_name	string	Provider display name
service_id	string	Related service/task ID
service_number	string	Service display number
invoice_date	string	Invoice date
system_amount	number	System-calculated amount
provider_amount	number	Provider-declared amount
difference	number	Absolute difference
deviation_pct	number	Deviation as percentage
state_id	number | null	Invoice state ID
state_name	string | null	Invoice state name
tolerance_configured	string	Tolerance configuration description
tolerance_type	string	Tolerance type (e.g. PERCENTAGE, FIXED)
tolerance_value	number	Configured tolerance value
tolerance_origin	string	Where the tolerance comes from
result	string	Tolerance evaluation result
within_tolerance	boolean	Whether the invoice is within tolerance

Response Fields — data.summary

Field	Type	Description
total_invoices	number	Total invoice count
auto_approved	number	Auto-approved count
in_review	number	In-review count
rejected	number	Rejected count
avg_deviation_pct	number	Average deviation percentage
providers_with_anomalies	number	Providers with out-of-tolerance invoices

Code Examples

cURL

curl -s -X GET "https://api.example.com/apidev/v1/reports/portal/tolerance?startdate=2026-03-01&enddate=2026-03-31&anomalies_only=true" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  'https://api.example.com/apidev/v1/reports/portal/tolerance?startdate=2026-03-01&enddate=2026-03-31&anomalies_only=true',
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`${data.summary.providers_with_anomalies} providers with anomalies`);

Response Example

{
  "success": true,
  "data": {
    "rows": [
      {
        "invoice_id": "7234567890123456789",
        "provider_id": "5678",
        "provider_name": "Taller Sanca",
        "service_id": "103878",
        "service_number": "SRV-2026-0042",
        "invoice_date": "2026-04-03T15:02:00",
        "system_amount": 1098.00,
        "provider_amount": 1500.00,
        "difference": 402.00,
        "deviation_pct": 36.61,
        "state_id": 1,
        "state_name": "Pendiente",
        "tolerance_configured": "5%",
        "tolerance_type": "PERCENTAGE",
        "tolerance_value": 5.0,
        "tolerance_origin": "ORIGIN_DEFAULT",
        "result": "EXCEEDED",
        "within_tolerance": false
      }
    ],
    "summary": {
      "total_invoices": 1,
      "auto_approved": 0,
      "in_review": 0,
      "rejected": 1,
      "avg_deviation_pct": 36.61,
      "providers_with_anomalies": 1
    }
  },
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Errors

Code	HTTP	Description
INVALID_DATE_RANGE	400	Date range exceeds 93 days or dates are invalid

---

Related

• Portal — Invoices
• Portal — Settlements