Technical Reference

SDK guide 3: Making outbound API calls with trading partners from your business application

Step by step, with code in Java, C#, TypeScript and Python: set up a partner, make a call through the outbound hub, read the outcome, and what happens on the wire.

Show the examples in

This is the second job: your application needs something from a trading partner's papiNet API, a delivery note say. It names the partner and the operation; Archr.Hermod looks the partner up, checks the request, calls the partner with the partner's key, and publishes the answer. Your application holds no address, key or certificate for the partner. Read guide 1 first for the messages.

1. What happens to a call

  1. Your application publishes a request on papinet.out.v4-0-0.<operation>.request. It says what (partner, operation, parameters, body) and never where or how: there is no URL, no HTTP method, no header and no credential in the message.
  2. Archr.Hermod checks, in order: the partner exists and is switched on; the version is live; the operation exists and is permitted for that partner; the partner has an endpoint for its environment; the parameters and the body fit the papiNet document.
  3. It reads the partner's key from its secret store and makes the call. The network rules apply: https only unless the partner allows http, no private addresses unless allowed, no redirects.
  4. It publishes the reply on ….response with an outcome: what happened, in words your application can act on.

2. Set the partner up (an administrator, once)

  1. In the Admin pages, Settings, card papiNet Outbound API Hub: switch the hub on. It is off until someone does: while it is off a request gets no answer, whatever the partners say.
  2. papiNet API, API Partners: add the partner. A new partner is switched off, in the test environment, with no endpoint and nothing permitted. Give it an endpoint for the papiNet version, enter its API key (the key is written once and never shown again), permit the operations it may be asked for (all reads is a rule that also covers operations a later papiNet document adds), then switch it on. The partner's page lists what still stops a call working.
  3. Use the partner's id, as you entered it (BAFOR in the examples), in your application. Start in the test environment; moving a partner to production asks for confirmation.

API-key authentication is available now; OAuth 2 client credentials and mutual TLS are not.

3. Add the SDK

Java

pom.xml
<dependency>
  <groupId>software.archr.papinet</groupId>
  <artifactId>archr-papinet-client</artifactId>
  <version>1.0.0</version>
</dependency>

It brings the contracts and the Kafka client. Java 8 and later. Until the jars are on a public repository, build them with ./mvnw install in the toolkit's source folder.

C#

Reference Hermod.PapiNet.HostAdapter: it holds PapinetClient as well as the adapter, and brings Hermod.PapiNet.Contracts (the classes of every papiNet version) and Confluent.Kafka. .NET Framework 4.6.1 and later, and .NET 8 and later; the notes of guide 2 about the native library on .NET Framework apply.

Python

Install the toolkit as in guide 2: pip install ./python. Client is in archr_papinet, and the version's module (archr_papinet.versions.v4_0_0) gives the operations and the types of their bodies.

TypeScript

Install the toolkit as in guide 2: npm install ./archr-papinet-1.0.0.tgz. PapinetClient is in @archr/papinet, and the version's module (@archr/papinet/V4_0_0) gives the operations and the types of their bodies.

4. Make a call

Java

Make one client for the whole application. It holds a connection and a reader thread, and any number of threads may call through it.

Java
static PapinetClient newClient(PapinetLog log) {
    // One client for the whole application: it holds a connection and a reader thread.
    return PapinetClient.forKafka(kafkaSettings(),
            new PapinetClientOptions().setSender("ERP-PROD").setTimeout(Duration.ofSeconds(20)), log);
}

The Kafka settings are those of the serving guide (KafkaPapinetSettings). A call names the partner and the operation, adds parameters, and execute() publishes it and waits for the reply:

Java
static LogisticsDeliveryNoteById readNote(PapinetClient client, UUID noteId) {
    OutboundCall call = client.call(Operations.GET_LOGISTICS_DELIVERY_NOTES_LOGISTICS_DELIVERY_NOTE_ID, "BAFOR")
            .pathParameter("logisticsDeliveryNoteId", noteId)
            .execute();

    if (call.isSucceeded()) {
        return call.body();                              // the partner's answer as the generated class
    }
    if (CallOutcomes.DELIVERED.equals(call.getOutcome()) && call.getStatus() != null && call.getStatus() == 404) {
        return null;                                     // the partner answered "no such note": a delivered answer, not a failure
    }
    throw new IllegalStateException("Could not read note " + noteId + ": " + call);   // outcome, status and Archr.Hermod's reason
}

