Protocol sandbox

A browser cannot speak gRPC, so this tab has no live client: call the service from Postman or grpcurl, as below. The server address is in Reference.

Inventory – gRPC

C6.10

The warehouse. Read the stock of a product, watch the catalog arrive as a stream, reserve units for yourself. A reservation is yours alone; the shop's stock never changes.

Method	Kind	What it does	Status codes you can meet
`GetStock`	unary	One product by SKU, with how many units are on hand, reserved by you and available.	`NOT_FOUND` `INVALID_ARGUMENT`
`ListStock`	server stream	The catalog's products, one message each. Filter by category, limit with `page_size`, slow it down with `interval_ms`.	`INVALID_ARGUMENT`
`ReserveItems`	unary	Reserve units for yourself, all lines or none. Needs your token or API key in the metadata.	`UNAUTHENTICATED` `INVALID_ARGUMENT` `NOT_FOUND` `FAILED_PRECONDITION` `RESOURCE_EXHAUSTED`

The service is reached over TLS: use a grpcs:// URL in Postman and no -plaintext in grpcurl. Reads need no sign-in. Reservations need your token or API key in the call metadata. The server has reflection, so tools can discover it by themselves.

How to call it from your tools

In Postman

1Create the request: New → gRPC, then enter the server URL

2Load the service: Postman asks the server (reflection). Or open Service definition → Import a .proto file and choose the file you downloaded

Download inventory.proto

3Pick the method GetStock, open Message, press Use Example Message and set the key – or paste this – then Invoke

4Reserving needs you: open Authorization, choose Bearer Token and paste your token (or add x-api-key in Metadata). Message for ReserveItems:

5Read the verdict in Trailers: grpc-status and grpc-message. Response Metadata has x-trace-id. A stream shows one message per item.

With grpcurl

Try a key that does not exist and read the status:

Your token goes with the connection as ?token=.Signed out: the server closes the connection with 4401. Sign in

Messages

Connect, then send the subscribe frame. Events of your order appear here as they happen.

Send a frame

{"type":"subscribe","order_id":12}

Place an order and pay it first – in the shop, or with the REST API on the API sandbox.

Order status – WebSocket

C6.11

A live feed for your orders. Subscribe with an order id and the server sends created, paid, packed and shipped as they happen. Pay for the order in the shop while you watch.

Direction	Frame	Meaning
you send	`{"type":"subscribe","order_id":…}`	Follow one order. The value is a whole number such as 12, or an order number such as SH-100012.
you send	`{"type":"unsubscribe",…}`	Stop following it.
you send	`{"type":"ping"}`	Application-level ping.
you get	`{"type":"subscribed",…}`	Your subscription is on. Events of that order follow.
you get	`{"type":"order.status","seq":…,"status":…}`	One status change: `created`, `payment_failed`, `paid`, `packed`, `shipped`, `cancelled`.
you get	`{"type":"pong"}`	The answer to your ping.
you get	`{"type":"error","code":…}`	Something is wrong with your frame. The connection stays open.

Every frame is JSON text. Events of one order arrive in order with a growing seq. Packing and shipping are simulated: a few seconds after payment. A frame you cannot use gets an error frame, not a closed connection.

How to call it from your tools

In Postman

1Create the request: New → WebSocket, then enter the URL

2Before you connect, open Headers and add Authorization with the value Bearer and your token. Or add a token parameter in Params.

3Press Connect. Without a token the connection opens and closes at once with code 4401.

4In the message composer choose JSON, paste this and press Send. The value is a whole number such as 12, or an order number such as SH-100012.

5Watch the messages list. Send a wrong value to see an error frame; send a ping to get a pong.

With wscat

Then type the subscribe frame and press Enter. An event looks like this:

And a mistake like this (the connection stays open):

Close codes

Close code	When
`4401`	No token or API key, or an invalid one.
`4429`	More than 5 open connections for your account.
`1009`	A frame larger than 4 KB.
`1001`	The server is stopping.

POST with Content-Type: text/xml; charset=utf-8, SOAPAction for the operation and your token. Capture and refund need the ids from the previous answer.

Envelope

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:gw="http://gateway.shelf.example.com/payments/v1">
  <soapenv:Header></soapenv:Header>
  <soapenv:Body>
    <gw:AuthorizeRequest>
      <gw:cardNumber>4242424242424242</gw:cardNumber>
      <gw:expiryMonth>12</gw:expiryMonth>
      <gw:expiryYear>2028</gw:expiryYear>
      <gw:cvc>123</gw:cvc>
      <gw:amount>49.00</gw:amount>
      <gw:currency>USD</gw:currency>
    </gw:AuthorizeRequest>
  </soapenv:Body>
