Settlements Report

Settlement tracking with status, amounts, voucher counts, and forced close indicators. Includes summary aggregates.

GET/apidev/v1/reports/portal/settlements

PermissionAPICLI_RPTPORTALPROVEEDOR_LIQUIDACIONES

Rate Limit10 req/min (sliding window)

Cache300s (5 min)

Max Range93 days

---

Overview

Returns paginated settlement records with status, financial totals, voucher counts, and forced-close indicators. Includes a summary with aggregate counts and amounts.

• State filtering — filter by settlement state codes (200–204)
• Provider filtering — restrict to specific providers (up to 100)
• Forced close detection — identify settlements that were force-closed
• Summary aggregates — total settlements, open vs closed counts, net differences

---

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
states	string	No	All	Comma-separated settlement state codes (200–204). Max 10
limit	integer	No	25	Records per page (1–100)
offset	integer	No	0	Records to skip

---

Code Examples

cURL

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

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/reports/portal/settlements?startdate=2026-01-01&enddate=2026-03-31&limit=50`,
  { headers }
);
const { data, meta } = await response.json();
console.log(`Open settlements: ${data.summary.open}`);

Python

response = requests.get(
    f"https://{TENANT}/apidev/v1/reports/portal/settlements",
    headers=headers,
    params={"startdate": "2026-01-01", "enddate": "2026-03-31", "limit": 50},
)
result = response.json()
summary = result["data"]["summary"]

---

Response Fields

Rows

Field	Type	Description
settlement_id	string	Settlement identifier
provider_id	string	Provider identifier
provider_name	string	Provider display name
date	string	Settlement creation date
state_id	number	Settlement state code (200–204)
state_name	string	Human-readable state name
invoice_count	number	Number of invoices in this settlement
total	number	Total settlement amount
total_vouchers	number	Total voucher amount
total_adjustments	number	Total adjustment amount
difference	number	Difference (total − vouchers − adjustments)
forced_close	boolean	Whether the settlement was force-closed
payment_number	string | null	Payment reference number
payment_notes	string | null	Payment notes or observations
close_date	string | null	Date the settlement was closed. null if still open
voucher_count	number	Number of vouchers attached

Summary

Field	Type	Description
total_settlements	number	Total settlement count in range
total_system	number	Sum of all settlement totals
total_vouchers	number	Sum of all voucher amounts
total_difference	number	Net difference across all settlements
closed	number	Count of closed settlements
open	number	Count of open settlements

Example Response

{
  "success": true,
  "data": {
    "rows": [
      {
        "settlement_id": "930120456700",
        "provider_id": "504210987600",
        "provider_name": "Transporte Rápido S.A.",
        "date": "2026-02-01",
        "state_id": 202,
        "state_name": "Closed",
        "invoice_count": 18,
        "total": 145200.00,
        "total_vouchers": 143800.00,
        "total_adjustments": 800.00,
        "difference": 600.00,
        "forced_close": false,
        "payment_number": "PAG-2026-0034",
        "payment_notes": "Wire transfer confirmed",
        "close_date": "2026-02-28",
        "voucher_count": 3
      },
      {
        "settlement_id": "930120456701",
        "provider_id": "504210987601",
        "provider_name": "Logística del Norte",
        "date": "2026-03-01",
        "state_id": 200,
        "state_name": "Open",
        "invoice_count": 12,
        "total": 98500.00,
        "total_vouchers": 0.00,
        "total_adjustments": 0.00,
        "difference": 98500.00,
        "forced_close": false,
        "payment_number": null,
        "payment_notes": null,
        "close_date": null,
        "voucher_count": 0
      }
    ],
    "summary": {
      "total_settlements": 14,
      "total_system": 876400.00,
      "total_vouchers": 712300.00,
      "total_difference": 164100.00,
      "closed": 9,
      "open": 5
    }
  },
  "meta": {
    "total": 14,
    "limit": 50,
    "offset": 0
  }
}

---

Errors

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

---

Related

• Portal Dashboard — Executive KPIs and charts
• Billing Report — Billing aggregated by provider
• Portal Settlements — Settlement management endpoints
• Pagination — Standard pagination parameters