1. Home
  2. Integrations
  3. Utility API sandbox

Solution

Utility API sandbox: test billing and HES integrations before the project starts

Last updated

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:

  1. Work order out. Read the open exchange work orders from the billing API.
  2. Field closeout in. Post the removed meter, its final reading, the new meter and its initial reading.
  3. Billing confirms. The billing side checks the serials and readings, removes the old device, installs the new one and confirms the initial reading.
  4. Head-end registers. The new meter appears on the HES as Registered, then Communicating.
  5. First read lands. One register read per simulated day arrives on the HES.

The three surfaces

SurfaceImitatesHighlights
SAP-style billingOData v2 service in the style of SAP IS-U$metadata, $top/$skip/$filter, __next paging, CSRF token on writes, /Date()/ dates
Oracle-style billingREST and SOAP services in the style of Oracle CC&Blimit/offset with hasMore, YYYY-MM-DD-HH.MM.SS dates, SOAP inbound web service with WS-Security
HES / MDMIEC 61968-9-style head-endEndDevices, 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:

SwitchWhat happens
desync_same_dayBilling 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_offlineThe meter registers but never starts communicating.
rate_limitMore than 10 calls in 10 seconds returns HTTP 429 with Retry-After.
server_errorEvery third call returns HTTP 503.
slowEvery call waits 3 seconds.
duplicate_idsEach 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

Free trial · no card

See it with your own crew

Start a free trial, or ask us for a walkthrough of your rollout.

Related