REST API

Embedding and hosted pages

A creation session has one page. ui_mode of the session decides how it reaches the person:

	Hosted (`ui_mode: hosted`)	Embedded (`ui_mode: embedded`)
Where	A full eSoppari page in the browser tab	A frame inside a page of your app
What you configure	Nothing	An embed origin
Code in your page	A redirect or a link	`esoppari.js` and one call
After the send	The browser goes to `success_url`	Your `onComplete` callback runs
After Cancel	The browser goes to `cancel_url`	Your `onCancel` callback runs

In both modes, your server opens the session and gives the session url to the browser. In both modes, trust the creation_session.completed webhook on your server, not what the browser tells you.

The placeholders in the examples

Placeholder	What to put there
`sessionUrl`	The `url` of the create answer, which your server passed to this page. It holds the secret of the session after `#`.
`https://create.esoppari.fi`	The page origin of your eSoppari service. The `url` of the session starts with it.
`https://app.example.com`	The origin of your own app. For embedded, it must be one of your embed origins.
`#signing`	An element of your page that holds the frame.

Hosted

Send the browser to url, with a redirect from your server or a link:

<a href="SESSION_URL_FROM_YOUR_SERVER">Review and send</a>

What happens:

The page opens on https://create.esoppari.fi. It takes the secret out of the address bar and keeps it in the browser tab, so a reload of the tab still works. A new tab or another browser cannot open the page.
The person reviews and clicks Send to signers. The browser then goes to success_url, with {SESSION_ID} replaced by the session id.
If the person clicks Cancel, the browser goes to cancel_url.
After a send, a cancel or expires_at, the page shows "This page is no longer open".

A hosted page refuses to be shown in a frame. To show the page inside your app, use embedded.

Embedded

1. Add your embed origin

Add the origin of the page that shows the frame, once: on the API keys page of the admin portal, or with POST /v1/embed-origins (Embed origins). Only that origin can frame the page.

2. Open the session

Open it from your server with "ui_mode": "embedded" and "embed_origin": "https://app.example.com", and pass url to the page of your app.

3. Mount the page

<div id="signing"></div>
<script src="https://create.esoppari.fi/js/v1.0.0/esoppari.js"
  integrity="sha384-AgXtPxel1ibUrCervx55961wJUfNw2uzdhZY2NnfAhaMRpf2AIV/xdFeTE5bhHhd"
  crossorigin="anonymous"></script>
<script>
  var page = ESoppari.mountCreation({
    url: sessionUrl,
    container: '#signing',
    onComplete: function (e) { showSent(e.signingRequestId); },
    onCancel: function (e) { closePanel(); },
    onExpired: function (e) { askYourServerForANewSession(); }
  });
</script>

showSent, closePanel and askYourServerForANewSession stand for code of your own app.

The script

URL	Use it when
`https://create.esoppari.fi/js/v1.0.0/esoppari.js`	Production. A pinned version never changes, so its `integrity` hash always matches it (Versions). Keep `integrity` and `crossorigin="anonymous"`: the browser then refuses a changed file.
`https://create.esoppari.fi/js/v1/esoppari.js`	Tests. It follows the newest v1 release, so it has no fixed hash.

Versions

Each version keeps its URL and its hash for good, so a page that pins one keeps working when a new version comes. To move to a new version, change both the URL and the integrity of your script tag.

Version	Path on `https://create.esoppari.fi`	`integrity`	Changes
`v1.0.0`	`/js/v1.0.0/esoppari.js`	`sha384-AgXtPxel1ibUrCervx55961wJUfNw2uzdhZY2NnfAhaMRpf2AIV/xdFeTE5bhHhd`	The first version: `mountCreation`, `unmount` and every callback of this guide.

Options of `mountCreation`

Option	Type	What it does
`url`	string	Required. The session `url`. It must be an embedded session on the eSoppari origin that served the script; any other URL throws an error.
`container`	element or CSS selector	Required. Where the frame goes. A selector that finds nothing throws an error.
`title`	string	The title of the frame, for screen readers. Default `eSoppari`.
`onReady`	function	The page loaded.
`onDocument`	function	The person uploaded a PDF.
`onValidityChange`	function	Send to signers turned on or off.
`onSending`	function	The person clicked Send to signers, and the send left the page.
`onSendFailed`	function	The send was refused, and the page shows why.
`onComplete`	function	The request was sent.
`onCancel`	function	The session was cancelled.
`onExpired`	function	The session expired, or the page cannot open it.

Every callback is optional. mountCreation returns an object with unmount(), which removes the frame and stops the callbacks.

What each callback gets

Each callback gets one object e. Every e has sessionId. No event carries a name, an email or a filename.

Callback	Fields of `e`
`onReady`	`hasDocument`: the page has a PDF. `valid`: Send to signers is on.
`onDocument`	`pageCount`: the pages of the new PDF.
`onValidityChange`	`valid`: Send to signers is on (`true`) or off (`false`). It is on when the page has a PDF and every signer row has a name and a valid email that no other row has.
`onSending`	Only `sessionId`.
`onSendFailed`	`reason`: `invalid` (a field must change; the page marks it), `document_gone` (the PDF is no longer there), or `error` (a fault or a lost connection; the person can try again).
`onComplete`	`signingRequestId`: the request that the send created.
`onCancel`	`reason`: `person`, `api_key_revoked`, `embed_origin_removed` or `request_erased`, as in Creation sessions.
`onExpired`	Only `sessionId`. Open a new session to try again.

If the host page reloads and mounts the same url after the session ended, the frame says how it ended: onComplete or onCancel again, else onExpired.

The frame

It is as wide as container. It starts 640 pixels high and then follows the height of the page, between 200 and 10000 pixels, so it never scrolls inside.
It needs no cookies, so it works when the browser blocks third-party cookies.
A reload of the frame keeps the session.
It takes no messages from your page: the session sets its document and its signers, and the person changes them on the page.

If your page has a Content Security Policy

Allow the script and the frame from the eSoppari page origin:

Content-Security-Policy: script-src 'self' https://create.esoppari.fi; frame-src https://create.esoppari.fi

Without `esoppari.js`

You can put the session url in an <iframe> yourself and listen to message events. Read only the events whose origin is https://create.esoppari.fi and whose source is your frame. Each data has type, and each type except esoppari:resize also has session_id:

`type`	More fields
`esoppari:ready`	`has_document`, `valid`
`esoppari:resize`	`height`, in pixels: set it on the frame
`esoppari:document`	`page_count`
`esoppari:validity`	`valid`
`esoppari:sending`
`esoppari:send_failed`	`reason`
`esoppari:complete`	`signing_request_id`
`esoppari:cancel`	`reason`
`esoppari:expired`

The frame sends these to your embed origin only.