API Wiki

Role: None

Lists the OCPI versions the Hub supports.

Response

{ "data": [{ "version": "2.3.0", "url": "https://<hub>/api/ocpi/2.3.0/details" }] }

Role: None

Details for the 2.3.0 version — the module endpoints the Hub exposes.

Response

{
  "data": {
    "version": "2.3.0",
    "endpoints": [{ "identifier": "credentials", "role": "HUB", "url": "https://<hub>/api/ocpi/2.3.0/credentials" }]
  }
}

Role: TOKEN_A (one-time, pre-shared, issued out of band)

Initial handshake. The Hub fetches your declared versions/details endpoints, then issues a fresh TOKEN_B and creates a CONNECTED HubConnection. Your TOKEN_A is revoked in the same transaction.

Request body

{
  "token": "<your own TOKEN_C for the Hub to use later>",
  "url": "https://<your-csms>/ocpi/versions",
  "roles": [{ "role": "CPO" | "EMSP" | "HUB", "party_id": "<3 chars>", "country_code": "<2 chars>" }]
}

Response

{
  "token": "<new TOKEN_B>",
  "url": "https://<hub>/api/ocpi/2.3.0/versions",
  "roles": [{ "role": "HUB", "party_id": "LEA", "country_code": "ZZ" }]
}

Errors

Role: TOKEN_B (current)

Rotates the current TOKEN_B for a brand-new one. No request body.

Response

{ "token": "<new TOKEN_B>", "url": "https://<hub>/api/ocpi/2.3.0/versions", "roles": [{ "role": "HUB", "party_id": "LEA", "country_code": "ZZ" }] }

Errors

Role: TOKEN_B

Terminates the connection (status becomes TERMINATED).

Response

{}

Errors

Role: Any connected role

Paginated list of published Locations (publish: true only), ordered by most recently updated.

Role: Any connected role

A single Location — no publish filter applies here, unlike the list endpoint.

Errors

Role: CPO, must own country_code/party_id

Full upsert of a Location and its nested EVSEs/Connectors. Returns HTTP 201 whether created or updated.

Request body

{
  "id": "loc-001",
  "publish": true,
  "address": "...", "city": "...", "country": "...",
  "coordinates": { "latitude": "-34.6", "longitude": "-58.4" },
  "evses": [{
    "uid": "EVSE1",
    "status": "AVAILABLE",
    "connectors": [{
      "id": "1", "standard": "...", "format": "SOCKET",
      "power_type": "AC_3_PHASE", "max_voltage": 400, "max_amperage": 32
    }]
  }]
}

Response

{
  "country_code": "AR", "party_id": "EVR", "id": "loc-001", "publish": true,
  "address": "...", "city": "...", "country": "...",
  "coordinates": { "latitude": "-34.6", "longitude": "-58.4" },
  "evses": [{ "uid": "EVSE1", "evse_id": "...", "status": "AVAILABLE",
    "connectors": [{ "id": "1", "standard": "...", "format": "SOCKET",
      "power_type": "AC_3_PHASE", "max_voltage": 400, "max_amperage": 32, "last_updated": "<ISO>" }],
    "last_updated": "<ISO>" }],
  "last_updated": "<ISO>"
}

Errors

• evses[].connectors requires at least 1 entry when evses is present.

Role: CPO, must own country_code/party_id

Partial update. The Location must already exist. publish/address/city/country/coordinates are merged onto the existing record and the full object is re-validated and re-upserted (including EVSEs/Connectors). Returns HTTP 200.

Errors

Role: Any connected role

Paginated list of all Tariffs (no publish concept for this module).

Role: Any connected role

A single Tariff.

Errors

Role: CPO, must own country_code/party_id

Full upsert. Returns HTTP 201.

Request body

{
  "id": "tariff-1", "currency": "USD", "type": "REGULAR",
  "elements": [{ "price_components": [{ "type": "ENERGY", "price": 0.35, "step_size": 1 }] }]
}

Response

{
  "country_code": "AR", "party_id": "EVR", "id": "tariff-1", "currency": "USD", "type": "REGULAR",
  "elements": [{ "price_components": [{ "type": "ENERGY", "price": 0.35, "step_size": 1 }] }],
  "last_updated": "<ISO>"
}

Errors

Role: CPO, must own country_code/party_id

Deletes the Tariff.

