Portal Proveedores — Invoice Reports

The Portal Proveedores API exposes read-only report endpoints that allow API consumers to query billing summaries and invoice-level differences for providers within their tenant.

Operator-scoped JWT

All endpoints filter results by the ciaid (tenant/company ID) embedded in the JWT. Optional providers filter narrows down to specific provider IDs.

---

Billing Report

Retrieve a billing summary grouped by provider for a date range. Returns per-provider totals (invoiced, paid, pending) and a grand total across all providers.

GET/apidev/v1/reports/portal/billing

PermissionAPICLI_RPTPORTAL_FACTURACION

Rate Limit10 req/min (sliding window)

Cache300s

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
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 to filter (max 100)

Response Fields — data.rows[]

Field	Type	Description
provider_id	string	Provider ID
provider_name	string	Provider display name
task_count	number	Number of tasks/services
total_invoiced	number	System-calculated total invoiced
total_provider	number	Total entered by provider
total_paid	number	Total amount paid
pending_payment	number	Pending payment amount
approval_rate	number	Approval rate (percentage)
approved_count	number	Number of approved invoices
rejected_count	number	Number of rejected invoices
review_count	number	Number of invoices in review

Response Fields — data.grand_total

Field	Type	Description
total_invoiced	number	Grand total invoiced
total_provider	number	Grand total entered by providers
total_paid	number	Grand total paid
pending_payment	number	Grand total pending
task_count	number	Grand total task count

Code Examples

cURL

curl -s -X GET "https://api.example.com/apidev/v1/reports/portal/billing?startdate=2026-03-01&enddate=2026-03-31" \
  -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/billing?startdate=2026-03-01&enddate=2026-03-31',
  {
    headers: {
      'Authorization': `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      'tenant': TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`${meta.total} providers, grand total: ${data.grand_total.total_invoiced}`);

Python

import requests

response = requests.get(
    'https://api.example.com/apidev/v1/reports/portal/billing',
    headers={
        'Authorization': f'Bearer {TOKEN}',
        'X-API-Key': APIKEY,
        'tenant': TENANT,
    },
    params={'startdate': '2026-03-01', 'enddate': '2026-03-31'}
)
body = response.json()
rows = body['data']['rows']
grand = body['data']['grand_total']

Response Example

{
  "success": true,
  "data": {
    "rows": [
      {
        "provider_id": "5678",
        "provider_name": "Taller Sanca",
        "task_count": 42,
        "total_invoiced": 125000.00,
        "total_provider": 126200.00,
        "total_paid": 98000.00,
        "pending_payment": 27000.00,
        "approval_rate": 85.7,
        "approved_count": 36,
        "rejected_count": 2,
        "review_count": 4
      }
    ],
    "grand_total": {
      "total_invoiced": 125000.00,
      "total_provider": 126200.00,
      "total_paid": 98000.00,
      "pending_payment": 27000.00,
      "task_count": 42
    }
  },
  "meta": {
    "total": 1
  }
}

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

---

Differences Report

Retrieve a paginated list of invoices with their system vs. provider amount differences. Useful for auditing discrepancies.

GET/apidev/v1/reports/portal/differences

PermissionAPICLI_RPTPORTAL_DIFERENCIAS

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)
states	string|string[]	No	—	Comma-separated state IDs (max 10)
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 | null	Provider-declared amount
difference	number	Absolute difference
difference_pct	number	Difference as percentage
state_code	string | null	Invoice state code
state_name	string | null	Invoice state name
provider_invoice_number	string | null	Provider's invoice number
provider_invoice_date	string | null	Provider's invoice date

Response Fields — data.summary

Field	Type	Description
total_system	number	Sum of system amounts
total_provider	number	Sum of provider amounts
net_difference	number	Net difference
avg_variation_pct	number	Average variation percentage
total_invoices	number	Total invoice count
invoices_with_difference	number	Invoices with non-zero difference

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": 1100.00,
        "difference": 2.00,
        "difference_pct": 0.18,
        "state_code": "PENDIENTE",
        "state_name": "Pendiente",
        "provider_invoice_number": "FAC-2026-001",
        "provider_invoice_date": "2026-04-03"
      }
    ],
    "summary": {
      "total_system": 1098.00,
      "total_provider": 1100.00,
      "net_difference": 2.00,
      "avg_variation_pct": 0.18,
      "total_invoices": 1,
      "invoices_with_difference": 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 — Dashboard & Tolerance
• Portal — Settlements