Technical Reference

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

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 messages every language shares

A request that Archr.Hermod puts on the queue for the papiNet API:

JSON: a request
{
  "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:

JSON: the reply
{ "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:

HeaderWhat it is for
hermod-correlation-idCopy 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-toThe topic the reply goes to. A message without it is not a request that expects an answer.
hermod-reply-idOn Kafka: which request in flight this is. Publish the reply with the same value as a header and as the message key.
hermod-deadlineThe 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

Next: serving the API from your back end, then calling partners.

← Back to the technical reference