Bridging any device · Raven Docs

Printers and scales are devices Raven understands. A bridge is for everything else: any device on the venue network that speaks HTTP. Raven does not interpret it. Your request goes in one end and the device's own response comes out the other.

Payment terminals, kitchen display controllers, door controllers, weighing bridges with a web API, a piece of equipment with a vendor REST interface nobody has documented since 2015. If it answers HTTP on the LAN, you can reach it.

The proxy

ANY  /bridge/{deviceId}/{**path}

  method   → forwarded verbatim
  path     → appended to the device's own base
  query    → forwarded verbatim
  headers  → forwarded verbatim, minus Raven's own auth
  body     → forwarded verbatim (up to 256 KB)

It is a transparent reverse proxy over the venue's network boundary. You address the logical device by id, and everything after it is the device's own API. Raven adds no envelope, rewrites no body, and does not need to know what the device is.

Your backend

POST /bridge/{id}/api/v1/payment

X-Api-Key: rvn_live_…

Raven API

POST /api/v1/payment

Raven credentials stripped

Connector

POST /api/v1/payment

→ 192.168.1.80:8080

The device

POST /api/v1/payment

answers as its own docs say

Method, path, query, headers and body arrive at the device as you sent them. The only edit Raven makes is removing its own credential headers, so your key can never leak onto the venue's LAN. The response travels back the same way, unchanged.

The same request at four points. Only the Raven prefix and Raven's own credential headers come off; nothing else is touched on the way in or on the way back.

A call to a device's own endpoint

curl -X POST https://raven-api.formfl.be/bridge/{deviceId}/api/v1/payment \
  -H "X-Api-Key: $RAVEN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 1450, "currency": "EUR" }'

What comes back is whatever the device returned: its status code, its headers, its body. Your integration is written against the device's documentation, not against Raven's.

It is synchronous

Like weighing and unlike printing, a bridge call holds the connection open until the device answers. There is no queue, no retry, and no monitor URL: the device is either reachable now or it is not.

Code	Means	Do
Anything the device returns	Passed through unchanged, including its own `4xx`/`5xx`.	Handle it as the device's documentation says.
`504`	The device did not answer within 10 seconds.	Retry only if the operation is safe to repeat. Raven cannot know whether your call charged a card.
`503`	The connector is offline, or dropped mid-request. The venue is unreachable, not the device.	Retry with backoff; nothing reached the device.
`413`	Request body over 256 KB.	Not retryable as-is. Bridges are for control traffic, not file transfer.
`429`	Rate limited; the call never left Raven.	Retry with backoff. See Rate limits.
`409`	No hardware assigned to this bridge device.	Finish setting it up in the dashboard.

503 and 504 mean different things and deserve different messages: 503 is the venue's link and nothing was attempted; 504 is the device itself and the call may well have landed.

Idempotency is yours

Printing has an idempotency key because Raven owns the job. A bridge call is passed straight through, so Raven cannot make a repeat safe. On a 504 you genuinely do not know whether the device acted.

If the device has its own idempotency or reference-number mechanism, use it. If it does not, treat a timeout as unknown rather than failed, and reconcile against the device rather than retrying blind.

Setting one up

A bridge device is registered by hand, not discovered: a generic HTTP box does not announce what it is. The technician adds it with its address and a name, and creates a logical device bound to it. See Field runbook.

When to ask for something better

A bridge is the right answer when the device is one customer's, or when its API is already what you want to call. It is the wrong answer when you find yourself writing the same translation layer for the same class of hardware across many venues. That is a first-class device type, and it belongs in Raven rather than in every integration separately. Ask.

History

Every bridge call is recorded as an interaction, and each one is readable by id with your key. But there is no key-reachable endpoint that lists them: if you will ever need to know what was sent to the terminal at 19:42, store the interaction id against your own record when you make the call. Browsing them after the fact is a dashboard job. See Looking back at past jobs.