If you have ever tried to learn OCPI, you have probably hit the same wall. The protocol only really makes sense when you watch two parties talk to each other, but you cannot watch two parties talk until you have a roaming partner, and you do not want a roaming partner until you understand the protocol. That is a genuine chicken-and-egg problem, and it is easy to stall there, stuck at the reading-the-spec stage.
A sandbox breaks that loop. Instead of waiting on a partner’s test endpoints, you step through a complete OCPI 2.2.1 flow against a simulated counterparty and watch every request and response go by. You can try the interactive OCPI simulator right now. It stands in for the other side of the connection so you can run the whole sequence, from the credentials handshake to a final CDR, before you have signed a single roaming agreement. This article walks through what that full flow looks like and why practicing it in a sandbox is the fastest way to get fluent.
Why a sandbox beats reading the spec first
The OCPI specification is well written, but it is a reference document, not a tutorial. It describes each module in isolation (object shapes, endpoints, allowed values) and leaves you to assemble the choreography in your head. The parts that trip people up are almost never the field definitions. They are the sequencing: which side initiates, what happens asynchronously, and how a call you send comes back to you later through a different endpoint.
A sandbox makes that choreography visible. You are not memorizing that Commands are asynchronous; you send a START_SESSION command, get an immediate acknowledgement, and then watch the real result arrive separately as a CommandResult. That single observation teaches more than a paragraph ever will. If you want the conceptual grounding first, what OCPI is and why it exists sets the stage, but the sandbox is where the concepts turn into muscle memory.
The full flow, start to finish
Here is the sequence a sandbox lets you run end to end. Every step below is something you can trigger and inspect rather than imagine.
1. The credentials handshake
Every OCPI relationship opens with the same ritual: two parties exchange a Token A, then use the credentials and versions endpoints to agree on a version, register with each other, and swap the long-lived Token B and Token C used for real traffic. This exchange is short, mandatory, and disproportionately bug-prone. The usual culprits are expired tokens, unreachable version endpoints, a mismatched country_code or party_id, and rotation happening mid-flight.
Running it in a sandbox is valuable precisely because it is so easy to get subtly wrong. You see the version negotiation resolve, watch the registration exchange complete, and understand what “both sides now trust each other” actually means at the wire level. For the details behind the ceremony, the credentials and versions handshake breaks down each token and endpoint.
2. Locations: the CPO publishes where charging happens
With the handshake done, the CPO exposes its charging infrastructure through the Locations module: sites, EVSEs, connectors, and their live status. In a sandbox you can pull a Location and see the nested structure. A location contains EVSEs, each EVSE contains connectors, and each connector carries power, format, and tariff references.
This is also where you first meet OCPI’s two data-transfer styles. The eMSP can pull the full catalogue on a schedule, or the CPO can push incremental updates as status changes. Watching both in a simulator makes the trade-off concrete, and pull versus push patterns (coming soon) covers when each one is the right choice. If you want to go deeper on the object model afterward, the Locations module covers the hierarchy and the status semantics in full.
3. Sessions: a charge in progress
Once a driver plugs in, the CPO reports the charge through the Sessions module. A Session object updates over the life of the charge, carrying energy delivered, current status, and running cost, until it completes. In a sandbox you can watch a session open, tick through intermediate updates, and close, which is the clearest way to internalize that sessions are living objects rather than a single end-of-charge record.
This matters for reconciliation later: the session is the real-time view, and it must line up with the billing record that follows.
4. Commands: reaching back into the network
Commands is where OCPI stops being read-only. As an eMSP, you can send a START_SESSION or STOP_SESSION request, or RESERVE_NOW and UNLOCK_CONNECTOR, into the CPO’s network. These calls are asynchronous, and a sandbox drives that home instantly. You get an immediate ACCEPTED or REJECTED acknowledgement telling you the request was received, and then, separately, the actual outcome arrives at your callback URL as a CommandResult.
Seeing that two-part pattern once removes a whole class of integration bugs where developers treat the acknowledgement as the result and wonder why nothing seems to happen. The Commands module walks through each command type and its result codes.
5. CDRs: the charge becomes money
Finally, the completed charge is recorded as a CDR (Charge Detail Record), the immutable billing document that settles who owes what. A CDR is not editable after the fact. If something is wrong, you issue a correction rather than mutating the original. In a sandbox you can generate a CDR at the end of a session and compare it against the session data it came from, which is exactly the reconciliation exercise you will do for real in production. The CDRs module covers the field-level detail behind that record.
What a sandbox teaches that a spec cannot
Run the sequence above a few times and some patterns click that no amount of reading delivers:
- The response envelope is universal. Every OCPI call, regardless of module, comes back wrapped in the same structure: a
status_code, astatus_message, atimestamp, and thedatapayload. Once you have seen it on five different endpoints, you stop parsing each response as a special case. - Push and pull are a design choice, not a rule. The same
Locationsdata can arrive because you asked for it or because the partner sent it. A sandbox lets you feel the difference in latency and load rather than just reading about it. - Asynchronous is the default mental model. Commands come back later, sessions update over time, and CDRs arrive after the fact. OCPI is an eventually-consistent conversation between two systems, and watching it flow is the fastest way to stop thinking in request-then-immediate-response terms.
Where the sandbox ends and real testing begins
Be honest about the boundary. A sandbox is a teaching and shakeout tool. It gives you a cooperative, well-behaved counterparty that always speaks the spec correctly. That is exactly what you want when you are learning. It is also exactly what a real partner is not.
The bugs that actually hurt in production come from two systems interpreting the same spec differently: an optional field one side treats as required, a status transition one side never emits, a tariff structure that is technically valid but unexpected. No simulator can predict those, because they are disagreements, not errors. So the right progression is to learn the flow in the sandbox, validate your payloads against the JSON schema, then move to a cooperative real partner or a roaming hub for the interpretation differences. For the full testing playbook (mocks, schema validation in CI, and the operational tests that catch real bugs), see OCPI testing tools and strategies.
The flow itself does not change by market. The message sequence is the same whether your counterparty sits in Europe or North America, because it is defined by the spec, not by geography. What varies between partners is which optional fields they populate, which modules they expose, and which version their endpoints speak. Those are questions you answer by reading a specific partner’s integration documentation, and no simulator can answer them for you.
Start with the flow, not the field list
The single best thing you can do to get comfortable with OCPI is to stop reading modules in isolation and watch one complete transaction move through all of them. Handshake, publish, charge, command, settle. Once that sequence is in your head as a story rather than a set of endpoints, the spec reads like documentation for something you already understand.
So open the OCPI simulator and run the full flow a couple of times. Then run it once more with a different question in mind: which fields did the simulator fill in that the spec marks optional? That list is the useful output of the exercise. A sandbox populates everything it can, and a real partner populates only what its own platform happens to track, so the gap between those two is where your first live integration will break. You cannot test that gap in a simulator, but you can leave the simulator knowing exactly where to look for it.