OpenAPI reference

Receiver Session

PATCH/sessions/{country_code}/{party_id}/{session_id}

Notify the receiver of partial updates to a Session. Per OCPI 2.2.1 §9.4.3, the body MUST include `last_updated` (2001 if absent); path `country_code`/`party_id` MUST match the body's, when the body c

API: OCPI 2.2.1 (eMSP) · Module: Sessions (eMSP)
Base path: /sessions · Base URL: https://ocpi-api.gridos.co/ocpi/emsp/2.2.1

Overview

PATCH /sessions/{country_code}/{party_id}/{session_id}

Absolute URL: https://ocpi-api.gridos.co/ocpi/emsp/2.2.1/sessions/{country_code}/{party_id}/{session_id}

Notify the receiver of partial updates to a Session. Per OCPI 2.2.1 §9.4.3, the body MUST include last_updated (2001 if absent); path country_code/party_id MUST match the body's, when the body carries them (2001 on mismatch).

Requires authentication. Use Authorization: Token <token>. See OCPI credentials.

How to call

Quick Shell sample (set OCPI_TOKEN when auth is required). Full Python and TypeScript under Examples.

1curl -sS -X PATCH 'https://ocpi-api.gridos.co/ocpi/emsp/2.2.1/sessions/NL/ABC/SESSION1' \
2  -H "Authorization: Token $OCPI_TOKEN" \
3  -H 'Content-Type: application/json' \
4  -d '{"kwh":14.1,"status":"COMPLETED","end_date_time":"2020-03-09T11:37:32Z","last_updated":"2020-03-09T11:37:32Z"}'

Request

Path parameters

Name	Type	Required	Description
`country_code`	`string`	Yes	ISO-3166 alpha-2 country code (uppercase).
`party_id`	`string`	Yes	CPO/eMSP party ID (ISO-15118, 3 uppercase alphanumerics).
`session_id`	`string`	Yes	Session.id of the Session object.

Request body

application/json · Required

Schema: SessionUpdate

