SDK guide 1: A comprehensive overview of how to use Java, C#, TypeScript and Python with Archr.Hermod
Using the SDK with your back-end systems, SDK reference by language, and the handling the papiNet messages.
Archr.Hermod sits between your trading partners and your own systems. Your system talks to it through a message queue, in plain JSON, and it does so for two jobs. This guide says what the SDK holds for each language and what the messages look like; the next two guides do the jobs step by step, with code.
The two jobs
- Serving. A trading partner calls Archr.Hermod's papiNet REST API. Archr.Hermod checks the key and the request, puts the request on the queue, and your back end answers it. Guide 2.
- Calling. Your application needs something from a partner's papiNet API. It tells Archr.Hermod which partner and which operation; Archr.Hermod holds the partner's address and key, makes the call and returns the answer. Guide 3.
What each language has
| C# (.NET Framework 4.6.1+, .NET 8+) | Java (8 and later) | TypeScript (Node.js) | Python (3.9 and later) | |
|---|---|---|---|---|
| Message types and the classes of every papiNet version | Hermod.PapiNet.Contracts (.NET Standard 2.0) |
archr-papinet-contracts |
@archr/papinet: the messages, and one V<version>.ts of interfaces per version |
archr-papinet: the messages, and one module of TypedDicts per version (v4_0_0) |
| Serve the API | Hermod.PapiNet.HostAdapter: the adapter subscribes, calls your handler, publishes the reply (Kafka) |
archr-papinet-host-adapter: the same (Kafka) |
@archr/papinet: the same (Kafka, through kafkajs) |
archr-papinet: the same (Kafka, through confluent-kafka) |
| Call partners | PapinetClient in Hermod.PapiNet.HostAdapter: a client that makes the call and returns the outcome (Kafka) |
archr-papinet-client: a client that makes the call and returns the outcome (Kafka) |
PapinetClient in @archr/papinet: the same (Kafka) |
Client in archr-papinet: the same (Kafka) |
Any other language can do both jobs from the messages alone: they are described below, and the download holds a JSON Schema for them.
Getting it
- The download. In the Admin pages, papiNet API, the Client contracts button of a version gives a zip with the C#, TypeScript, Java and Python classes of that version (the Java ones as a Maven project that builds into a jar), the JSON Schemas of the messages, the papiNet document and a list of every operation with its topics. It covers a version that was added after the libraries were built.
- C#.
Hermod.PapiNet.ContractsandHermod.PapiNet.HostAdapter(version 1.0.0, which holds both the adapter and the client) are built from the source. They are not on a public package feed yet. - Java. The toolkit is in the source folder
javawith a Maven wrapper:./mvnw installputssoftware.archr.papinet:archr-papinet-contracts,…-host-adapterand…-clientin your local Maven repository. They are not on Maven Central yet. - Python. The toolkit is in the source folder
python:pip install ./pythoninstalls it, withconfluent-kafka, into your environment. It is not on PyPI yet. To use only the types, copy thearchr_papinetfolder from the download into your project: it needs nothing outside the standard library. - TypeScript. The toolkit is in the source folder
typescript:npm install,npm run buildandnpm packmakearchr-papinet-1.0.0.tgz, which you install withnpm install ./archr-papinet-1.0.0.tgz. It is not on npm yet. To use only the types, copypapinet-envelope.tsand theV<version>.tsfile from the download into your project, side by side.
The messages every language shares
A request that Archr.Hermod puts on the queue for the papiNet API:
{
"specVersion": "4.0.0",
"operation": "get-supplier-orders-supplierOrderId",
"method": "GET",
"path": "/supplier-orders/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pathParameters": { "supplierOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" },
"query": { "limit": ["10"], "offset": ["0"] },
"caller": { "id": "BAFOR", "keyId": 31, "attributes": { "AppId": "APOLLO-PROD", "BusinessUnit": "PAPER-EU", "PartyId": ["1001"] } },
"correlationId": "0d1c5f0a8b7e4c1c9d3a",
"receivedUtc": "2026-10-23T09:19:29.449Z",
"deadlineUtc": "2026-10-23T09:19:59.449Z",
"body": null
}
caller says who is calling and carries the attributes the administrator set up for that caller (for Apollo: AppId, BusinessUnit, PartyId);
it never carries the caller's key. deadlineUtc is the moment Archr.Hermod stops waiting. The answer your back end publishes:
{ "correlationId": "0d1c5f0a8b7e4c1c9d3a", "status": 200, "headers": { "content-type": "application/json" }, "body": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "number": "ABCD-476408" } }Headers travel with each message, so a consumer can route without reading the body:
| Header | What it is for |
|---|---|
hermod-correlation-id | Copy it from the request to the reply: it is how Archr.Hermod matches an answer to the caller that is waiting for it. |
hermod-reply-to | The topic the reply goes to. A message without it is not a request that expects an answer. |
hermod-reply-id | On Kafka: which request in flight this is. Publish the reply with the same value as a header and as the message key. |
hermod-deadline | The deadline, so it is known before the body is read. |
hermod-operation, hermod-spec-version, hermod-caller-id, hermod-attr-<Name> | The operation, the papiNet version, who is calling, and each caller attribute. |
Topics carry the papiNet version, so versions never mix: papinet.v4-0-0.<operation>.request for what you serve and papinet.v4-0-0.<operation>.response for the replies;
papinet.out.v4-0-0.<operation>.request and ….response for the calls you make to partners. The operation id is the verb and the path with its parameter names:
get-supplier-orders-supplierOrderId.
Rules that hold in every language
- The queue delivers at least once. The same request can arrive twice. A request that changes data must be safe to handle twice; the correlation id is the same on a repeat of the same message.
- There is a deadline. After
deadlineUtcthe caller has been told 504 and an answer is thrown away. Do not do work for a request that is past it. - Only the statuses the papiNet document declares get through (200, 204, 400 and 404 in every bundled version). Anything else becomes 502 for the caller, and Archr.Hermod logs it.
- Order is not guaranteed between requests.
- Optional means optional. A property that was not sent is absent (null), and is left out again when the message is written back. Properties the document does not describe are kept, not dropped.
Next: serving the API from your back end, then calling partners.