</soapenv:Envelope>

Response

Send the envelope. A success is 200; a fault is 500 with a Fault in the body – normal for SOAP 1.1.

Payment gateway – SOAP

C6.8

The old gateway behind checkout: XML in, XML out. Authorize a test card, capture the money, refund it. Every error is a SOAP fault, with its own code in the detail.

Operation	What it does	Faults you can meet
`Authorize`	Check a test card and hold an amount. Returns `authorizationId`.	`GW-CARD-DECLINED` `GW-INSUFFICIENT-FUNDS` `GW-CARD-EXPIRED` `GW-INCORRECT-CVC` `GW-CARD-NOT-ACCEPTED` `GW-INVALID-REQUEST`
`Capture`	Take money from an authorization, once, up to its amount. Returns `captureId`.	`GW-AUTHORIZATION-NOT-FOUND` `GW-ALREADY-CAPTURED` `GW-CAPTURE-EXCEEDS-AUTHORIZATION`
`Refund`	Give money back from a capture, in parts, up to what was captured. Returns `refundId`.	`GW-CAPTURE-NOT-FOUND` `GW-REFUND-EXCEEDS-CAPTURE`

SOAP 1.1, document/literal. The contract is one WSDL file with the schema inside. Test cards only – they behave like the ones in the shop's checkout.

Test card	Brand	Result
`4242424242424242`	Visa	Authorized (payment succeeds)
`5555555555554444`	Mastercard	Authorized (payment succeeds)
`4000000000000002`	Visa	Fault `GW-CARD-DECLINED`
`4000000000009995`	Visa	Fault `GW-INSUFFICIENT-FUNDS`
`4000000000000069`	Visa	Fault `GW-CARD-EXPIRED`
`4000000000000127`	Visa	Fault `GW-INCORRECT-CVC`

How to call it from your tools

In Postman

1SOAP is plain HTTP: New → HTTP, method POST, URL:

2Headers: Content-Type = text/xml; charset=utf-8 (Postman sets application/xml, so change it), SOAPAction as below, and Authorization = Bearer and your token.

3Body → raw → XML, paste the envelope, press Send.

4Read the answer. A success is 200. A fault is 500 with a <Fault> in the body – for SOAP 1.1 that is normal. The gateway's own code is in <detail>.

SoapUI and similar tools can import the WSDL address above and build the requests for you.

With curl

Capture and refund need the ids from the previous answer. Instead of the HTTP header you can put <gw:AuthToken>token</gw:AuthToken> (or <gw:ApiKey>) in the SOAP header.

Faults at the envelope level

faultcode	Fault code in the detail	When
Client	`GW-INVALID-XML`	The body is not well-formed XML (or has a DTD).
Client	`GW-INVALID-REQUEST`	A missing, unexpected or invalid element or value.
Client	`GW-UNKNOWN-OPERATION`	The operation or its namespace is not in the WSDL.
Client	`GW-ACTION-MISMATCH`	The SOAPAction header names another operation.
Client	`GW-UNAUTHENTICATED`	No valid token or API key.
VersionMismatch	`GW-SOAP-VERSION`	A SOAP 1.2 envelope. Use SOAP 1.1.

Three more doors into Shelf: a gRPC stock service, a WebSocket feed of order status and a SOAP payment gateway. The same accounts, products and orders as the shop and the REST API – sign in once, then call them from Postman, grpcurl, wscat or curl.

Addresses

Sign in on the right first: most calls need your token

gRPC server (TLS)
gRPC contract – download or import
WebSocket
SOAP endpoint
SOAP contract (WSDL)
REST base URL – sign-in, orders, keys

Your access

Signed out

Bearer token · 8 hours

–

Header Authorization: Bearer <token>. Anyone with it can act as you until it expires.

API keys

Header X-API-Key: <key>. A key lasts until you revoke it.

Reset my data

Deletes your cart, coupon, orders, payments, products, stock reservations, gateway transactions and task progress. Your account and keys stay.

Your tasks

Inventory – gRPC

How to call it from your tools

In Postman

With grpcurl

Order status – WebSocket

How to call it from your tools

In Postman

With wscat

Close codes

Payment gateway – SOAP

How to call it from your tools

In Postman

With curl

Faults at the envelope level

Addresses