The platform's interfaces, in one map
Your ERP integrator wants orders out and stock in. Your BI team wants a nightly extract. Your customer's procurement lead wants a punchout. All three will ask you the same question — "what's the API?" — and the honest answer is that there are five interfaces and the API is only one of them.
Five interfaces, five jobs
| Interface | What it is | Reach for it when | Not for |
|---|---|---|---|
| REST API | HTTP + JSON at https://api.revenexx.com/v1 | Your system asks a question or makes a change, now | Moving a million rows |
| Webhooks | The platform calls you when something happens | You need to know about an order the moment it is placed | Getting the current state of everything |
| Bulk import / export | File-shaped jobs for large data sets | Nightly catalog, price list, or a BI extract | Anything a person is waiting for |
| Punchout | Your catalog rendered inside a customer's procurement system | A large customer buys through SAP Ariba, Coupa, Onventis or JAGGAER | Any of your own systems |
| SFTP | A managed folder your systems drop files into | The ERP only speaks CSV and nobody will build an API | Anything needing an immediate answer |
Two of the five are covered elsewhere and this area does not repeat them: punchout is a commercial project per customer, and the workflow engine that schedules and maps file jobs lives in Integration Studio.
Sync or async: who waits for whom
Everything above is one of two shapes, and the shape decides your failure modes.
| Synchronous — you call, you wait | Asynchronous — you are told, or you poll | |
|---|---|---|
| Examples | REST reads and writes | Webhooks, bulk jobs, SFTP |
| Latency | Immediate, and you own the timeout | Seconds to hours |
| What failure looks like | An error code you can react to | A delivery that has not arrived yet |
| Who carries the load | The caller, in the moment | A queue |
| Needs | Backoff, a timeout, a retry rule | Deduplication, an event log, reconciliation |
The rule of thumb: pull when you need an answer, be pushed when you need to
react. A system that polls /orders every thirty seconds to see whether
anything is new is doing the platform's job badly. Subscribe to the event and
poll once an hour as a safety net instead.
That safety net is not optional. A webhook is a delivery attempt, not a guarantee — see Events and webhooks.
One API, many apps
The platform is a set of installed apps — Products, Prices, Orders, Carts,
Customers, Inventories and whatever else your tenant runs. They do not each get
their own hostname. There is one gateway, at api.revenexx.com, and every
path is versioned under /v1:
https://api.revenexx.com/v1/orders
https://api.revenexx.com/v1/products
https://api.revenexx.com/v1/inventories/stock
https://api.revenexx.com/v1/customers/organizations
Three consequences your integrator should know on day one:
Which resources exist depends on which apps are installed. A tenant without
the Inventories app has no /inventories. This is why the reference is
generated per tenant rather than published as one static document — see below.
Everything is scoped to a tenant by a header, never by the URL. There is no
/acme-eu/orders. The tenant is X-Revenexx-Tenant, and it is required on
every call.
Resources follow one predictable shape, so once your integrator has learned one, they have learned all of them:
| Pattern | Method | Means |
|---|---|---|
/v1/{resource} | GET | List, with limit, offset and order |
/v1/{resource} | POST | Create one |
/v1/{resource}/{id} | GET | Read one |
/v1/{resource}/{id} | PUT / PATCH | Update one |
/v1/{resource}/{id} | DELETE | Remove one |
/v1/{resource}/search | POST | List, when the filter is too big for a query string |
/v1/{resource}/{id}/{action} | POST | Do something to it — orders/{id}/cancel |
The reference your integrator should actually use
Your tenant publishes its own OpenAPI document, listing exactly the resources and fields your installed apps expose:
https://api.revenexx.com/v1/openapi.json
That, not any prose page, is the authority on what exists. Point your integrator at it in the first conversation and it removes a week of guessing.
What a call looks like
GET /v1/orders?limit=50&order=created_at.desc HTTP/1.1
Host: api.revenexx.com
X-Revenexx-Tenant: acme-eu
X-Revenexx-Api-Key: rvxk_…
A list answers in a consistent envelope:
{ "items": [ ... ], "total": 248, "limit": 50, "offset": 0 }
and an error in a consistent one too:
{ "error": true, "message": "missing X-Revenexx-Tenant header" }
data or items object depend on your installed apps and their
versions — take those from your tenant's openapi.json, not from an example
here.Every response also carries an X-Request-ID. Have your integrator log it. It
is the one thing that turns "the API was returning errors on Tuesday" into a
support case somebody can answer.
Versioning, and what "stable" means for you
There is one current version, /v1, and it evolves additively: new
resources, new optional fields, new optional parameters. Additive means an
integration that ignores what it does not recognise keeps working — which is why
the first rule you give any integrator is ignore unknown fields, do not fail on
them.
Breaking changes do not appear inside /v1 unannounced. They are announced
ahead of time on the changelog, with a migration path and a deprecation window.
See Handling API changes.
Where the Developer Portal takes over
This area stops where writing an app begins. The boundary is worth being clear about, because it is the difference between something your own IT can do this week and something that needs a development project.
| This Help Center | The Developer Portal at revenexx.dev |
|---|---|
| Getting an API key, and scoping it safely | SDKs, the CLI, and code |
| What the interfaces are and which to choose | The full endpoint reference and API explorer |
| Setting up webhooks and reading the delivery log | Writing the receiver |
| Bulk import and export from the Cockpit | The bulk data API and file streaming |
| Sandbox, go-live checklist, monitoring | Building an app, a theme, or a storefront |
Neither audience is wrong; they are different jobs. Your ERP integrator connecting two existing systems lives here. A partner building a new app on the platform lives there.
Next
- Keys, scopes and tenants — how access works, and how to give an integrator exactly enough.
- Common API tasks, by job — orders out, stock in, prices in, customers in.