Settlement API¶

Base path: /core/api/communities/{community_id}/sessions/settlement

Settlement is the post-clearing financial computation of each member's revenues and costs per 15-minute ISP (see Settlement concepts and the Settlement Guide). Settlement itself runs automatically after market clearing, so this API is read-only for results and offers three groups of endpoints:

• Metrics: pre-aggregated KPIs per community, per member and per resource.
• Dynamic query: a flexible endpoint to read any of the 8 settlement output tables.
• Billing guides: asynchronous Excel / PDF reports, plus listing, downloading and deleting the generated files (see also File Exports).

All routes require an authenticated, verified user who belongs to the community (or a platform admin). Because POST and DELETE are "unsafe" methods, a community member receives 403 Community members can only perform read operations on every POST/DELETE route below, including the dynamic query and the file download. Only community admins and platform admins can use them.

Dates are plain YYYY-MM-DD dates and ranges are inclusive of the whole end_date. Monetary values are in EUR and energy values in kWh, per 15-minute ISP, summed over the requested range. Timestamps follow the platform time zone (Europe/Lisbon).

Endpoint summary¶

Metrics¶

Get Settlement KPIs¶

GET /core/api/communities/{community_id}/sessions/settlement/settlement-kpis

Returns three community-level KPIs summed over the period, computed from the member-level settlement output (rev_total, rev_total_no_csc, rev_total_pow). See Revenue & Cost Fields for the meaning of each field.

Auth / permissions: any member of the community, community admin or platform admin. The result is community-wide and is not restricted to the caller's own data.

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/settlement-kpis?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "savings_perc": 12.4,
  "savings": 86.35,
  "rev_total_pow": -4.1
}

Get Member Settlement Metrics¶

GET /core/api/communities/{community_id}/sessions/settlement/settlement-metrics

Returns one entry per member, keyed by member (user) UUID, with the member's settlement energy and revenue fields summed over the period plus its savings.

Auth / permissions: any member of the community, community admin or platform admin. For a community member the result is automatically restricted to the caller's own entry; admins see all members.

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/settlement-metrics?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

{
  "7c9e6679-7425-40de-944b-e07fc1f90ae7": {
    "savings": 4.82,
    "savings_perc_proportional": 5.6,
    "rev_total_pow": -0.9,
    "rev_pow": -0.4,
    "e_sup": 210.5,
    "e_pur": 95.2,
    "e_sale": 0.0,
    "e_sur": 12.1,
    "rev_sup": -31.6,
    "rev_pur": -9.1,
    "rev_sale": 0.0,
    "rev_sur": 0.8,
    "rev_slc_soc": -1.2,
    "rev_lem_fee": 0.0
  }
}

Get Resource Settlement Metrics¶

GET /core/api/communities/{community_id}/sessions/settlement/settlement-resource-metrics

Returns, for each resource, the total revenue (rev_total, EUR) over the period and the resource's share of the community resource revenue total (rev_total_perc), keyed by resource UUID.

Auth / permissions: any member of the community, community admin or platform admin. Not restricted to the caller's own resources.

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/settlement-resource-metrics?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged, as built by the handler)

{
  "5b2c1e40-0c3a-4c52-9d0e-1f6a8d9b7a11": {
    "rev_total": 42.7,
    "rev_total_perc": 61.3
  }
}

Dynamic query¶

Query Settlement Outputs (Dynamic)¶

POST /core/api/communities/{community_id}/sessions/settlement/outputs/query

An optional, flexible endpoint for retrieving settlement results without being tied to a fixed response shape. Instead of calling one endpoint per level (member, resource, CPE, REC), you describe in a single JSON body which output tables, which fields, and which entities you want, and the response contains only that. It is a POST because the fields parameter is a nested object, which cannot be expressed as flat query-string parameters.

Auth / permissions: community admin or platform admin only (it is a POST, so community members get 403).

Passing "ALL" to any parameter skips that filter or selects everything.

Output types

Selecting fields. fields is either "ALL" or an object that maps an output type to "ALL" or a list of field names. Output types left out of the object default to "ALL".

"fields": {
  "cpes": ["e_lem", "e_pur"],
  "cpes_bilateral": "ALL"
}

Selectable fields per output type:

Field meanings are in Revenue & Cost Fields and Energy Fields.

Entity filters

rec is a community-level aggregate, so entity filters have no effect on it.

Example

curl -X POST \
  https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/outputs/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "outputs": ["cpes", "cpes_bilateral"],
    "fields": {
      "cpes": ["e_lem", "e_pur"],
      "cpes_bilateral": "ALL"
    },
    "meters": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
  }'

Response (abridged)