Field	Type	Required	Description
`country_code`	`string`	No	—
`party_id`	`string`	No	—
`id`	`string`	No	—
`start_date_time`	`string (date-time)`	No	—
`end_date_time`	`string (date-time)`	No	—
`kwh`	`number`	No	—
`cdr_token`	`CdrToken`	No	OCPI CdrToken: the token reference embedded in Sessions and CDRs.
`auth_method`	`"AUTH_REQUEST"	"COMMAND"	"WHITELIST"`
`authorization_reference`	`string`	No	—
`location_id`	`string`	No	—
`evse_uid`	`string`	No	—
`connector_id`	`string`	No	—
`meter_id`	`string`	No	—
`currency`	`string`	No	—
`charging_periods`	`object[]`	No	—
`total_cost`	`Price`	No	OCPI Price: an amount with and without VAT.
`status`	`"ACTIVE"	"COMPLETED"	"INVALID"
`last_updated`	`string (date-time)`	No	—

Request examples

Example 1

1{
2  "kwh": 14.1,
3  "status": "COMPLETED",
4  "end_date_time": "2020-03-09T11:37:32Z",
5  "last_updated": "2020-03-09T11:37:32Z"
6}

Example 2

1{
2  "charging_periods": [
3    {
4      "start_date_time": "2020-03-10T08:00:00Z",
5      "dimensions": [
6        {
7          "type": "ENERGY",
8          "volume": 18.75
9        }
10      ]
11    }
12  ],
13  "last_updated": "2020-03-10T08:30:00Z"
14}

Responses

Status	Description	Schema
`200`	Successful Response	`SessionResponse`
`400`	Invalid or missing parameters (HTTP 200, OCPI envelope)	`—`
`401`	Unauthorized	`—`
`404`	Not Found	`—`
`422`	Validation Error	`HTTPValidationError`

`200` — successful response

application/json

Schema: SessionResponse

Field	Type	Required	Description
`status_code`	`integer`	No	Default: `1000`
`status_message`	`string`	No	—
`timestamp`	`string (date-time)`	No	—
`data`	`SessionOut`	No	`SessionOut`

Response example

1{
2  "status_code": 1000,
3  "status_message": "Success",
4  "timestamp": "2024-01-15T10:00:00Z",
5  "data": {
6    "auth_method": "WHITELIST",
7    "authorization_reference": "AUTH-REF-001",
8    "cdr_token": {
9      "contract_id": "NL-TNM-012345678905880-S",
10      "country_code": "NL",
11      "party_id": "TNM",
12      "type": "RFID",
13      "uid": "012345678905880"
14    },
15    "charging_periods": [
16      {
17        "dimensions": [
18          {
19            "type": "ENERGY",
20            "volume": 15.32
21          }
22        ],
23        "start_date_time": "2024-01-15T10:00:00Z",
24        "tariff_id": "TARIFF-001"
25      }
26    ],
27    "connector_id": "1",
28    "country_code": "NL",
29    "currency": "EUR",
30    "end_date_time": "2024-01-15T11:30:00Z",
31    "evse_uid": "3256",
32    "id": "SESSION-001",
33    "kwh": 15.32,
34    "last_updated": "2024-01-15T11:30:00Z",
35    "location_id": "LOC-001",
36    "meter_id": "METER-001",
37    "party_id": "CPO",
38    "start_date_time": "2024-01-15T10:00:00Z",
39    "status": "COMPLETED",
40    "total_cost": {
41      "excl_vat": 3.064,
42      "incl_vat": 3.7074
43    }
44  }
45}

`400` — invalid or missing parameters (HTTP 200, OCPI envelope)

application/json

Response example

1{
2  "status_code": 2001,
3  "status_message": "Invalid or missing parameters",
4  "timestamp": "2025-01-01T00:00:00Z",
5  "doc_url": "https://github.com/ocpplab/ocpi-gateway/blob/main/docs/errors.md#2001-invalid-parameters",
6  "errors": [
7    {
8      "field": "country_code",
9      "message": "expected 'NL' to match Token A identity",
10      "type": "value_error.identity_mismatch"
11    }
12  ]
13}

`401` — unauthorized

application/json

Response example

1{
2  "status_code": 2001,
3  "status_message": "Unauthorized",
4  "timestamp": "2025-01-01T00:00:00Z"
5}

`404` — not found

application/json

Response example

1{
2  "status_code": 2001,
3  "status_message": "Session not found",
4  "timestamp": "2025-01-01T00:00:00Z"
5}

`422` — validation error

application/json

Schema: HTTPValidationError

Field	Type	Required	Description
`detail`	`ValidationError[]`	No	`Detail`

Response example

1{
2  "detail": [
3    {
4      "loc": [],
5      "msg": "string",
6      "type": "string",
7      "input": {
8        "_type": "Input"
9      },
10      "ctx": {
11        "_type": "Context"
12      }
13    }
14  ]
15}

Examples

Shell, Python, and TypeScript (set OCPI_TOKEN when auth is required).

1curl -sS -X PATCH 'https://ocpi-api.gridos.co/ocpi/emsp/2.2.1/sessions/NL/ABC/SESSION1' \
2  -H "Authorization: Token $OCPI_TOKEN" \
3  -H 'Content-Type: application/json' \
4  -d '{"kwh":14.1,"status":"COMPLETED","end_date_time":"2020-03-09T11:37:32Z","last_updated":"2020-03-09T11:37:32Z"}'

OpenAPI reference

Receiver Session

PATCH/sessions/{country_code}/{party_id}/{session_id}

API: OCPI 2.2.1 (eMSP) · Module: Sessions (eMSP)
Base path: /sessions · Base URL: https://ocpi-api.gridos.co/ocpi/emsp/2.2.1

Overview

PATCH /sessions/{country_code}/{party_id}/{session_id}

Absolute URL: https://ocpi-api.gridos.co/ocpi/emsp/2.2.1/sessions/{country_code}/{party_id}/{session_id}

Requires authentication. Use Authorization: Token <token>. See OCPI credentials.

How to call

Quick Shell sample (set OCPI_TOKEN when auth is required). Full Python and TypeScript under Examples.

1curl -sS -X PATCH 'https://ocpi-api.gridos.co/ocpi/emsp/2.2.1/sessions/NL/ABC/SESSION1' \
2  -H "Authorization: Token $OCPI_TOKEN" \
3  -H 'Content-Type: application/json' \
4  -d '{"kwh":14.1,"status":"COMPLETED","end_date_time":"2020-03-09T11:37:32Z","last_updated":"2020-03-09T11:37:32Z"}'

Request

Path parameters

Name	Type	Required	Description
`country_code`	`string`	Yes	ISO-3166 alpha-2 country code (uppercase).
`party_id`	`string`	Yes	CPO/eMSP party ID (ISO-15118, 3 uppercase alphanumerics).
`session_id`	`string`	Yes	Session.id of the Session object.

Request body

application/json · Required

Schema: SessionUpdate

Field	Type	Required	Description
`country_code`	`string`	No	—
`party_id`	`string`	No	—
`id`	`string`	No	—
`start_date_time`	`string (date-time)`	No	—
`end_date_time`	`string (date-time)`	No	—
`kwh`	`number`	No	—
`cdr_token`	`CdrToken`	No	OCPI CdrToken: the token reference embedded in Sessions and CDRs.
`auth_method`	`"AUTH_REQUEST"	"COMMAND"	"WHITELIST"`
`authorization_reference`	`string`	No	—
`location_id`	`string`	No	—
`evse_uid`	`string`	No	—
`connector_id`	`string`	No	—
`meter_id`	`string`	No	—
`currency`	`string`	No	—
`charging_periods`	`object[]`	No	—
`total_cost`	`Price`	No	OCPI Price: an amount with and without VAT.
`status`	`"ACTIVE"	"COMPLETED"	"INVALID"
`last_updated`	`string (date-time)`	No	—

Request examples

Example 1

