Supplier Portal — Settlements

These endpoints let a supplier (prestador) manage their own settlements (liquidaciones): list them, open one for detail, build a draft from approved invoices, and submit it for payment. A settlement groups several invoices into a single payment batch. Every endpoint is scoped to the supplier behind the token — you only ever see and touch your own settlements.

Supplier account required

The authenticated user must be linked to a supplier (prestador). Requests from a non-supplier account are rejected with 403 FORBIDDEN. All endpoints require a valid JWT token, API key, and tenant header. See Authentication.

List Settlements

Retrieve a paginated list of the supplier's settlements, with optional date range and status filters.

GET/apidev/v1/supplier-portal/settlements

PermissionAPICLI_PORTALPROVEEDOR_READ

Rate Limit30 req/min (sliding window)

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	Description
`startdate`	string (ISO 8601)	No	Start of the date range
`enddate`	string (ISO 8601)	No	End of the date range
`status`	string	No	Filter by settlement state code: `BOR`, `LENV`, `LAPR`, `LREC`, `CER`
`limit`	integer	No	Records per page. Min: `1`, Max: `100`, Default: `25`
`offset`	integer	No	Records to skip. Default: `0`

Response Fields — `data.rows[]`

Field	Type	Description
`settlement_id`	string	Settlement unique identifier
`date`	string	Settlement creation date
`close_date`	string \| null	When the settlement was closed
`state_id`	number	Settlement state ID
`state_code`	string	Settlement state code (`BOR`, `LENV`, …)
`state_name`	string	Settlement state name
`total`	number	Settlement total amount
`invoice_count`	number	Number of invoices included
`receipts_total`	number	Total of attached receipts
`adjustments_total`	number	Total of adjustments
`difference`	number	Difference between total and receipts
`notes`	string \| null	Free-text notes
`payment_date`	string \| null	Payment date
`payment_reference`	string \| null	Payment reference

Code Example

cURL
JavaScript

curl -s "https://$TENANT/apidev/v1/supplier-portal/settlements?startdate=2026-05-01&enddate=2026-05-31&status=BOR" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const params = new URLSearchParams({
  startdate: '2026-05-01',
  enddate: '2026-05-31',
  status: 'BOR',
});

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/settlements?${params}`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
    },
  }
);

const { data, meta } = await response.json();
console.log(`${data.rows.length} of ${meta.total} settlements`);

Example Response

{
  "success": true,
  "data": {
    "rows": [
      {
        "settlement_id": "9100000000001",
        "date": "2026-05-31T10:00:00",
        "close_date": null,
        "state_id": 1,
        "state_code": "BOR",
        "state_name": "Borrador",
        "total": 3294.00,
        "invoice_count": 3,
        "receipts_total": 0.00,
        "adjustments_total": 0.00,
        "difference": 3294.00,
        "notes": "Liquidación mayo.",
        "payment_date": null,
        "payment_reference": null
      }
    ]
  },
  "meta": {
    "total": 1,
    "limit": 25,
    "offset": 0
  }
}

Settlement Detail

Retrieve a single settlement with its full breakdown: the same row fields as the list, plus the invoices it groups and the receipts attached to it. Returns 404 if the settlement does not belong to the supplier.

GET/apidev/v1/supplier-portal/settlements/{id}

PermissionAPICLI_PORTALPROVEEDOR_READ

Rate Limit30 req/min (sliding window)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Settlement unique identifier

Response Fields — `data.invoices[]`

Field	Type	Description
`invoice_id`	string	Invoice unique identifier
`service_number`	string \| null	Service display number
`account_name`	string \| null	Account the service belongs to
`system_amount`	number	Amount calculated by the system
`declared_amount`	number \| null	Amount declared by the supplier
`provider_invoice_number`	string \| null	Supplier's own invoice number
`state_code`	string	Invoice state code
`state_name`	string	Invoice state name
`is_manual`	boolean	Whether the line was added manually
`description`	string \| null	Line description

Response Fields — `data.receipts[]`

Field	Type	Description
`receipt_id`	string	Receipt unique identifier
`number`	string \| null	Receipt number
`date`	string \| null	Receipt date
`type`	string	Receipt type
`amount`	number	Receipt amount
`notes`	string \| null	Free-text notes
`attachment_url`	string \| null	URL to the attached receipt file

The data object also includes every field listed for a list row.

Code Example

cURL
JavaScript

curl -s "https://$TENANT/apidev/v1/supplier-portal/settlements/9100000000001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/settlements/9100000000001`,
  {
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
    },
  }
);

const { data } = await response.json();
console.log(`${data.invoices.length} invoices, ${data.receipts.length} receipts`);

Example Response

{
  "success": true,
  "data": {
    "settlement_id": "9100000000001",
    "date": "2026-05-31T10:00:00",
    "close_date": null,
    "state_id": 1,
    "state_code": "BOR",
    "state_name": "Borrador",
    "total": 3294.00,
    "invoice_count": 3,
    "receipts_total": 3300.00,
    "adjustments_total": 0.00,
    "difference": 6.00,
    "notes": "Liquidación mayo.",
    "payment_date": null,
    "payment_reference": null,
    "invoices": [
      {
        "invoice_id": "7234567890123456789",
        "service_number": "SRV-2026-0042",
        "account_name": "Supermercado Centro",
        "system_amount": 1098.00,
        "declared_amount": 1100.00,
        "provider_invoice_number": "A-0001-0000123",
        "state_code": "APR",
        "state_name": "Aprobada",
        "is_manual": false,
        "description": null
      }
    ],
    "receipts": [
      {
        "receipt_id": "9200000000010",
        "number": "REC-0001",
        "date": "2026-05-31",
        "type": "TRANSFER",
        "amount": 3300.00,
        "notes": "Transferencia bancaria.",
        "attachment_url": "https://files.example.com/rec/10.pdf"
      }
    ]
  },
  "meta": {}
}

