Technical Reference

SFRM guide: sending and receiving large files in segments

How a file is split into segments, checked and put back together, what each setting of an SFRM partnership does, how to send and receive, and how a transfer is acknowledged and retried.

SFRM moves a large file by cutting it into segments. Each segment is posted on its own over HTTP or HTTPS with a checksum, so that one that fails can be sent again without starting the whole file over. The receiver checks each segment, puts the file back together, and sends an acknowledgement when it has all of them. Segments can be signed and encrypted. For what SFRM is, see the short overview.

Agree these with your partner first

How a file travels

Sending.

  1. Your system sends the file to the gateway's API, or puts it on a message-queue topic. The gateway answers at once with the message's ID.
  2. The gateway cuts the file into segments of the configured size (1 MB unless changed), works out an MD5 checksum of each one, and stores them.
  3. A background sender posts each segment on its own to the partner's address. Every request carries the headers SFRM-Message-ID, SFRM-Partnership-ID, SFRM-Segment-No, SFRM-Segment-Type, SFRM-Total-Segment, SFRM-Filename, SFRM-Total-Size and SFRM-MD5. When the partnership signs or encrypts, the segment is a CMS message (content type application/pkcs7-mime) and SFRM-Signed or SFRM-Encrypted says so.
  4. A segment the partner accepts is delivered. One that is refused, or does not get through, is sent again after the retry interval, up to the partnership's Retry Max. Each segment is retried on its own, and a segment that runs out of retries fails the message.
  5. When the receiver has the whole file it sends back an acknowledgement segment, and the message becomes acknowledged.

Receiving.

  1. The partner posts each segment to /api/sfrm/message/inbound.
  2. The gateway checks the segment against its MD5 and refuses a segment that does not match (with a 400, "MD5 checksum mismatch"), so that the sender sends it again. A segment it already holds is not stored twice.
  3. It stores the segment, and while a file is arriving the message shows as still arriving. When every segment is there the file is complete.
  4. A background worker then sends an acknowledgement segment back to the partner. If that fails it is tried again, and the gateway gives up when the retries are used up.
  5. Your system reads the file from the API or the Messages page, or the gateway publishes it to a message-queue topic.

Set up a partnership

In the Admin UI choose Partnership > SFRM and add a partnership.

SettingWhat it does
Partnership ID, DescriptionYour name for the partnership, and a note. The ID is what you give the API when you send.
Partner EndpointThe partner's complete receiving address. It is used exactly as it is entered, and no path is added. To try the gateway against itself, use its own address followed by /api/sfrm/message/inbound.
Remote Partner IDThe partner, chosen from Partner Management > Remote Partners.
Sign AlgorithmSign each segment (CMS / PKCS#7) with this digest: SHA1, SHA256, SHA384, SHA512 or MD5. Signing needs your signing certificate to be set up on the server (see below). Without it, the transfer fails: a segment that is to be signed is never sent unsigned.
Encrypt AlgorithmEncrypt each segment for the partner's certificate: AES128, AES192, AES256 or DES3. Encryption needs the partner's certificate.
Partner Certificate FingerprintIdentifies the partner's certificate, which is looked up under the fingerprint (hex, lower case) in the server's partner certificate folder.
Retry Max, Retry IntervalHow many times a segment is sent again, and how long apart. The interval is in milliseconds here (30,000 unless changed), where ebMS and AS2 use seconds.
Verify HostnameCheck the partner's server certificate against its host name. Switch it off only for a partner that you have chosen to trust without it.
Tags (message queue topic)Optional. A topic name used as it is written. With IN among the tags, every file received through this partnership is published to the topic. Without it, a message that arrives on the topic is sent through this partnership.
Acknowledgement Topic, Acknowledgement Reference KeyOptional. A topic on which an event is published when the partner's acknowledgement segment arrives, and the name of the header, in your send request, whose value is carried back on that event.
DisabledSwitch the partnership off without deleting it.

Some settings belong to the server and are set by whoever runs the gateway, in the Hermod:SFRM section of its configuration: the segment size (1 MB by default), the folder where the files are staged, how often the background workers look for work (30 seconds), the default number of retries (3), the signing certificate, and the folder of partner certificates.

When it is saved, use the Test button on the partnership: choose a file, and the gateway sends it through the partnership and shows the result.

Send a file

Call the API with your API key (created under Programmability > API Keys) in the X-Api-Key header, as in the ebMS guide, but to /api/sfrm/message/send. The file is base64, and the file name is carried to the partner:

JSON (send.json)
{
  "partnershipId": "acme-sfrm",
  "payload": "T1JERVJTK0RBVEEgMTAwMQ==",
  "filename": "orders-2026-11-17.dat",
  "headers": { "ErpReference": "BATCH-77" }
}
JSON
{ "id": "20261117-093012-0001@gateway" }

Follow a transfer

GET /api/sfrm/message/status?id=<id> returns the state of a message with its number of segments and its size, and the Admin UI's Messages > SFRM page lists them, with a detail view and downloads.

CodeA message you sentA message you received
PSWaiting to be sent, or sent and waiting for an acknowledgement that comes later.Received.
PRBeing sent.Still arriving (a transfer in segments).
HDOn hold: a certificate it needs has lapsed. It is accepted, but not yet built or sent. 
DLDelivered to the partner's endpoint.Received.
AGAcknowledged by the partner.Received, and the gateway's own acknowledgement was sent.
PE, DFFailed for good: the retries ran out, or the partner rejected it. The reason is kept with the message.Received, but the gateway could not deliver its acknowledgement.

For SFRM, the codes mean this for a file you send: it is PS while it waits, and again once every segment has been delivered, when it waits for the receiver's acknowledgement; PR while segments are being sent; AG when the acknowledgement arrives; DF when a segment ran out of retries or could not be signed. DL is the state of an individual segment that the partner has accepted.

A failed transfer can be put back in the send queue with Retry on the Messages page, once the cause has been put right.

When something goes wrong

The same pattern, with its own settings, is used for ebMS and AS2.

← Back to the technical reference