Zynka ONE - OCPI vs CPO Onboarding Specification

1. Introduction

The Open Charge Point Interface (OCPI) is an open protocol used by charge point operators (CPOs) and e-mobility service providers (eMSPs) to exchange information about charging locations, tariffs, tokens, session control commands, and billing.

For non-session operations (everything except charging sessions and CDRs), OCPI defines modules for data synchronization. This specification explains how Zynka One, acting as an eMSP and OCPI Hub, onboards CPOs and facilitates exchange of non-session data and remote commands.

It complements the UPI–OCPI Integration Specification and defines backlog-ready user stories for onboarding and message processing.

---

2. Business Use Case

As a CPO, I want to onboard onto Zynka One so that my charging locations, EVSEs, and tariffs are accessible to eMSPs and EV drivers, and I can receive remote commands without integrating with each eMSP individually.

Actors:

• CPO Admin – registers and maintains CPO data
• Zynka One (eMSP/Hub) – stores credentials, synchronizes non-session data, and routes remote commands
• eMSP – accesses CPO data through Zynka and issues commands
• EV Driver – benefits from real-time and consistent data

Preconditions:

• Parties agree on an OCPI version (e.g., 2.2.1).
• Credentials tokens are exchanged securely.
• Location identifiers follow eMI3/IDACS conventions.
• At least one location and tariff exist in the CPO CMS.

Postconditions:

• CPO credentials registered with Zynka
• Locations, EVSEs, and tariffs synchronized
• Tokens cached for offline authorization
• Remote commands executed asynchronously

---

3. Functional Use Cases

Each use case includes actor, flow, data references, and idempotency. All HTTP traffic is secured (TLS + Authorization headers). Push is preferred; pull is supported for recovery.

3.1 OCPI Registration (CPO → Zynka)

Goal: Exchange credentials tokens and register endpoints.

Flow:

1. CPO Admin requests onboarding; receives one-time token & versions URL (CREDENTIALS_TOKEN_A).

2. CPO calls GET /versions using the token to discover endpoints.

3. CPO POST /credentials to Zynka with:

   • token: new CPO token
   • url: base version URL
   • roles: list of CPO roles with business details

4. Zynka stores token, responds with its own (CREDENTIALS_TOKEN_C).

5. Zynka calls the CPO’s /versions and /credentials to confirm.

6. Onboarding token is discarded.

Alt-Flows:

• Invalid version → abort & notify
• Endpoint discovery fails → retry

Data: party_id, country_code, business_details, roles, version_url, token

---

3.2 Publish Locations & EVSEs (CPO → Zynka)

Goal: Keep eMSPs updated with latest CPO site and EVSE data.

Flow:

• CPO builds and pushes PUT /locations/{country}/{party}/{id}.
• Zynka validates and stores the data.
• Zynka pulls via GET /locations for recovery or sync.
• EVSE removals set status = REMOVED (no deletions).
• Zynka updates its directory for eMSPs.

Alt-Flows:

• Validation error → return 200 with OCPI error
• Invalid removal → reject

Data: location_id, evse_uid, connector_id, status, last_updated

---

3.3 Update Location Status & Grouping (CPO → Zynka)

Goal: Manage availability and grouping.

Flow:

• CPO updates EVSE status (UNAVAILABLE, etc.) via push.
• Supports virtual EVSEs for multi-connector stations.
• Multiple chargers in same area grouped under one location.

Alt-Flows:

• Uncertain sync → call GET /locations/{id}

Data: location_id, evse_uid, status

---

3.4 Publish Tariffs (CPO → Zynka)

Goal: Provide pricing updates.

Flow:

• Push via PUT /tariffs/{country}/{party}/{tariff_id}
• Update with another PUT; delete with DELETE /tariffs/...
• Zynka pulls via GET /tariffs if sync fails.

Alt-Flows:

• Invalid delete → reject
• Cache mismatch → pull full list

Data: tariff_id, currency, elements, last_updated

---

3.5 Token Synchronization (eMSP → Zynka → CPO)

Goal: Enable authorization using cached tokens.

Flow:

• eMSP pushes tokens (PUT /tokens/{...}) to Zynka.
• Zynka forwards tokens to CPO.
• Invalidate via updated valid=false.
• Real-time authorization via POST /tokens/{...}/authorize.

Alt-Flows:

• Network issues → fallback to whitelist
• Unknown token → reject

Data: token_uid, type, contract_id, issuer, whitelist, valid

---

3.6 Remote Commands (eMSP → Zynka → CPO)

Goal: Support RESERVE_NOW, UNLOCK_CONNECTOR, etc.

Flow:

1. eMSP sends command to POST /commands/{command}
2. Zynka forwards to CPO
3. CPO executes via CSMS (e.g., OCPP)
4. CPO reports result (ACCEPTED, FAILED, etc.) to Zynka
5. Zynka relays result to eMSP

Alt-Flows:

• Invalid location or connector → reject
• Timeout → Zynka notifies eMSP

Data: command_id, location_id, evse_uid, token_uid, expiry_date, response_url

---

3.7 Offboarding / Credential Update (Either Direction)

Goal: Rotate or revoke tokens.

Flow:

• Initiator PUT /credentials with new token.
• Receiver responds with new token; both invalidate old ones.
• To unregister → DELETE /credentials.

Data: token, url, roles

---

4. Usage Flows

4.1 Registration & Endpoint Exchange

• Credentials exchanged, versions discovered.
• All further calls use new tokens & OCPI transport rules.

4.2 Location & Tariff Synchronization

• Push model: PUT /locations, PUT /tariffs
• Pull model: GET /locations, GET /tariffs
• EVSE removals → status=REMOVED
• Grouping of charge points into single location

4.3 Token Sharing & Authorization

• Push: PUT/PATCH /tokens
• Pull: GET /tokens
• Real-time: POST /tokens/authorize

4.4 Command Processing

• Asynchronous with response_url callbacks

---

5. OCPI Modules & Endpoint Summary

Module	Purpose	Example Endpoints
Credentials	Exchange tokens	/credentials (GET/POST/PUT/DELETE)
Versions	Discover supported versions	/versions
Locations	Publish EVSE and connectors	/locations
Tariffs	Publish pricing	/tariffs
Tokens	Authorize drivers	/tokens, /tokens/authorize
Commands	Remote operations	/commands/*
Sessions/CDRs	Managed separately (UPI–OCPI Spec)	/sessions, /cdrs

---

6. Traceability Matrix

Use Case	OCPI Entity	API	Outcome
Registration	Credentials	/credentials	Tokens exchanged
Push Locations	Locations	/locations	Stations visible to eMSPs
Update Location	Locations	/locations	EVSE updated
Push Tariffs	Tariffs	/tariffs	Pricing published
Delete Tariff	Tariffs	/tariffs (DELETE)	Tariff removed
Token Sync	Tokens	/tokens	Tokens cached
Real-Time Auth	Tokens	/tokens/authorize	Token verified
Commands	Commands	/commands/*	Remote action executed
Credential Update	Credentials	/credentials	Token rotated

---

7. Summary

Zynka One, acting as an e-Mobility Service Provider and OCPI Hub, enables CPOs to onboard and synchronize non-session data—locations, tariffs, and tokens—while supporting asynchronous remote commands for a seamless and interoperable EV charging experience.