A list, with query parameters. A parameter given twice has two values:

Java
static List<String> departedNotes(PapinetClient client) {
    OutboundCall call = client.call(Operations.GET_LOGISTICS_DELIVERY_NOTES, "BAFOR")
            .query("shipmentStatus", "Departed")
            .query("limit", "20")
            .execute();

    List<String> numbers = new ArrayList<String>();
    if (call.hasBody()) {
        ListOfLogisticsDeliveryNotes notes = call.body();
        for (int i = 0; i < notes.getItems().size(); i++) {
            numbers.add(notes.getItems().get(i).getNumber());
        }
    }
    return numbers;                                      // empty for 204 (nothing matches) as well as for a failure: look at the outcome to tell them apart
}

A push. The body is the generated class of the operation's request; the idempotency key goes to the partner, so a repeat can be told from a new document:

Java
static boolean sendReceipt(PapinetClient client, LogisticsGoodsReceiptById receipt) {
    OutboundCall call = client.call(Operations.POST_LOGISTICS_GOODS_RECEIPTS, "BAFOR")
            .body(receipt)
            .idempotencyKey(receipt.getId().toString())   // passed to the partner, so a repeat can be told from a new receipt
            .execute();

    if (call.isSucceeded()) {
        return true;
    }
    if (CallOutcomes.TIMEOUT.equals(call.getOutcome())) {
        return false;                                     // it may have reached the partner: send it again with the same key
    }
    throw new IllegalStateException("The receipt was not delivered: " + call);
}

C#

Make one client for the whole application. It holds a connection and a reader thread, and any number of tasks may call through it.

C#
public static PapinetClient NewClient(IPapinetLog log)
{
    var kafka = new KafkaPapinetSettings
    {
        BootstrapServers = "broker1:9092,broker2:9092",
        SaslUsername = Environment.GetEnvironmentVariable("PAPINET_KAFKA_USER"),
        SaslPassword = Environment.GetEnvironmentVariable("PAPINET_KAFKA_PASSWORD"),
    };

    // One client for the whole application: it holds a connection and a reader thread.
    return PapinetClient.ForKafka(kafka, new PapinetClientOptions { Sender = "APOLLO-PROD", Timeout = TimeSpan.FromSeconds(20) }, log);
}