Errors

Role: Any connected role

Paginated list of all Tokens.

Role: Any connected role

A single Token.

Errors

Role: EMSP, must own country_code/party_id

Full upsert. Returns HTTP 201.

Request body

{
  "uid": "04ABCD...", "type": "RFID", "contract_id": "...", "issuer": "...",
  "valid": true, "whitelist": "ALLOWED"
}

Response

{
  "country_code": "AR", "party_id": "EVR", "uid": "04ABCD...", "type": "RFID",
  "contract_id": "...", "issuer": "...", "valid": true, "whitelist": "ALLOWED",
  "last_updated": "<ISO>"
}

Errors

Role: EMSP, must own country_code/party_id

Partial update, applied field-by-field directly (no re-merge/re-validate pass, unlike Locations).

Errors

Role: EMSP, must own country_code/party_id

Deletes the Token.

Errors

Role: Caller must hold a CPO role (any country/party)

A CPO checking whether a token (owned by the eMSP identified by the path) may charge. The path segments identify the eMSP that owns the token, not the caller. This endpoint never returns an HTTP error for business failures — any internal failure (token not found, eMSP disconnected, endpoint not declared, 6-second proxy timeout) resolves to { "allowed": "BLOCKED" } rather than an exception.

Request body

{ "location_references"?: <any object, passed through as-is to the eMSP> }

Response

{ "allowed": "ALLOWED" }

Errors

• The Hub proxies this call to the eMSP's own declared tokens endpoint with a 6-second timeout, and forwards whatever the eMSP responds as the allowed value.

Role: Any connected role

Paginated list of all Sessions.

Role: Any connected role

A single Session.

Errors

Role: CPO, must own country_code/party_id

Full upsert. Returns HTTP 201.

Request body

{
  "id": "sess-1", "start_date_time": "<ISO>", "kwh": 12.5,
  "cdr_token": { "country_code": "AR", "party_id": "EVR", "uid": "...", "type": "RFID", "contract_id": "..." },
  "auth_method": "WHITELIST", "location_id": "loc-001", "evse_uid": "EVSE1",
  "connector_id": "1", "currency": "USD", "status": "ACTIVE"
}

Errors

Role: CPO, must own country_code/party_id

Partial update, applied field-by-field directly.

Errors

Role: Any connected role

Paginated list of all CDRs.

Role: Any connected role

A single CDR.

Errors

Role: CPO, must own country_code/party_id

Creates the CDR. Note this is POST, not PUT — a second POST with the same cdr_id is rejected. Returns HTTP 201.

Request body

{
  "id": "cdr-1", "start_date_time": "<ISO>", "end_date_time": "<ISO>",
  "cdr_token": { "country_code": "AR", "party_id": "EVR", "uid": "...", "type": "RFID", "contract_id": "..." },
  "auth_method": "WHITELIST",
  "cdr_location": { "id": "loc-001", "address": "...", "city": "...", "country": "...",
    "coordinates": { "latitude": "-34.6", "longitude": "-58.4" },
    "evse_uid": "EVSE1", "connector_id": "1", "connector_standard": "...",
    "connector_format": "SOCKET", "connector_power_type": "AC_3_PHASE" },
  "currency": "USD",
  "charging_periods": [{ "start_date_time": "<ISO>", "dimensions": [{ "type": "ENERGY", "volume": 12.5 }] }],
  "total_cost": { "excl_vat": 4.5 }, "total_energy": 12.5, "total_time": 0.5
}

Errors

Role: Caller must hold an EMSP role (any country/party)

command_type is one of CANCEL_RESERVATION, RESERVE_NOW, START_SESSION, STOP_SESSION, UNLOCK_CONNECTOR. START_SESSION/RESERVE_NOW resolve their target CPO via location_id; the other three via session_id. The response_url field in your request body is accepted by the schema but overridden — the Hub always injects its own internal callback URL when forwarding to the CPO.

Request body

// START_SESSION
{
  "response_url": "https://your-system/callback",
  "token": { "uid": "...", "type": "RFID", "contract_id": "..." },
  "location_id": "loc-001", "country_code": "AR", "party_id": "CPO1"
}

// STOP_SESSION / UNLOCK_CONNECTOR / CANCEL_RESERVATION
{
  "response_url": "https://your-system/callback",
  "session_id": "sess-1", "country_code": "AR", "party_id": "CPO1"
}

