- Home
- Integrations
- Utility API sandbox
Solution
Utility API sandbox: test billing and HES integrations before the project starts
The PIEBENCH utility API sandbox is a free, hosted, simulated utility. It exposes an SAP-style OData billing API, an Oracle-style REST and SOAP billing API and an IEC 61968-9-style head-end API. They share one state, so a meter exchange posted to billing shows up as a registered, communicating meter on the HES. No sign-up is needed.
Why this exists
Integrators who connect field, billing and head-end systems usually can't get a test endpoint until a contract is signed. Vendor sandboxes sit behind partner programmes or licensed test tenants, and the standards bodies sell the specifications. So the first time an integration meets real system behaviour is often on the utility's own test environment, weeks into the project.
We built this sandbox to test our own integration layer, Connectorly, against the behaviour that breaks integrations in practice: paging, authentication handshakes, odd date formats, rejected readings and messages that never arrive. It's free for anyone to use.
What a meter exchange looks like here
Every workspace starts with 60 service points, each with an installed meter, 60 new meters in stock and 12 open Exchange Meter work orders. The loop the sandbox simulates is the one utility contracts check:
- Work order out. Read the open exchange work orders from the billing API.
- Field closeout in. Post the removed meter, its final reading, the new meter and its initial reading.
- Billing confirms. The billing side checks the serials and readings, removes the old device, installs the new one and confirms the initial reading.
- Head-end registers. The new meter appears on the HES as Registered, then Communicating.
- First read lands. One register read per simulated day arrives on the HES.
The three surfaces
| Surface | Imitates | Highlights |
|---|---|---|
| SAP-style billing | OData v2 service in the style of SAP IS-U | $metadata, $top/$skip/$filter, __next paging, CSRF token on writes, /Date()/ dates |
| Oracle-style billing | REST and SOAP services in the style of Oracle CC&B | limit/offset with hasMore, YYYY-MM-DD-HH.MM.SS dates, SOAP inbound web service with WS-Security |
| HES / MDM | IEC 61968-9-style head-end | EndDevices, MeterReadings and EndDeviceEvents in JSON or XML, cursor paging |
Authentication covers HTTP Basic, OAuth 2.0 client credentials and API keys. The test credentials are published on the discovery endpoint.
Failure cases you can switch on
Happy-path mocks don't find the bugs that cost projects time. Each workspace has switches for documented failure modes:
| Switch | What happens |
|---|---|
desync_same_day | Billing accepts the meter swap but never tells the HES, so the new meter stays unknown to the head-end until you register it. SAP describes a same-day removal and installation not reaching the meter data system in support note 2520360. |
hes_offline | The meter registers but never starts communicating. |
rate_limit | More than 10 calls in 10 seconds returns HTTP 429 with Retry-After. |
server_error | Every third call returns HTTP 503. |
slow | Every call waits 3 seconds. |
duplicate_ids | Each page after the first repeats the previous page's last row. |
Business rules apply all the time. A reading lower than the previous one is rejected as implausible. A reading dated outside a meter's installation period is rejected. An upload of more than 600 readings is refused. A removed serial that doesn't match the installed meter is refused.
The acceptance report
GET /_control/acceptance grades every completed exchange against four checks taken from real contracts:
- Initial reading confirmed in billing.
- Closeout within 2 business days. Australia's B2B procedures set this window for the notice of metering works.
- Commissioned within 4 days. One US co-op AMI tender sets this target.
- First billing-cycle read. At least one read 30 days after installation. A US co-op installation tender accepts installs only after reads for two consecutive billing periods.
Use POST /_control/clock to fast-forward simulated time, so you can see a 30-day check pass without waiting a month.
Try it in two minutes
No code needed: run a meter exchange in your browser. The playground shows every HTTP request it makes, so you can copy them as curl.
Or from a terminal, create a workspace. The response holds your workspace ID and every base URL:
curl -X POST https://sandbox.piebench.com/workspaces
Then list the open work orders on the SAP-style surface, replacing ws_… with your ID:
curl -u 'SBX_USER:Sandbox#1' "https://sandbox.piebench.com/ws_…/sap/opu/odata/sap/ZPB_UTILITIES_SRV/WorkOrders?\$filter=Status%20eq%20'Open'"
In Windows PowerShell, type curl.exe, not curl. The discovery endpoint at https://sandbox.piebench.com lists every surface, credential and switch.
Use it from an AI coding agent
The sandbox has its own public MCP server, so an agent such as Claude Code, Cursor or Copilot can create a workspace, look up endpoints and payloads, switch failure modes on, fast-forward the clock and read the acceptance report. The agent still calls the billing and HES APIs over HTTP itself, so your integration code is what gets tested.
claude mcp add --transport http piebench-sandbox https://sandbox.piebench.com/mcp
It needs no sign-in. Each session can create up to 3 workspaces and make 60 tool calls a minute.
Limits and honest caveats
- Vendor-style, not vendor copies. The APIs imitate how SAP- and Oracle-style systems behave: envelopes, paging, dates and error shapes. They don't reproduce any vendor's schema, and error codes are illustrative. PIEBENCH isn't affiliated with SAP or Oracle.
- Disposable state. Workspaces live in memory. Ones idle for over an hour may be recycled, and any may be reset during maintenance.
- Fair use. Each IP can make up to 300 calls a minute and create 10 workspaces an hour. Each workspace can take 120 calls a minute and 5,000 a day. A request that fails the same way 10 times in a row is paused for a minute, so a stuck retry loop stops by itself.
- Keep your workspace ID private. Anyone who has it can use that workspace.
Where PIEBENCH fits
The sandbox simulates the utility side. PIEBENCH is the field side: an offline Android app that captures the exchange (serials by barcode, readings, photos, GPS), supervisor approval, and no-code integrations that send approved jobs to billing and the HES. If you're planning a rollout and want to see that loop against your own systems, talk to us.
Built to integrate with your systems
HES, MDM, SAP IS-U, Oracle CC&B and billing systems, over REST, OAuth or a direct SQL connection. How integrations work
Questions buyers ask
Is the utility API sandbox free?
Yes. There is no sign-up and no charge. Create a workspace with one POST request and use it straight away. Fair-use limits apply: 300 calls a minute and 10 new workspaces an hour per IP, and 120 calls a minute and 5,000 a day per workspace.
Is this a real SAP or Oracle system?
No. It is a simulator that imitates SAP-style and Oracle-style API behaviour, such as OData paging, CSRF tokens, OUAF date formats and SOAP faults. It doesn't contain vendor software or schemas, and PIEBENCH isn't affiliated with SAP or Oracle.
How is this different from a mock server like Beeceptor or Postman mocks?
A mock server returns canned responses. This sandbox keeps state and applies billing and head-end rules: it rejects a mismatched serial, confirms an initial reading, registers the new meter on the HES and produces reads over simulated time.
Can I test failures, not just the happy path?
Yes. Switch on rate limiting, server errors, slow responses, duplicate rows across pages, a head-end that never hears about the meter swap, or a meter that never communicates. Each is a single PUT request to your workspace.
How long does my data last?
Workspaces are held in memory. One that has had no calls for over an hour may be recycled when the sandbox is busy, and any workspace may be reset during maintenance. Treat them as disposable test environments.
Can an AI agent use the sandbox?
Yes. Add the sandbox MCP server to Claude Code, Cursor or another MCP client. The agent can create a workspace, read endpoints and example payloads, switch failures on, fast-forward time and read the acceptance report. It calls the APIs over HTTP itself.
Do I need PIEBENCH to use the sandbox?
No. Any HTTP client works: curl, Postman, SoapUI, an integration platform or your own code. PIEBENCH's field app and Connectorly are separate products.
Sources
- SAP KBA 2520360 — same-day removal and installation not sent to MDUS
- AEMO B2B Procedure: One Way Notification Process (notice of metering works timing)
- AEMO B2B Procedure: Service Order Process v4.01
- Washington Electric Cooperative AMI RFP (2024)
- Rappahannock Electric Cooperative AMI Installation Services RFP (October 2025)
Free trial · no card
See it with your own crew
Start a free trial, or ask us for a walkthrough of your rollout.