Create Settlement

Create a draft settlement from the supplier's approved invoices. Each invoice is validated: it must belong to the supplier, be in APR (approved) state, and not already be part of an active settlement. Returns 201 with the new settlement detail.

POST/apidev/v1/supplier-portal/settlements

PermissionAPICLI_PORTALPROVEEDOR_WRITE

Rate Limit10 req/min (sliding window)

Request Body

Field	Type	Required	Description
`invoice_ids`	array	Yes	Invoices to group (numeric strings, 1–500 items)
`note`	string	No	Free-text note for the settlement

Code Example

cURL
JavaScript

curl -s -X POST "https://$TENANT/apidev/v1/supplier-portal/settlements" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_ids": ["7234567890123456789", "7234567890123456790"],
    "note": "Liquidación mayo."
  }'

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/settlements`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      invoice_ids: ['7234567890123456789', '7234567890123456790'],
      note: 'Liquidación mayo.',
    }),
  }
);

const { data } = await response.json();
console.log(`Draft settlement created: ${data.settlement_id}`);

Example Response — `201 Created`

{
  "success": true,
  "data": {
    "settlement_id": "9100000000001",
    "date": "2026-05-31T10:00:00",
    "close_date": null,
    "state_id": 1,
    "state_code": "BOR",
    "state_name": "Borrador",
    "total": 1640.00,
    "invoice_count": 2,
    "receipts_total": 0.00,
    "adjustments_total": 0.00,
    "difference": 1640.00,
    "notes": "Liquidación mayo.",
    "payment_date": null,
    "payment_reference": null,
    "invoices": [
      {
        "invoice_id": "7234567890123456789",
        "service_number": "SRV-2026-0042",
        "account_name": "Supermercado Centro",
        "system_amount": 1100.00,
        "declared_amount": 1100.00,
        "provider_invoice_number": "A-0001-0000123",
        "state_code": "APR",
        "state_name": "Aprobada",
        "is_manual": false,
        "description": null
      }
    ],
    "receipts": []
  },
  "meta": {}
}

Submit Settlement

Submit a draft settlement for payment. It moves the settlement from BOR (draft) to LENV (submitted) and requires at least one receipt to be attached. Returns the updated settlement row, or 404 if the settlement does not belong to the supplier.

PUT/apidev/v1/supplier-portal/settlements/{id}/submit

PermissionAPICLI_PORTALPROVEEDOR_WRITE

Rate Limit10 req/min (sliding window)

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Settlement unique identifier

Code Example

cURL
JavaScript

curl -s -X PUT "https://$TENANT/apidev/v1/supplier-portal/settlements/9100000000001/submit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT"

const response = await fetch(
  `https://${TENANT}/apidev/v1/supplier-portal/settlements/9100000000001/submit`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'X-API-Key': APIKEY,
      tenant: TENANT,
    },
  }
);

const { data } = await response.json();
console.log(`Settlement now in state: ${data.state_code}`);

Example Response

{
  "success": true,
  "data": {
    "settlement_id": "9100000000001",
    "date": "2026-05-31T10:00:00",
    "close_date": null,
    "state_id": 2,
    "state_code": "LENV",
    "state_name": "Enviada",
    "total": 3294.00,
    "invoice_count": 3,
    "receipts_total": 3300.00,
    "adjustments_total": 0.00,
    "difference": 6.00,
    "notes": "Liquidación mayo.",
    "payment_date": null,
    "payment_reference": null
  },
  "meta": {}
}

Errors

Code	HTTP	Applies to	Description
`VALIDATION_ERROR`	400	List, Create, Submit	Invalid params or body (e.g. empty `invoice_ids`, more than 500 items, an invoice that is not approved, or submitting without a receipt)
`UNAUTHORIZED`	401	All	Missing or invalid JWT token / API key
`TOKEN_EXPIRED`	401	All	The JWT was valid but has expired (1 hour lifetime)
`FORBIDDEN`	403	All	The account is not a supplier — "This endpoint requires a supplier account." — or lacks the required permission
`NOT_FOUND`	404	Detail, Submit	Settlement (or a referenced invoice) does not exist or does not belong to your supplier account
`RATE_LIMITED`	429	All	Exceeded the endpoint rate limit

Invoices — list, declare, and validate invoices
Catalogs & Tolerance — invoice states, concepts, and the effective tolerance

List Settlements​

Request Headers​

Query Parameters​

Response Fields — data.rows[]​

Code Example​

Example Response​

Settlement Detail​

Path Parameters​

Response Fields — data.invoices[]​

Response Fields — data.receipts[]​

Code Example​

Example Response​

Create Settlement​

Request Body​

Code Example​

Example Response — 201 Created​

Submit Settlement​

Path Parameters​

Code Example​

Example Response​

Errors​

Related​

List Settlements

Request Headers

Query Parameters

Response Fields — `data.rows[]`

Code Example

Example Response

Settlement Detail

Path Parameters

Response Fields — `data.invoices[]`

Response Fields — `data.receipts[]`

Code Example

Example Response

Create Settlement

Request Body

Code Example

Example Response — `201 Created`

Submit Settlement

Path Parameters

Code Example

Example Response

Errors

Related