# eversign Python SDK #

eversign Python SDK is the official Python Wrapper around the eversign [API](https://eversign.com/api/documentation).

**Quick Links:**
  - [Create Document Example](/examples/create_document.py)
  - [Use Template Example](/examples/create_document_from_template.py)
  - [Document Operations](/examples/document_operations.py)
  - [Create Iframe Signature](/examples/iframe.py)
  - [Create Iframe Signature From Template](/examples/iframe_template.py)
  - [OAuth Flow (start)](/examples/oauth.py)
  - [OAuth Flow (callback)](/examples/oauth_token.py)


## Installation

Install from npm:
````sh
pip install eversign
````

Install from code:
````sh
pip install git+https://github.com/eversign/eversign-python-sdk.git
````

## Usage

All eversign API requests are made using the `Client` class, which contains all methods for creating, retrieving and saving documents. This class must be initialized with your API access key string. [Where is my API access key?](https://eversign.com/api/documentation/intro#api-access-key)

Please also specify the ID of the eversign business you would like this API request to affect. [Where is my Business ID?](https://eversign.com/api/documentation/intro#business-selection)

In your Python application, import `eversign` and pass authentication information to initialize it:

````python
import eversign
client = eversign.Client('ACCESS_KEY')
````

The client will automatically pick up the primary business to use.

### Fetch businesses
Using the `get_businesses()` function all businesses on the eversign account will be fetched and listed along with their Business IDs.

````python
businesses = client.get_businesses()
print(businesses[0].business_id)
client.set_selected_business(businesses[1])
````

If you know the `businessId` beforehand you can also set it with `set_selected_business_by_id(business_id)`

```
client.set_selected_business_by_id(1337)
```

### Create document from template [Method: Use Template]
To create a document based on an already created template you can use the class `Template` (they are identical). In order to identify which template should be used, please set the template's ID `template_id = 'MY_TEMPLATE_ID'`.

````python
template = eversign.Template()
template.template_id = 'MY_TEMPLATE_ID'
template.title = 'Tile goes here'
template.message = 'test message'
````

#### Fill signing roles [Method: Use Template]
A template's signing and CC roles are filled just using the functions below. Each role is identified using the `role` field, must carry a name and email address and is appended to the document using the `add_signer()` function.

````python
signer = eversign.Signer()
signer.role = 'Testrole'
signer.name = 'John Doe'
signer.email = 'john.doe@eversign.com'

template.add_signer(signer)
````

#### Saving the document object [Method: Use Template]
Your document object can now be saved using the `create_document_from_template()` function. Once this function has been called successfully, your document is created and the signing process is started.

````python
document = client.create_document_from_template(template)
print(document.document_hash)
````

### Creating a document [Method: Create Document]
A document is created by instantiating the `Document` object and setting your preferred document properties. All available methods can be found inside our extensive [Create Document Example](/examples/create_document.js).

````python
document = eversign.Document()
document.template_id = 'MY_TEMPLATE_ID'
document.title = 'Tile goes here'
document.message = 'test message'
````

#### Adding signers to a document [Method: Create Document]
Signers are added to an existing document object by instantiating the `Signer` object and appending each signer to the document object. Each signer object needs to come with a Signer ID, which is later used to assign fields to the respective signer. If no Signer ID is specified, the `add_signer()` method will set a default incremented Signer ID. Each signer object also must contain a name and email address and is appended to the document using the `add_signer()` method.

````python
signer = eversign.Signer()
signer.id = '1'
signer.role = 'Testrole'
signer.name = 'John Doe'
signer.email = 'john.doe@eversign.com'

document.add_signer(signer)
````

#### Adding recipients (CCs) to a document [Method: Create Document]
Recipients (CCs) are added by instantiating the `Recipient` object and appending each recipient to the document object. Just like signers, recipients must carry a name and email address.

````python
recipient = eversign.Recipient()
recipient.role = 'Testrole'
recipient.name = 'John Doe'
recipient.email = 'john.doe@eversign.com'

document.add_recipient(recipient)
````

#### Adding files to the Document [Method: Create Document]
Files are added to a document by instantiating an `File` object. The standard way of choosing a file to upload is appending the file's path using the `file_url` field and then appending your file using the `add_file()` method.

````python
file = eversign.File()
file.file_name = 'Test'
file.file_url = 'test.pdf'

document.add_file(file)
````

#### Adding fields [Method: Create Document]
There is a number of fields that can be added to a document, each coming with different options and parameters. ([Full list of fields ยป](https://eversign.com/api/documentation/fields))

A field is appended to the document using the `add_field(field)` method.

Signature and Initials fields are required to be assigned to a specific signer. Fields are assigned to a signer by setting the **Signer ID** `signer` field.

````python
field = eversign.SignatureField()

field.identifier = 'Test Signature'
field.x = '120.43811219947'
field.y = '479.02760463045'
field.page = 1
field.signer = 5
field.width = 120
field.height = 35
field.required = 1

document.add_field(field)
````

#### Saving a document [Method: Create Document]
A document is saved and sent out by passing the final document object into the `create_document` method. The API will return the entire document object array in response.

```python
saved_document = client.create_document(document)
```

#### Loading a document

A document is loaded by passing a document hash `get_document_by_hash(document_hash='MY_HASH')`.

```python
document = client.get_document_by_hash(document_hash='MY_HASH')
```

#### Downloading the raw or final document
A document can be downloaded either in its raw or in its final (completed) state. In both cases, the respective method must contain the document object and a path to save the PDF document to. When downloading a final document, you can choose to attach the document's Audit Trail by setting the third parameter to `1`.

```python
client.download_final_document_to_path(document, 'final.pdf', audit_trail=0)
client.download_raw_document_to_path(document, 'raw.pdf')
```

#### Get a list of documents or templates
The Client class is also capable fo listing all available documents templates based on their status. Each method below returns an array of document objects.

```python
client.get_all_documents()
client.get_completed_documents()
client.get_draft_documents()
client.get_canceled_documents()
client.get_action_required_documents()
client.get_waiting_for_others_documents()

client.get_templates()
client.get_archived_templates()
client.get_draft_templates()
```

#### Delete or cancel a document
A document is cancelled or deleted using the methods below.

```python
client.delete_document(document);
client.cancel_document(document);
```


### Contact us
Any feedback? Please feel free to [contact our support team](https://eversign.com/contact).

### Development
```
docker run -ti --rm -p 8000:8000 -v $(pwd):/opt/sdk -w /opt/sdk python:3 bash
pip install -r requirements.txt
PYTHONPATH=$(pwd) python examples/create_document.py
```