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
- Where to send. The partner's complete receiving address, and the address they must send to: your gateway's
/api/sfrm/message/inbound. - The partnership name that both sides use, which every segment carries.
- Security. Whether segments are signed and encrypted, with which algorithms, and the certificates to be exchanged.
- How the file is described. Archr.Hermod sends the file name and the total size with every segment, as headers, and not in a separate handshake segment. Check that your partner's receiver does not wait for one.
How a file travels
Sending.
- 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.
- 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.
- 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-SizeandSFRM-MD5. When the partnership signs or encrypts, the segment is a CMS message (content typeapplication/pkcs7-mime) andSFRM-SignedorSFRM-Encryptedsays so. - 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.
- When the receiver has the whole file it sends back an acknowledgement segment, and the message becomes acknowledged.
Receiving.
- The partner posts each segment to
/api/sfrm/message/inbound. - 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.
- 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.
- 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.
- 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.
| Setting | What it does |
|---|---|
| Partnership ID, Description | Your name for the partnership, and a note. The ID is what you give the API when you send. |
| Partner Endpoint | The 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 ID | The partner, chosen from Partner Management > Remote Partners. |
| Sign Algorithm | Sign 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 Algorithm | Encrypt each segment for the partner's certificate: AES128, AES192, AES256 or DES3. Encryption needs the partner's certificate. |
| Partner Certificate Fingerprint | Identifies the partner's certificate, which is looked up under the fingerprint (hex, lower case) in the server's partner certificate folder. |
| Retry Max, Retry Interval | How 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 Hostname | Check 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 Key | Optional. 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. |
| Disabled | Switch 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:
{
"partnershipId": "acme-sfrm",
"payload": "T1JERVJTK0RBVEEgMTAwMQ==",
"filename": "orders-2026-11-17.dat",
"headers": { "ErpReference": "BATCH-77" }
}{ "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.
| Code | A message you sent | A message you received |
|---|---|---|
| PS | Waiting to be sent, or sent and waiting for an acknowledgement that comes later. | Received. |
| PR | Being sent. | Still arriving (a transfer in segments). |
| HD | On hold: a certificate it needs has lapsed. It is accepted, but not yet built or sent. | |
| DL | Delivered to the partner's endpoint. | Received. |
| AG | Acknowledged by the partner. | Received, and the gateway's own acknowledgement was sent. |
| PE, DF | Failed 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
- A segment keeps being refused. The partner's answer is kept with the failure. A checksum mismatch means the segment was changed on the way: check what sits between the two servers.
- Segments are sent but the file is never acknowledged. The partner may not have all of the segments, or may not be able to send its acknowledgement back to
/api/sfrm/message/inbound. - The transfer failed with a reason about signing. A partnership that signs never sends an unsigned segment. If your signing certificate is not configured on the server, cannot be loaded, has lapsed, or the signing itself fails, the segment is not sent, the transfer fails with the reason, and the reason is logged as an error. Put the certificate right and use Retry.
- Encryption did not happen. An encrypt algorithm needs the partner's certificate. If it is missing, or encrypting fails, the gateway logs it and the segment is sent without encryption. Check the log, and that the settings above are in place, before you rely on a partnership to be encrypted.
- A message is refused or held because a certificate has lapsed. Renew it (see Security & Certificate Management).
The same pattern, with its own settings, is used for ebMS and AS2.