A call names the partner and the operation, adds parameters, and ExecuteAsync publishes it and waits for the reply. ExecuteAsync<T> reads the answer as the class you name (normally the operation's response class):

C#
public static async Task<LogisticsDeliveryNoteById> ReadNoteAsync(PapinetClient client, Guid noteId, CancellationToken ct)
{
    var call = await client.Call(Operations.GetLogisticsDeliveryNotesLogisticsDeliveryNoteId, "BAFOR")
        .PathParameter("logisticsDeliveryNoteId", noteId)
        .ExecuteAsync<LogisticsDeliveryNoteById>(ct);

    if (call.Succeeded)
        return call.Body;                                   // the partner's answer as the generated class
    if (call.Outcome == CallOutcomes.Delivered && call.Status == 404)
        return null;                                        // the partner answered "no such note": a delivered answer, not a failure
    throw new InvalidOperationException("Could not read note " + noteId + ": " + call);   // outcome, status and Archr.Hermod's reason
}

A list, with query parameters. A parameter given twice has two values:

C#
public static async Task<List<string>> DepartedNotesAsync(PapinetClient client, CancellationToken ct)
{
    var call = await client.Call(Operations.GetLogisticsDeliveryNotes, "BAFOR")
        .Query("shipmentStatus", "Departed")
        .Query("limit", "20")
        .ExecuteAsync<ListOfLogisticsDeliveryNotes>(ct);

    // Empty for 204 (nothing matches) as well as for a failure: look at call.Outcome to tell them apart.
    return call.HasBody ? call.Body.Items.Select(item => item.Number).ToList() : new List<string>();
}

A push. The body is the generated class of the operation's request; the idempotency key goes to the partner, so a repeat can be told from a new document:

C#
public static async Task<bool> SendReceiptAsync(PapinetClient client, LogisticsGoodsReceiptById receipt, CancellationToken ct)
{
    var call = await client.Call(Operations.PostLogisticsGoodsReceipts, "BAFOR")
        .Body(receipt)
        .IdempotencyKey(receipt.Id.ToString())              // passed to the partner, so a repeat can be told from a new receipt
        .ExecuteAsync(ct);

    if (call.Succeeded)
        return true;
    if (call.Outcome == CallOutcomes.Timeout)
        return false;                                       // it may have reached the partner: send it again with the same key
    throw new InvalidOperationException("The receipt was not delivered: " + call);
}

TypeScript

Make one client for the whole application. It holds connections, and any number of calls may be in flight through it. await client.prepare([operations.getLogisticsDeliveryNotes]) at start-up joins the consumer group that reads the answers (a few seconds on a broker with default settings), so that the first call of an operation does not wait for it.

TypeScript
export function newClient(log: PapinetLog): PapinetClient {
    // One client for the whole application: it holds connections. Close it when the application stops.
    return PapinetClient.forKafka(
        { bootstrapServers: "broker1:9092,broker2:9092", saslUsername: process.env.PAPINET_KAFKA_USER, saslPassword: process.env.PAPINET_KAFKA_PASSWORD },
        { sender: "ERP-PROD", timeoutMs: 20000 }, log);
}

A call names the partner and the operation, adds parameters, and execute() publishes it and waits for the reply. The answer is typed by the operation:

TypeScript
export async function readNote(client: PapinetClient, noteId: string): Promise<LogisticsDeliveryNoteById | undefined> {
    const call = await client.call(operations.getLogisticsDeliveryNotesLogisticsDeliveryNoteId, "BAFOR")
        .pathParameter("logisticsDeliveryNoteId", noteId)
        .execute();

    if (call.succeeded) {
        return call.body;                                   // the partner's answer as the generated type
    }
    if (call.outcome === CallOutcomes.delivered && call.status === 404) {
        return undefined;                                   // the partner answered "no such note": a delivered answer, not a failure
    }
    throw new Error(`Could not read note ${noteId}: ${call}`);   // outcome, status and Archr.Hermod's reason
}

A list, with query parameters. A parameter given twice has two values:

TypeScript
export async function departedNotes(client: PapinetClient): Promise<string[]> {
    const call = await client.call(operations.getLogisticsDeliveryNotes, "BAFOR")
        .query("shipmentStatus", "Departed")
        .query("limit", 20)
        .execute();

    const notes: ListOfLogisticsDeliveryNotes | undefined = call.body;
    // Empty for 204 (nothing matches) as well as for a failure: look at call.outcome to tell them apart.
    return notes ? notes.items.map((item) => item.number) : [];
}

A push. The body is the generated type of the operation's request; the idempotency key goes to the partner, so a repeat can be told from a new document:

TypeScript
export async function sendReceipt(client: PapinetClient, receipt: LogisticsGoodsReceiptById): Promise<boolean> {
    const call = await client.call(operations.postLogisticsGoodsReceipts, "BAFOR")
        .body(receipt)
        .idempotencyKey(receipt.id)                          // passed to the partner, so a repeat can be told from a new receipt
        .execute();

    if (call.succeeded) {
        return true;
    }
    if (call.outcome === CallOutcomes.timeout) {
        return false;                                        // it may have reached the partner: send it again with the same key
    }
    throw new Error(`The receipt was not delivered: ${call}`);
}

Python

Make one client for the whole application. It holds connections and a reader thread, and any number of threads may call through it; use it as a context manager or call close() when the application stops. client.prepare([v4.GET_LOGISTICS_DELIVERY_NOTES]) at start-up starts the reader that listens for the answers, so that the first call of an operation does not wait for it.

Python
def new_client() -> Client:
    # One client for the whole application: it holds connections and a reader thread, and any number of threads may call through it. Close it when the application stops.
    return Client.for_kafka(
        KafkaSettings("broker1:9092,broker2:9092", sasl_username=os.environ.get("PAPINET_KAFKA_USER"), sasl_password=os.environ.get("PAPINET_KAFKA_PASSWORD")),
        sender="ERP-PROD", timeout=20)

A call names the partner and the operation, and takes its parameters as keyword arguments: path, query, body, idempotency_key. It blocks until the reply comes:

Python
def read_note(client: Client, note_id: uuid.UUID) -> t.Optional[v4.LogisticsDeliveryNoteById]:
    call = client.call(v4.GET_LOGISTICS_DELIVERY_NOTES_LOGISTICS_DELIVERY_NOTE_ID, "BAFOR", path={"logisticsDeliveryNoteId": note_id})

    if call.succeeded:
        return call.body                                       # the partner's answer, a dict typed by the operation
    if call.outcome == Outcomes.DELIVERED and call.status == 404:
        return None                                            # the partner answered "no such note": a delivered answer, not a failure
    raise RuntimeError(f"Could not read note {note_id}: {call}")   # outcome, status and Archr.Hermod's reason

A list, with query parameters. A list value is a parameter given twice; a None value is left out:

Python
def departed_notes(client: Client) -> t.List[str]:
    call = client.call(v4.GET_LOGISTICS_DELIVERY_NOTES, "BAFOR", query={"shipmentStatus": "Departed", "limit": 20})

    notes = call.body
    # Empty for 204 (nothing matches) as well as for a failure: look at call.outcome to tell them apart.
    return [item["number"] for item in notes["items"]] if notes else []

A push. The body is a dict typed by the operation's request; the idempotency key goes to the partner, so a repeat can be told from a new document:

Python
def send_receipt(client: Client, receipt: v4.LogisticsGoodsReceiptById) -> bool:
    call = client.call(v4.POST_LOGISTICS_GOODS_RECEIPTS, "BAFOR", body=receipt,
                       idempotency_key=receipt["id"])          # passed to the partner, so a repeat can be told from a new receipt

    if call.succeeded:
        return True
    if call.outcome == Outcomes.TIMEOUT:
        return False                                           # it may have reached the partner: send it again with the same key
    call.raise_for_status()                                    # anything else: raises PapinetCallError, with the outcome, the status and Archr.Hermod's reason
    return False

5. Read the outcome

Nothing is thrown for a call that did not work: its outcome says what happened, so a page or a job can show it.

OutcomeIt meansYour application should
deliveredThe partner answered. The status and the body are its. A partner's 4xx is still delivered.Use the answer; look at the status.
refusedArchr.Hermod did not call: unknown or switched-off partner, operation not permitted, no endpoint, or the request does not fit papiNet.Fix the request or ask the administrator. Retrying is pointless.
unavailableThe partner could not be reached, or Archr.Hermod may not reach it. Nothing was delivered.Try later.
timeoutNo answer in time. The call may have reached the partner.For a push, send it again with the same idempotency key.
failedA problem on Archr.Hermod's side (a key it cannot read, an internal error). The administrator is told.Alert; do not retry in a loop.
no-replyNothing came back from Archr.Hermod in time: the outbound hub is switched off, or Archr.Hermod is not running or not using this queue.Check the hub's switch and that Archr.Hermod is up.
queue-error, bad-replyThis application could not use the queue, or something came back that is not a reply of the hub.Check the Kafka settings and permissions.

Java

Java
static void explain(OutboundCall call) {
    switch (call.getOutcome()) {
        case CallOutcomes.DELIVERED:
            // The partner answered. call.getStatus() and call.getRawBody() are its; a 4xx is still "delivered".
            break;
        case CallOutcomes.REFUSED:
            // Archr.Hermod did not call: unknown or switched-off partner, operation not permitted, no endpoint, or the request does not fit papiNet. Retrying is pointless; call.getError() says why.
            break;
        case CallOutcomes.UNAVAILABLE:
            // Archr.Hermod could not reach the partner. Nothing was delivered: try later.
            break;
        case CallOutcomes.TIMEOUT:
            // No answer in time. The call may have reached the partner.
            break;
        case CallOutcomes.FAILED:
            // A problem on Archr.Hermod's side (a key it cannot read, an internal error). The administrator is told.
            break;
        case CallOutcomes.NO_REPLY:
            // Nothing came back from Archr.Hermod: the outbound hub is switched off, or Archr.Hermod's Api is not running or not using this queue.
            break;
        case CallOutcomes.QUEUE_ERROR:
            // This application could not use the message queue (not reachable, not allowed).
            break;
        default:
            // BAD_REPLY: something came back that is not a reply of the outbound hub.
            break;
    }
}

C#

C#
public static void Explain<T>(OutboundCall<T> call)
{
    switch (call.Outcome)
    {
        case CallOutcomes.Delivered:
            // The partner answered. call.Status and call.RawBody are its; a 4xx is still "delivered".
            break;
        case CallOutcomes.Refused:
            // Archr.Hermod did not call: unknown or switched-off partner, operation not permitted, no endpoint, or the request does not fit papiNet. Retrying is pointless; call.Error says why.
            break;
        case CallOutcomes.Unavailable:
            // Archr.Hermod could not reach the partner. Nothing was delivered: try later.
            break;
        case CallOutcomes.Timeout:
            // No answer in time. The call may have reached the partner.
            break;
        case CallOutcomes.Failed:
            // A problem on Archr.Hermod's side (a key it cannot read, an internal error). The administrator is told.
            break;
        case CallOutcomes.NoReply:
            // Nothing came back from Archr.Hermod: the outbound hub is switched off, or Archr.Hermod's Api is not running or not using this queue.
            break;
        case CallOutcomes.QueueError:
            // This application could not use the message queue (not reachable, not allowed).
            break;
        default:
            // CallOutcomes.BadReply: something came back that is not a reply of the outbound hub.
            break;
    }
}

call.Succeeded is true for delivered with a 2xx status; call.Status, call.RawBody and call.Error say the rest.

TypeScript

TypeScript
export function explain(call: OutboundCall<unknown>): void {
    switch (call.outcome) {
        case CallOutcomes.delivered:
            // The partner answered. call.status and call.rawBody are its; a 4xx is still "delivered".
            break;
        case CallOutcomes.refused:
            // Archr.Hermod did not call: unknown or switched-off partner, operation not permitted, no endpoint, or the request does not fit papiNet. Retrying is pointless; call.error says why.
            break;
        case CallOutcomes.unavailable:
            // Archr.Hermod could not reach the partner. Nothing was delivered: try later.
            break;
        case CallOutcomes.timeout:
            // No answer in time. The call may have reached the partner.
            break;
        case CallOutcomes.failed:
            // A problem on Archr.Hermod's side (a key it cannot read, an internal error). The administrator is told.
            break;
        case CallOutcomes.noReply:
            // Nothing came back from Archr.Hermod: the outbound hub is switched off, or Archr.Hermod's Api is not running or not using this queue.
            break;
        case CallOutcomes.queueError:
            // This application could not use the message queue (not reachable, not allowed).
            break;
        default:
            // CallOutcomes.badReply: something came back that is not a reply of the outbound hub.
            break;
    }
}

call.succeeded is true for delivered with a 2xx status; call.status, call.rawBody and call.error say the rest.

Python

Python
def explain(call: OutboundCall[t.Any]) -> None:
    if call.outcome == Outcomes.DELIVERED:
        pass    # The partner answered. call.status and call.raw_body are its; a 4xx is still "delivered".
    elif call.outcome == Outcomes.REFUSED:
        pass    # Archr.Hermod did not call: unknown or switched-off partner, operation not permitted, no endpoint, or the request does not fit papiNet. Retrying is pointless; call.error says why.
    elif call.outcome == Outcomes.UNAVAILABLE:
        pass    # Archr.Hermod could not reach the partner. Nothing was delivered: try later.
    elif call.outcome == Outcomes.TIMEOUT:
        pass    # No answer in time. The call may have reached the partner.
    elif call.outcome == Outcomes.FAILED:
        pass    # A problem on Archr.Hermod's side (a key it cannot read, an internal error). The administrator is told.
    elif call.outcome == Outcomes.NO_REPLY:
        pass    # Nothing came back from Archr.Hermod: the outbound hub is switched off, or Archr.Hermod's Api is not running or not using this queue.
    elif call.outcome == Outcomes.QUEUE_ERROR:
        pass    # This application could not use the message queue (not reachable, not allowed).
    else:
        pass    # Outcomes.BAD_REPLY: something came back that is not a reply of the outbound hub.

call.succeeded is true for delivered with a 2xx status; call.status, call.raw_body and call.error say the rest. call.raise_for_status() raises PapinetCallError unless the call succeeded, if you prefer exceptions.

6. Timeouts, repeats and what Archr.Hermod does not do for you yet

Java

Java
static JsonNode rawAnswer(OutboundCall call) {
    // The answer as the JSON it arrived as, whatever the operation says: for a partner that is not quite conformant, or to pass it on unchanged.
    JsonNode raw = call.getRawBody();
    if (raw != null && call.getBodyProblem() != null) {
        System.err.println("The partner's answer does not match papiNet: " + call.getBodyProblem());
    }
    return raw == null ? PapinetJson.mapper().createObjectNode() : raw;
}

7. The wire protocol, for any language

Everything above is these steps. A request message:

JSON: a call to a partner
{
  "specVersion": "4.0.0",
  "operation": "get-logistics-delivery-notes-logisticsDeliveryNoteId",
  "partner": "BAFOR",
  "pathParameters": { "logisticsDeliveryNoteId": "fc190dd0-d239-40db-8196-ea72ae5b4841" },
  "query": {},
  "correlationId": "0d1c5f0a8b7e4c1c9d3a",
  "sender": "ERP-PROD",
  "deadlineUtc": "2026-10-23T09:19:49.449Z"
}
  1. Create the topics papinet.out.v4-0-0.<operation>.request and ….response if they do not exist (the clients do).
  2. Start a consumer on the response topic that begins at the end of it, and wait until it is ready, so that no answer can arrive before you listen. No consumer group that outlives your process is needed.
  3. Publish the request with the message key set to a unique reply id and the headers hermod-reply-to (the response topic), hermod-reply-id (the reply id) and hermod-correlation-id (the request's correlationId).
  4. Read replies from the response topic and pick the one whose hermod-reply-id header is yours. Ignore the others: they belong to other callers. If none comes by the deadline plus a few seconds, treat it as no reply.

The reply:

JSON: the outcome
{
  "correlationId": "0d1c5f0a8b7e4c1c9d3a",
  "status": 200,
  "outcome": "delivered",
  "partner": "BAFOR",
  "attempts": 1,
  "durationMs": 412,
  "headers": { "content-type": "application/json" },
  "body": { "id": "fc190dd0-d239-40db-8196-ea72ae5b4841", "number": "LDN12345" }
}

If you build and read these messages yourself, the message types do the JSON; the publishing and the waiting are the steps above, which the client classes do for you:

C#

C#
public static byte[] BuildAnOutboundRequest(Guid noteId, out string requestTopic, out string responseTopic)
{
    var request = new PapinetOutRequest<JToken>
    {
        SpecVersion = "4.0.0",
        Operation = "get-logistics-delivery-notes-logisticsDeliveryNoteId",
        Partner = "BAFOR",
        CorrelationId = Guid.NewGuid().ToString("N"),
        Sender = "APOLLO-PROD",
        DeadlineUtc = DateTimeOffset.UtcNow.AddSeconds(20),
    };
    request.PathParameters["logisticsDeliveryNoteId"] = noteId.ToString();

    requestTopic = PapinetOutNames.RequestTopic(request.SpecVersion, request.Operation);     // papinet.out.v4-0-0.get-logistics-delivery-notes-logisticsDeliveryNoteId.request
    responseTopic = PapinetOutNames.ResponseTopic(request.SpecVersion, request.Operation);   // ...and its .response: the topic to ask for the answer on
    return request.ToBytes();
}

public static LogisticsDeliveryNoteById ReadTheOutboundReply(byte[] replyBytes)
{
    var reply = PapinetOutReply<JToken>.Read(replyBytes);

    if (reply.Succeeded)
        return (LogisticsDeliveryNoteById)PapinetJson.ReadBody(typeof(LogisticsDeliveryNoteById), reply.Body);

    switch (reply.Outcome)
    {
        case PapinetOutOutcomes.Delivered:     // the partner answered with a status that is not 2xx: reply.Status and reply.Body are its
            return null;
        case PapinetOutOutcomes.Refused:       // Archr.Hermod did not call: reply.Error says why; retrying is pointless
        case PapinetOutOutcomes.Unavailable:   // the partner could not be reached; nothing was delivered
        case PapinetOutOutcomes.Timeout:       // no answer in time; the call may have reached the partner
        default:                               // Failed: a problem on Archr.Hermod's side
            throw new InvalidOperationException("The call did not work: " + reply.Outcome + " " + reply.Error);
    }
}

TypeScript

TypeScript
/** What the client does for you, if you would rather publish the request yourself: build the message, publish it on the request topic, and read the reply from the response topic. */
export function buildAnOutboundRequest(noteId: string): { topic: string; payload: Uint8Array } {
    const operation = operations.getLogisticsDeliveryNotesLogisticsDeliveryNoteId;
    const payload = serializePapinetOutRequest({
        specVersion: operation.specVersion,
        operation: operation.id,
        partner: "BAFOR",
        pathParameters: { logisticsDeliveryNoteId: noteId },
        correlationId: "a-unique-id",
        sender: "ERP-PROD",
        deadlineUtc: new Date(Date.now() + 20000).toISOString(),
    });
    // Publish it on operation.outboundRequestTopic (papinet.out.v4-0-0.get-logistics-delivery-notes-logisticsDeliveryNoteId.request) with the headers
    // hermod-reply-to: operation.outboundResponseTopic, and hermod-reply-id: a unique id (also the message key). The answer is the message on ...response with that reply id.
    return { topic: papinetOutRequestTopic(operation.specVersion, operation.id), payload };
}

export function readTheOutboundReply(replyBytes: Uint8Array): LogisticsDeliveryNoteById | undefined {
    const reply: PapinetOutReply<LogisticsDeliveryNoteById> = parsePapinetOutReply(replyBytes);

    if (reply.outcome === "delivered" && reply.status !== undefined && reply.status >= 200 && reply.status < 300) {
        return reply.body ?? undefined;
    }
    if (reply.outcome === "delivered") {
        return undefined;                                    // the partner answered with a status that is not 2xx: reply.status and reply.body are its
    }
    throw new Error(`The call did not work: ${reply.outcome} ${reply.error}`);   // refused, unavailable, timeout or failed
}

Python

Python
def build_an_outbound_request(note_id: uuid.UUID) -> t.Tuple[str, bytes]:
    """What the client does for you, if you would rather publish the request yourself: build the message, publish it on the request topic, and read the reply from the response topic."""
    operation = v4.GET_LOGISTICS_DELIVERY_NOTES_LOGISTICS_DELIVERY_NOTE_ID
    payload = serialize_out_request({
        "specVersion": operation.spec_version,
        "operation": operation.id,
        "partner": "BAFOR",
        "pathParameters": {"logisticsDeliveryNoteId": str(note_id)},
        "correlationId": uuid.uuid4().hex,
        "sender": "ERP-PROD",
        "deadlineUtc": "2026-10-23T09:19:49.449Z",             # now plus how long you will wait
    })
    # Publish it on operation.out_request_topic (papinet.out.v4-0-0.get-logistics-delivery-notes-logisticsDeliveryNoteId.request) with the headers
    # hermod-reply-to: operation.out_response_topic, and hermod-reply-id: a unique id (also the message key). The answer is the message on ...response with that reply id.
    return operation.out_request_topic, payload


def read_the_outbound_reply(reply_bytes: bytes) -> t.Optional[v4.LogisticsDeliveryNoteById]:
    reply: PapinetOutReply = parse_out_reply(reply_bytes)

    status = reply.get("status", 0)
    if reply["outcome"] == "delivered" and 200 <= status < 300:
        return t.cast("t.Optional[v4.LogisticsDeliveryNoteById]", reply.get("body"))
    if reply["outcome"] == "delivered":
        return None                                            # the partner answered with a status that is not 2xx: reply["status"] and reply["body"] are its
    raise RuntimeError(f"The call did not work: {reply['outcome']} {reply.get('error')}")   # refused, unavailable, timeout or failed

status is the partner's HTTP status when there was one; outcome is one of the five in step 5; error says why a call was refused or failed, in words that never contain a key, a stack trace or an internal address.

8. Try it without writing code

The papiNet Client, a small web application included with Archr.Hermod, makes these calls and shows the answers as forms: a delivery note with its parties, legs, line items and packages. In the Admin pages, Request History, Outbound lists every call that was made, with the partner, the application that asked, the outcome, the partner's status and the reason.

When a call does not work

You seeLook at
No answer at all (no-reply)Is the outbound hub switched on (Settings)? Is Archr.Hermod running and using the same Kafka cluster? May your application publish to papinet.out.*.request and read ….response?
refused and an error textThe partner's page in API Partners: is it switched on, in the right environment, with an endpoint for this papiNet version and the operation permitted? The error text names which.
unavailableThe partner's endpoint address and whether its server is up; whether the network rules (https, private addresses) refuse it.
delivered with 401 or 403The partner rejected the key: set it again on the partner's page.
delivered but no typed bodyThe partner's answer does not match the papiNet description of the operation (C# and Java say why in BodyProblem). Read the raw JSON.

← Back to the technical reference