Skip to content

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 (APIBASE in 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-client parameter (client number) to every call.
  • Every functional error carries a code (uppercase letters, digits and _, 50 characters at most) and, optionally, a message already 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:

StatusMeaning
200 / 201Check done / document stored.
400Malformed request (missing or invalid field).
401Missing, invalid or expired token.
403The user may not read or modify this object.
409A file with the same name is already attached to the object (upload only).
422The object (or the template) does not exist, or its type is unknown.
5xxTechnical 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:

json
{
  "objectType": "BUS2000126",
  "objectKey": "0000012345",
  "fileName": "contract.docx"
}

200 response:

json
{
  "exists": true,
  "allowedActions": ["REPLACE", "NEW_VERSION"],
  "existingFile": {
    "version": "3",
    "modifiedAt": "2026-10-12T14:35:00+02:00",
    "modifiedBy": "Marie Dupont"
  }
}
FieldRequiredContent
existsYestrue if a file with this name is already attached to the object.
allowedActionsYesActions 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.
existingFileNoInformation 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:

json
{
  "objectType": "BUS2000126",
  "objectKey": "0000012345",
  "fileName": "contract.docx",
  "fileContent": "<document encoded in base64>",
  "onNameConflict": "FAIL"
}
  • fileName always ends with the extension of the chosen format (.docx or .pdf), and fileContent is 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:

onNameConflictFile does not existFile exists, action allowedFile exists, action not allowed
FAILFile created409409
REPLACEFile createdExisting file deleted, new file created409
NEW_VERSIONFile createdNew version of the existing file409

201 response, with an optional message that the pane shows instead of its own:

json
{ "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):

json
{
  "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.

json
{ "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.

json
{ "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:

json
{
  "templateId": "OFFER-2026",
  "content": "values",
  "objectType": "BUS2000126",
  "objectKey": "0000012345"
}
FieldRequiredContent
templateIdYesID of the template (S2E_TemplateId property of the document).
contentYeslabels: the label of each tag; values: the object's values.
objectType, objectKeyWith valuesThe 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
<?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).
  • labels is reserved to template designers: answer 403 to other users.
  • values must 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 its code and message.