1{
2  "kwh": 14.1,
3  "status": "COMPLETED",
4  "end_date_time": "2020-03-09T11:37:32Z",
5  "last_updated": "2020-03-09T11:37:32Z"
6}

Example 2

1{
2  "charging_periods": [
3    {
4      "start_date_time": "2020-03-10T08:00:00Z",
5      "dimensions": [
6        {
7          "type": "ENERGY",
8          "volume": 18.75
9        }
10      ]
11    }
12  ],
13  "last_updated": "2020-03-10T08:30:00Z"
14}

Responses

Status	Description	Schema
`200`	Successful Response	`SessionResponse`
`400`	Invalid or missing parameters (HTTP 200, OCPI envelope)	`—`
`401`	Unauthorized	`—`
`404`	Not Found	`—`
`422`	Validation Error	`HTTPValidationError`

`200` — successful response

application/json

Schema: SessionResponse

Field	Type	Required	Description
`status_code`	`integer`	No	Default: `1000`
`status_message`	`string`	No	—
`timestamp`	`string (date-time)`	No	—
`data`	`SessionOut`	No	`SessionOut`

Response example

1{
2  "status_code": 1000,
3  "status_message": "Success",
4  "timestamp": "2024-01-15T10:00:00Z",
5  "data": {
6    "auth_method": "WHITELIST",
7    "authorization_reference": "AUTH-REF-001",
8    "cdr_token": {
9      "contract_id": "NL-TNM-012345678905880-S",
10      "country_code": "NL",
11      "party_id": "TNM",
12      "type": "RFID",
13      "uid": "012345678905880"
14    },
15    "charging_periods": [
16      {
17        "dimensions": [
18          {
19            "type": "ENERGY",
20            "volume": 15.32
21          }
22        ],
23        "start_date_time": "2024-01-15T10:00:00Z",
24        "tariff_id": "TARIFF-001"
25      }
26    ],
27    "connector_id": "1",
28    "country_code": "NL",
29    "currency": "EUR",
30    "end_date_time": "2024-01-15T11:30:00Z",
31    "evse_uid": "3256",
32    "id": "SESSION-001",
33    "kwh": 15.32,
34    "last_updated": "2024-01-15T11:30:00Z",
35    "location_id": "LOC-001",
36    "meter_id": "METER-001",
37    "party_id": "CPO",
38    "start_date_time": "2024-01-15T10:00:00Z",
39    "status": "COMPLETED",
40    "total_cost": {
41      "excl_vat": 3.064,
42      "incl_vat": 3.7074
43    }
44  }
45}

`400` — invalid or missing parameters (HTTP 200, OCPI envelope)

application/json

Response example

1{
2  "status_code": 2001,
3  "status_message": "Invalid or missing parameters",
4  "timestamp": "2025-01-01T00:00:00Z",
5  "doc_url": "https://github.com/ocpplab/ocpi-gateway/blob/main/docs/errors.md#2001-invalid-parameters",
6  "errors": [
7    {
8      "field": "country_code",
9      "message": "expected 'NL' to match Token A identity",
10      "type": "value_error.identity_mismatch"
11    }
12  ]
13}

`401` — unauthorized

application/json

Response example

1{
2  "status_code": 2001,
3  "status_message": "Unauthorized",
4  "timestamp": "2025-01-01T00:00:00Z"
5}

`404` — not found

application/json

Response example

1{
2  "status_code": 2001,
3  "status_message": "Session not found",
4  "timestamp": "2025-01-01T00:00:00Z"
5}

`422` — validation error

application/json

Schema: HTTPValidationError

Field	Type	Required	Description
`detail`	`ValidationError[]`	No	`Detail`

Response example

1{
2  "detail": [
3    {
4      "loc": [],
5      "msg": "string",
6      "type": "string",
7      "input": {
8        "_type": "Input"
9      },
10      "ctx": {
11        "_type": "Context"
12      }
13    }
14  ]
15}

Examples

Shell, Python, and TypeScript (set OCPI_TOKEN when auth is required).

1curl -sS -X PATCH 'https://ocpi-api.gridos.co/ocpi/emsp/2.2.1/sessions/NL/ABC/SESSION1' \
2  -H "Authorization: Token $OCPI_TOKEN" \
3  -H 'Content-Type: application/json' \
4  -d '{"kwh":14.1,"status":"COMPLETED","end_date_time":"2020-03-09T11:37:32Z","last_updated":"2020-03-09T11:37:32Z"}'

Receiver Session

Overview

How to call

Request

Path parameters

Request body

Request examples

Responses

`200` — successful response

`400` — invalid or missing parameters (HTTP 200, OCPI envelope)

`401` — unauthorized

`404` — not found

`422` — validation error

Examples

Is this helpful?

AI Tools

On this page

Receiver Session

Overview

How to call

Request

Path parameters

Request body

Request examples

Responses

`200` — successful response

`400` — invalid or missing parameters (HTTP 200, OCPI envelope)

`401` — unauthorized

`404` — not found

`422` — validation error

Examples

Is this helpful?

AI Tools

On this page