Billing Report

Billing aggregated by provider — total invoiced, provider amounts, payment status, and approval rates.

GET/apidev/v1/reports/portal/billing

PermissionAPICLI_RPTPORTALPROVEEDOR_FACTURACION

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range93 days

---

Overview

Aggregates billing data by provider for the specified date range. Each row represents one provider with totals for invoiced amounts, provider-reported amounts, payment status, and approval/rejection counts.

• Per-provider summary — task count, invoiced totals, payment status, approval rate
• Grand totals — aggregate across all providers in the response
• Provider filtering — restrict to specific providers (up to 100)

---

Request

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 assigned tenant domain (default: geotareas.com) — always send your assigned tenant
Content-Type	Conditional	application/json — required for POST and PUT requests

Query Parameters

Parameter	Type	Required	Default	Description
startdate	string	Yes	—	ISO 8601 start date
enddate	string	Yes	—	ISO 8601 end date. Max range 93 days
providers	string	No	All	Comma-separated provider IDs. Max 100

---

Code Examples

cURL

curl -s "https://$TENANT/apidev/v1/reports/portal/billing?startdate=2026-01-01&enddate=2026-03-31" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/portal/billing?startdate=2026-01-01&enddate=2026-03-31`,
  { headers }
);
const { data } = await response.json();
console.log(`Total invoiced: ${data.grand_total.total_invoiced}`);

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/portal/billing",
    headers=headers,
    params={"startdate": "2026-01-01", "enddate": "2026-03-31"},
)
result = response.json()
for row in result["data"]["rows"]:
    print(f"{row['provider_name']}: {row['total_invoiced']}")

---

Response Fields

Rows

Field	Type	Description
provider_id	string	Provider identifier
provider_name	string	Provider display name
task_count	number	Number of tasks/services in the period
total_invoiced	number	Total system-calculated invoiced amount
total_provider	number	Total provider-reported amount
total_paid	number	Total amount already paid
pending_payment	number	Amount pending payment
approval_rate	number	Approval rate as percentage (0–100)
approved_count	number	Number of approved invoices
rejected_count	number	Number of rejected invoices
review_count	number	Number of invoices in review

Grand Total

Field	Type	Description
total_invoiced	number	Sum of all providers' invoiced amounts
total_provider	number	Sum of all providers' reported amounts
total_paid	number	Sum of all paid amounts
pending_payment	number	Sum of all pending payments
task_count	number	Total task count across all providers

Example Response

{
  "success": true,
  "data": {
    "rows": [
      {
        "provider_id": "504210987600",
        "provider_name": "Transporte Rápido S.A.",
        "task_count": 42,
        "total_invoiced": 245800.00,
        "total_provider": 251200.00,
        "total_paid": 198400.00,
        "pending_payment": 47400.00,
        "approval_rate": 88.10,
        "approved_count": 37,
        "rejected_count": 2,
        "review_count": 3
      },
      {
        "provider_id": "504210987601",
        "provider_name": "Logística del Norte",
        "task_count": 35,
        "total_invoiced": 198300.00,
        "total_provider": 199100.00,
        "total_paid": 178500.00,
        "pending_payment": 19800.00,
        "approval_rate": 94.29,
        "approved_count": 33,
        "rejected_count": 1,
        "review_count": 1
      },
      {
        "provider_id": "504210987602",
        "provider_name": "ServiFlota Express",
        "task_count": 28,
        "total_invoiced": 167500.00,
        "total_provider": 169800.00,
        "total_paid": 142000.00,
        "pending_payment": 25500.00,
        "approval_rate": 85.71,
        "approved_count": 24,
        "rejected_count": 2,
        "review_count": 2
      }
    ],
    "grand_total": {
      "total_invoiced": 611600.00,
      "total_provider": 620100.00,
      "total_paid": 518900.00,
      "pending_payment": 92700.00,
      "task_count": 105
    }
  },
  "meta": {
    "total": 3
  }
}

---

Errors

Code	HTTP	Description
VALIDATION_ERROR	400	Date range exceeds 93 days, > 100 providers
UNAUTHORIZED	401	Missing, invalid, or expired tenant / Authorization / X-API-Key
FORBIDDEN	403	User lacks APICLI_RPTPORTALPROVEEDOR_FACTURACION permission
RATE_LIMITED	429	Exceeded 10 req/min
INTERNAL_ERROR	500	Unexpected server error

---

Related

• Portal Dashboard — Executive KPIs and charts
• Differences Report — Per-invoice system vs provider comparison
• Settlements Report — Settlement tracking and status
• Portal Invoices — Invoice management endpoints