Skip to content

Overview ​

This part is for the team that prepares the target system (the ERP, for example SAP) so that it accepts the documents sent by Save2ERP.

Save2ERP does not depend on a particular ERP: it calls REST services described by a common contract, which each target system implements in its own way. Today, Save2ERP can connect to SAP systems (see Target system: SAP).

What the target system must provide ​

ItemPurpose
An OAuth2 server and a client registered for Save2ERPUser sign-in, with the user's own permissions ("authorization code" flow with PKCE).
The check service (POST /attachments/check)Tells, before sending, whether a file with the same name is already attached to the object, and which actions are allowed.
The upload service (POST /attachments)Stores the document as an attachment of the object.
The test service (GET /attachments/healthcheck)Lets the administrator check the connection from the /test page.
Prepared Word documentsEach generated document carries the S2E_… properties that identify the system and the object (see Preparing Word documents).

The full contract is described in API contract.

How a document is sent ​

  1. The target system generates a Word document, with the S2E_SystemKey, S2E_ObjectType, S2E_ObjectKey and, optionally, S2E_FileName properties.
  2. The user opens it in Word and clicks the save button in the pane.
  3. The Save2ERP server calls POST /attachments/check with the object and the file name, while Word reads the document.
  4. If the file does not exist, the server calls POST /attachments with onNameConflict: FAIL.
  5. If it exists, the pane offers the allowed actions (allowedActions), or applies the option chosen by the user if it is allowed. The document is then sent with onNameConflict set to the chosen action.
  6. The target system answers 201, with or without a message. If it provides a message, the pane shows it as is.

What the Save2ERP server does ​

  • It obtains and renews the user's OAuth2 token, and sends it in the Authorization: Bearer header of each call.
  • It forwards request and response bodies as is: the target system validates the fields and their values.
  • It never shows the technical details of a 5xx error to the user: it writes them to its logs.
  • It shows the message of a functional error (4xx) as is: write it in the user's language.