API contract
The reference contract is an OpenAPI 3.1 file, version 2.1.0: download attachments-openapi.yaml. It can be opened in any OpenAPI editor (Swagger Editor, Postman…). This page summarizes it.
Common rules
- Addresses: the paths below are appended to the base address of the target system's REST API (
APIBASEin the Save2ERP configuration). They are the default paths: each one can be changed in the configuration (see Configuring the server). - Authentication: the user's OAuth2 access token, in
Authorization: Bearer. An additional API key header can be configured if a gateway requires one. - SAP only: the server adds the
sap-clientparameter (client number) to every call. - Every functional error carries a
code(uppercase letters, digits and_, 50 characters at most) and, optionally, amessagealready written in the user's language. - Same file name: the comparison rule (for example case-insensitive) is defined by the target system, and must be the same for the check and the upload.
HTTP status codes
Each status has a single meaning:
| Status | Meaning |
|---|---|
200 / 201 | Check done / document stored. |
400 | Malformed request (missing or invalid field). |
401 | Missing, invalid or expired token. |
403 | The user may not read or modify this object. |
409 | A file with the same name is already attached to the object (upload only). |
422 | The object (or the template) does not exist, or its type is unknown. |
5xx | Technical error of the target system (no detail is shown to the user). |
Never 404 or 405 for a functional error
A 404 or 405 answer without a code on the check means that the service does not exist: Save2ERP then sends the document without checking. On the designer mode services, it means that designer mode is not available. An unknown object therefore answers 422, never 404.
Check before sending
POST /attachments/check: read-only, nothing is stored or changed. It is a POST so that the file name and the object key never appear in URLs, and therefore in logs.
Request:
{
"objectType": "BUS2000126",
"objectKey": "0000012345",
"fileName": "contract.docx"
}200 response:
{
"exists": true,
"allowedActions": ["REPLACE", "NEW_VERSION"],
"existingFile": {
"version": "3",
"modifiedAt": "2026-10-12T14:35:00+02:00",
"modifiedBy": "Marie Dupont"
}
}| Field | Required | Content |
|---|---|---|
exists | Yes | true if a file with this name is already attached to the object. |
allowedActions | Yes | Actions the upload would accept for this object: REPLACE, NEW_VERSION, both, or none (empty list: only another name is possible). Always empty when exists is false. |
existingFile | No | Information on the existing file, shown to the user: version (50 characters at most), modifiedAt (ISO 8601 date with time zone), modifiedBy (person's name, not a technical ID). Each one is optional. |
Sending the document
POST /attachments:
{
"objectType": "BUS2000126",
"objectKey": "0000012345",
"fileName": "contract.docx",
"fileContent": "<document encoded in base64>",
"onNameConflict": "FAIL"
}fileNamealways ends with the extension of the chosen format (.docxor.pdf), andfileContentis a document of that format: the target system deduces the file type from it.- The request is limited to 50 MB by Save2ERP, about 37 MB of document once encoded in base64.
onNameConflict (optional, FAIL by default) tells what to do if a file with the same name exists:
onNameConflict | File does not exist | File exists, action allowed | File exists, action not allowed |
|---|---|---|---|
FAIL | File created | 409 | 409 |
REPLACE | File created | Existing file deleted, new file created | 409 |
NEW_VERSION | File created | New version of the existing file | 409 |
201 response, with an optional message that the pane shows instead of its own:
{ "code": "FILE_STORED", "message": "The file contract.docx has been attached to the object 0000012345." }409 response, with the actions allowed for a new upload (missing or empty: only another name is possible):
{
"code": "FILE_ALREADY_EXISTS",
"message": "A file named contract.docx is already attached to the object 0000012345.",
"allowedActions": ["REPLACE", "NEW_VERSION"]
}Connection test
GET /attachments/healthcheck: used by the administrator's /test page to check the connection, the token and the configuration. The content of the 200 response is free: it is shown as is to the administrator.
{ "RESULT": "OK", "SYSTEM": "D01" }Designer mode (optional)
Designer mode lets the designer of a Word template show the label of each tag instead of the object's values. It relies on two optional services: a target system that does not provide them never offers designer mode.
User permissions
GET /attachments/permissions: called only once, at sign-in. Save2ERP keeps the permissions for the whole session.
{ "templateDesigner": true }Only the value true grants the permission. If the service does not exist, answers with an error or does not answer within 5 seconds, the user has no permission and the sign-in goes on normally.
Template XML
POST /attachments/readTemplateXml: read-only, like the check, and for the same reason: the object ID never appears in URLs, and therefore in logs.
Request:
{
"templateId": "OFFER-2026",
"content": "values",
"objectType": "BUS2000126",
"objectKey": "0000012345"
}| Field | Required | Content |
|---|---|---|
templateId | Yes | ID of the template (S2E_TemplateId property of the document). |
content | Yes | labels: the label of each tag; values: the object's values. |
objectType, objectKey | With values | The document's object (S2E_ObjectType and S2E_ObjectKey properties). Absent with labels. |
200 response: the complete XML of the template's custom part (application/xml), as the system writes it into the document when it generates it. Its root carries the namespace of this part: the pane uses it to find the part in the document.
<?xml version="1.0" encoding="UTF-8"?>
<Document xmlns="urn:example:offer">
<Customer><Company>Customer name</Company><City>City</City></Customer>
<Lines><Line><Description>Service description</Description><Amount>Amount</Amount></Line></Lines>
</Document>- The pane replaces each element under the root with the element of the same name received: an element received that is missing from the document is ignored, an element of the document missing from the XML received is left as it is. A repeating section follows the number of elements received (usually a single one for the labels).
labelsis reserved to template designers: answer403to other users.valuesmust remain allowed to every user who may read the object: a document left with the labels must always be able to get its values back.- An unknown template answers
422, with itscodeandmessage.