data has one key per requested output type, each holding a list of rows (one per 15-minute ISP). Every row contains the identity columns of its output type, followed by the requested fields. UUIDs are serialised as strings and datetime_timestamp as an ISO-8601 string. session_id and community_id are omitted, as they are implied by the request.

{
  "data": {
    "cpes": [
      {
        "datetime_timestamp": "2025-01-01T00:00:00",
        "cpe_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "e_lem": 0.12,
        "e_pur": 0.05
      }
    ],
    "cpes_bilateral": [
      {
        "datetime_timestamp": "2025-01-01T00:00:00",
        "provider_cpe_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "receiver_cpe_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "e_alc": 0.03,
        "e_slc": 0.03,
        "allocation_coefficient": 0.25
      }
    ]
  }
}

Billing guides¶

A billing guide is a per-period financial report (revenues, costs and energy per member, resource, transaction and REC) generated as an Excel workbook or a PDF. Generation is asynchronous: the POST returns a Celery task_id, and the finished file appears in the community's file folder, from where it can be listed, downloaded and deleted. The end-to-end flow is in File Exports.

List Billable Members¶

GET /core/api/communities/{community_id}/sessions/settlement/billing-guides/members

Lists the members that can be selected for a billing guide in a period: those holding an active MEMBER membership on at least one day of the range. Use the returned id values as user_ids when generating a guide.

Auth / permissions: community admin or platform admin (403 Community admin access required otherwise).

Example

curl "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/billing-guides/members?start_date=2025-01-01&end_date=2025-01-31" \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "Alice Silva", "email": "alice@example.com" }
]

Generate Billing Guide (Excel)¶

POST /core/api/communities/{community_id}/sessions/settlement/billing-guides/excel

Queues the generation of an .xlsx billing guide for the period. Returns immediately with a task id.

Auth / permissions: community admin or platform admin.

Valid sheets values:

• Member | Total: totals per member
• Member-Resource | Total: totals per member and resource
• Member-Resource | Distinct: per-interval detail per member and resource
• Transactions | Total: totals of the transactions
• Transactions | Distinct: per-interval transaction detail
• REC Total: community aggregate

Example

curl -X POST \
  https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/billing-guides/excel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "user_ids": [],
    "sheets": ["Member | Total", "Transactions | Total", "REC Total"],
    "language": "pt"
  }'

Response (abridged)

{ "message": "Processing started", "task_id": "b1c6e8a2-3d4f-4e5a-9a7b-0c1d2e3f4a5b" }

Generate Billing Guide (PDF)¶

POST /core/api/communities/{community_id}/sessions/settlement/billing-guides/pdf

Same request and response as the Excel version, but produces a .pdf file.

Auth / permissions: community admin or platform admin.

Example

curl -X POST \
  https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/billing-guides/pdf \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "user_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
    "sheets": ["Member | Total", "REC Total"],
    "language": "en"
  }'

Response (abridged)

{ "message": "Processing started", "task_id": "b1c6e8a2-3d4f-4e5a-9a7b-0c1d2e3f4a5b" }

List Billing Guides¶

GET /core/api/communities/{community_id}/sessions/settlement/billing-guides

Lists the generated files in the community's folder (.xlsx, .xlsm, .xltx, .xltm and .pdf), newest first.

Auth / permissions: community admin or platform admin (403 Community admin access required otherwise).

Example

curl https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/billing-guides \
  -H "Authorization: Bearer $TOKEN"

Response (abridged)

[
  { "name": "9f3a1c2e_Community_Name_0_3_20250101_20250131.xlsx", "creation_time": "2025-02-03T10:15:42.123456" }
]

Download Billing Guide¶

POST /core/api/communities/{community_id}/sessions/settlement/billing-guides/{file_name}

Downloads a previously generated file as a binary stream (application/octet-stream).

Auth / permissions: community admin or platform admin. The route is a POST, so community members get 403.

Example

curl -X POST \
  "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/billing-guides/9f3a1c2e_Community_Name_0_3_20250101_20250131.xlsx" \
  -H "Authorization: Bearer $TOKEN" \
  -o billing-guide.xlsx

Response

The file bytes, with Content-Disposition set to the file name. There is no JSON body.

Delete Billing Guide¶

DELETE /core/api/communities/{community_id}/sessions/settlement/billing-guides/{file_name}

Permanently deletes a generated billing guide file from the community folder.

Auth / permissions: community admin or platform admin.

Example

curl -X DELETE \
  "https://<host>/core/api/communities/3fa85f64-5717-4562-b3fc-2c963f66afa6/sessions/settlement/billing-guides/9f3a1c2e_Community_Name_0_3_20250101_20250131.xlsx" \
  -H "Authorization: Bearer $TOKEN"

Response

{ "message": "File 9f3a1c2e_Community_Name_0_3_20250101_20250131.xlsx deleted successfully" }