papiNet REST API
A secured HTTPS API for your trading partners, built from the papiNet specification and carried over your message queue to the system that holds the data.
papiNet is the paper and forest-products industry's standard for supply-chain messages. Its REST API describes how a logistics supplier asks a supplier for supplier orders, delivery instructions and delivery notes, and reports goods receipts and inventory changes. Archr.Hermod serves that API for you: your trading partners call an ordinary HTTPS endpoint, and your own system never has to face the internet.
Archr.Hermod reads the papiNet document and publishes one endpoint for each operation in it. There is no endpoint code to write or keep in step with the specification. It does not interpret the business content: it authenticates, validates, carries and records, and your back-end system does the real work.
How a call is handled
- The operation is found from the papiNet document. The exact papiNet version is part of
the address (for example
/papinet/4.0.0/supplier-orders). - The caller is authenticated by API key. The key belongs to a caller record that carries attributes you define, such as an application id, a business unit or the parties the caller may see. They are set by you, not by the caller, and reach your back end with the request so it knows whose data to return.
- The request is validated against the document's JSON Schema — path, query and body.
A request that does not comply is refused with
400and never reaches your system. - A request message is published on your message queue (NATS or Kafka), on a topic named
after the version and the operation, such as
papinet.v4-0-0.get-supplier-orders.request, with a correlation id and a deadline. - Your back end replies with a status and a body. Archr.Hermod passes through only the statuses the
document declares for that operation; anything else becomes
502. Optionally, the body of a successful reply is checked against the document too. - No reply before the deadline (30 seconds by default) gives the caller
504, so a caller is never left waiting.
Versions never change underneath a partner
Every papiNet version is a separate, immutable API, and several can be live at the same time. An
administrator chooses which versions are live; an alias such as v4 can point at one registered
version, and moves only when an administrator moves it. Because the version is in the topic name,
switching a version on cannot deliver messages to a back end that does not know it.
Administration
- Callers and keys. Create callers, issue keys with an expiry date, revoke them, and see exactly which attribute values each key sends. A new key is shown once.
- Switches. Turn a whole version, or a single operation, on or off. Partners calling an operation
that is switched off get
404from the next request. - Development responder. An optional responder answers with papiNet's own example data, so a partner can build against the API before your back end exists.
- Record and metrics. Every request is recorded as metadata (caller, operation, version, status, time taken), not its content, and counted in the same OpenTelemetry metrics as the rest of Archr.Hermod.
The API is off until an administrator switches it on, and it needs a message queue. Without one it does not start.