Response

{ "result": "ACCEPTED", "timeout": 30 }

Errors

• The Hub's outbound dispatch to the CPO has an 8-second timeout.
• A pending Command not resolved within 30 seconds is marked TIMEOUT the next time it is read via GET.

Role: None (security boundary is the unguessable command_id)

Called by the target CPO with the final async result. On success, the Hub best-effort re-forwards the same payload to the originating EMSP's own commands endpoint (fire-and-forget, failures are swallowed).

Request body

{ "result": "ACCEPTED" | "REJECTED" | "FAILED" | "TIMEOUT" | "UNKNOWN_RESERVATION", "message"?: {} }

Errors

Role: Any connected role

Fetches the current status of a Command. If the command has been pending for more than 30 seconds with no callback, it is lazily marked TIMEOUT before being returned.

Response

{
  "id": "<id>", "type": "START_SESSION", "payload": {},
  "ack_result": "ACCEPTED", "final_result": "ACCEPTED",
  "final_result_received_at": "<ISO>", "last_updated": "<ISO>"
}

Role: Caller must hold an EMSP role

action is one of GET_ACTIVE_CHARGING_PROFILE, PUT_CHARGING_PROFILE, DELETE_CHARGING_PROFILE. The Hub calls the CPO with the matching HTTP verb (GET/PUT/DELETE respectively) at its declared chargingprofiles endpoint.

Request body

// PUT_CHARGING_PROFILE
{
  "response_url": "https://your-system/callback",
  "charging_profile": {
    "charging_rate_unit": "W",
    "charging_profile_period": [{ "start_period": 0, "limit": 7400 }]
  }
}

// GET_ACTIVE_CHARGING_PROFILE / DELETE_CHARGING_PROFILE
{ "response_url": "https://your-system/callback" }

Response

{ "result": "ACCEPTED", "timeout": 30 }

Errors

• Same 8-second dispatch timeout and 30-second resolution timeout as Commands.
• Unlike Commands (which marks a stale request TIMEOUT), a stale Charging Profile request is marked FAILED on the next GET.

Role: None (security boundary is the unguessable id)

Called by the CPO with the final result. Best-effort re-forwarded to the originating EMSP's own chargingprofiles endpoint.

Request body

{ "result": "ACCEPTED" | "REJECTED" | "FAILED" | "UNKNOWN_SESSION", "charging_profile"?: {...} }

Errors

Role: Any connected role

Fetches the current status of a charging profile request.

Response

{
  "id": "<id>", "session_id": "sess-1", "action": "PUT_CHARGING_PROFILE",
  "ack_result": "ACCEPTED", "final_result": "ACCEPTED",
  "charging_profile": {...}, "last_updated": "<ISO>"
}

Role: Any connected role

Paginated list.

Role: Any connected role

A single reconciliation record.

Errors

Role: CPO or EMSP (either role for the party is accepted)

Full upsert, PUT-only (no POST, unlike CDRs). If discrepancy_amount is present, the Hub looks up the referenced CDR's currency and converts the amount to USD automatically.

Request body

{
  "id": "rec-1", "cdr_id": "cdr-1", "status": "DISPUTED",
  "discrepancy_description": "...",
  "discrepancy_amount": { "excl_vat": 1000 }
}

Response

{
  "country_code": "AR", "party_id": "EVR", "id": "rec-1", "cdr_id": "cdr-1", "status": "DISPUTED",
  "discrepancy_amount": { "excl_vat": 1000 },
  "discrepancy_currency": "ARS",
  "discrepancy_amount_usd": { "excl_vat": 1.05 },
  "exchange_rate_used": 950.3,
  "last_updated": "<ISO>"
}

Errors

• discrepancy_currency, discrepancy_amount_usd and exchange_rate_used only appear when discrepancy_amount was included in the request — a status-only PUT preserves whatever FX fields were already there.

Role: CPO or EMSP

Deletes the record.

Errors

Role: Any connected role

Paginated list, one entry per (connection × role) pair — a connection with 2 declared roles produces 2 entries.

Role: Any connected role

All role entries matching that country/party. Returns an empty array (not a 404) if none exist.

Response

[{ "party_id": "EVR", "country_code": "AR", "role": "CPO", "status": "CONNECTED", "last_updated": "<ISO>" }]