Portal Proveedores — Settlements Report

Query settlement data for providers within the authenticated tenant. Settlements group invoices into consolidated payment batches.

Operator-scoped JWT

All endpoints filter results by the ciaid (tenant/company ID) embedded in the JWT. Optional providers and states filters narrow the results.

---

Settlements Report

Retrieve a paginated list of settlements with per-row detail and an aggregated summary.

GET/apidev/v1/reports/portal/settlements

PermissionAPICLI_RPTPORTAL_LIQUIDACIONES

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 (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
settlement_id	string	Settlement unique identifier
provider_id	string	Provider ID
provider_name	string	Provider display name
date	string	Settlement date
state_id	number	Settlement state ID
state_name	string	Settlement state display name
invoice_count	number	Number of invoices included
total	number	Settlement total amount
total_vouchers	number	Total voucher amount
total_adjustments	number	Total adjustments amount
difference	number	Difference between total and vouchers
forced_close	boolean	Whether the settlement was force-closed
payment_number	string | null	Payment reference number
payment_notes	string | null	Payment notes
close_date	string | null	Settlement close date
voucher_count	number	Number of vouchers attached

Response Fields — data.summary

Field	Type	Description
total_settlements	number	Total settlement count
total_system	number	Total system amount
total_vouchers	number	Total voucher amount
total_difference	number	Total difference
closed	number	Closed settlements count
open	number	Open settlements count

Code Examples

cURL

curl -s -X GET "https://api.example.com/apidev/v1/reports/portal/settlements?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/settlements?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(`${data.summary.total_settlements} settlements, ${data.summary.open} open`);

Python

import requests

response = requests.get(
    'https://api.example.com/apidev/v1/reports/portal/settlements',
    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']
summary = body['data']['summary']

Response Example

{
  "success": true,
  "data": {
    "rows": [
      {
        "settlement_id": "9100000000001",
        "provider_id": "5678",
        "provider_name": "Taller Sanca",
        "date": "2026-04-03T10:00:00",
        "state_id": 1,
        "state_name": "Abierta",
        "invoice_count": 3,
        "total": 3294.00,
        "total_vouchers": 3300.00,
        "total_adjustments": 0,
        "difference": 6.00,
        "forced_close": false,
        "payment_number": null,
        "payment_notes": null,
        "close_date": null,
        "voucher_count": 2
      }
    ],
    "summary": {
      "total_settlements": 1,
      "total_system": 3294.00,
      "total_vouchers": 3300.00,
      "total_difference": 6.00,
      "closed": 0,
      "open": 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

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

---

Related

• Portal — Invoices — billing and differences reports
• Portal — Dashboard & Tolerance — KPIs, charts, and tolerance analysis