esignbase-sdk 1.1.0
Python SDK for eSignBase – eIDAS-compliant digital signatures and GDPR-ready electronic signing via REST API.
Requires Python: <4.0,>=3.10
Keywords: digital signature, electronic signature, eIDAS, GDPR, REST API, document signing, e-signature, legal signature, EU compliance, python sdk

# eSignBase Python SDK

Official Python SDK for integrating **eIDAS-compliant digital signatures** into your application using the eSignBase REST API.

eSignBase provides GDPR-ready electronic signatures with EU-based infrastructure and flexible pay-as-you-go pricing — no subscriptions, no per-seat licenses.

This SDK offers a simple, synchronous client for creating signing requests, managing templates, and retrieving signed documents programmatically.

## Why eSignBase?

- ✅ eIDAS-compliant electronic signatures
- ✅ GDPR-aligned EU data hosting
- ✅ Simple REST API
- ✅ No subscriptions — pay-as-you-go credits
- ✅ Lightweight and easy to integrate

## Documentation

Full REST API documentation:
https://esignbase.com/en/api_documentation

A step-by-step integration guide:
https://esignbase.com/en/blog/rest-api-guide

### Classes

**GrantType** (Enum)

Defines the available OAuth2 grant types:

* CLIENT_CREDENTIALS: For server-to-server authentication
* AUTHORIZATION_CODE: For user-specific authentication


**Scope** (Enum)

Defines the available API permission scopes:

* ALL: Full access to all API endpoints
* READ: Read-only access
* CREATE_DOCUMENT: Permission to create documents
* DELETE: Permission to delete documents
* SANDBOX: Access to the sandbox environment, use this scope for testing

**OAuth2Client**

Main client class that stores authentication credentials and state.

Attributes:
```python
id (str) # Client ID from ESignBase
secret (str) # Client secret from ESignBase
grant_type (GrantType) # OAuth2 grant type to use
user_name (Optional[str]) # Username (required AUTHORIZATION_CODE)
password (Optional[str]) # Password (required AUTHORIZATION_CODE)
scope (list[Scope]) # List of requested API scopes
```
Retrieve your Client ID and Client Secret at https://app.esignbase.com/oauth2/client by creating an
OAuth2 Client Configuration.

**Recipient**

Represents a document recipient/signer.
`role_name` value is defined during template creation in the template editor.

Attributes:
```python
email (str) # Recipient's email address
first_name (str) # Recipient's first name
last_name (str) # Recipient's last name
role_name (str) # Role name (e.g., "Signer", "Viewer")
locale (str) # Locale code ("de", "en", "es")
```

**ESignBaseSDKError** (Exception)

Custom exception class for API-related errors.

### Functions

```python
def connect(client: OAuth2Client) -> None
```

Authenticates with the ESignBase API

Parameters:

    client: Configured OAuth2Client instance

Raises:

    ESignBaseSDKError: If authentication fails or validation fails

Example:
```python
client = OAuth2Client(
    id="your_client_id",
    secret="your_client_secret",
    grant_type=GrantType.CLIENT_CREDENTIALS,
    scope=[Scope.ALL],
)
connect(client)
```
---

```python
def get_templates(client: OAuth2Client) -> list[dict[str, Any]]
```


Retrieves a list of available document templates.

Parameters:
```
client: Authenticated OAuth2Client instance
```

Returns A list of dictionaries containing template data.

Raises:

    ESignBaseSDKError: If the API request fails

---

```python
def get_template(client: OAuth2Client, template_id: str) -> dict[str, Any]
```

Retrieves details of a specific template.

Parameters:

    client: Authenticated OAuth2Client instance
    template_id: Unique identifier of the template

Returns:
    Dictionary containing template details

Raises:
    ESignBaseSDKError: If the API request fails

---

```python
def get_documents(client: OAuth2Client, limit: int, offset: int) -> dict[str, Any]
```
Retrieves a paginated list of documents.

Parameters:

    client: Authenticated OAuth2Client instance
    limit: Maximum number of documents to return
    offset: Pagination offset

Returns:

    Dictionary containing document list and pagination info `{documents: [...]}`

Raises:

    ESignBaseSDKError: If the API request fails

---

```python
def get_document(client: OAuth2Client, document_id: str) -> dict[str, Any]
```

Retrieves details of a specific document.

Parameters:

    client: Authenticated OAuth2Client instance
    document_id: Unique identifier of the document

Returns:

    Dictionary containing document details

Raises:

    ESignBaseSDKError: If the API request fails

---

```python
def create_document(
    client: OAuth2Client,
    *,
    template_id: str,
    document_name: str,
    recipients: list[Recipient],
    user_defined_metadata: Optional[dict[str, str | int]] = None,
    expiration_date: Optional[datetime] = None
) -> dict[str, Any]
```

Creates a new document from a template.

Parameters:

    client: Authenticated OAuth2Client instance
    template_id: ID of the template to use
    document_name: Name for the new document
    recipients: List of Recipient objects
    user_defined_metadata: Optional metadata to attach to the document
    expiration_date: Optional expiration date for the document

Returns:

    Dictionary containing the created document id and current document status

Raises:

    ESignBaseSDKError: If the API request fails

Example:

```python
recipients = [
    Recipient(
        email="signer@example.com",
        first_name="John",
        last_name="Doe",
        role_name="signer",
        locale="de"
    )
]

document = create_document(
    client=client,
    template_id="template_123",
    document_name="Contract Agreement",
    recipients=recipients,
    user_defined_metadata={"contract_id": "CTR-2024-001"},
    expiration_date=datetime(2024, 12, 31)
)

```

---

```python
def delete_document(client: OAuth2Client, document_id: str) -> None
```

Deletes a specific document.

Parameters:

    client: Authenticated OAuth2Client instance
    document_id: Unique identifier of the document to delete

Raises:

    ESignBaseSDKError: If the API request fails

---
```python
def download_document(client: OAuth2Client, document_id: str) -> Generator[bytes]
```

Download a completed document.

Parameters:

    client: Authenticated OAuth2Client instance
    document_id: Unique identifier of the document to download

Raises:

    ESignBaseSDKError: If the API request fails

Example Usage:
```python
    with open(f"document.pdf", "wb") as f:
        for chunk in esignbase_sdk.download_document(client, "695e4a4d869ba75efa33aa07"):
            f.write(chunk)
```
---
```python
def get_credits(client: OAuth2Client) -> dict[str, Any]
```

Retrieves credit balance information.

Parameters:

    client: Authenticated OAuth2Client instance

Returns:

    Dictionary containing credit balance data

Raises:

    ESignBaseSDKError: If the API request fails

Error Handling

All functions raise ESignBaseSDKError exceptions for API errors, network issues, or validation failures. Always wrap API calls in try-except blocks:

```python
try:
    templates = get_templates(client)
except ESignBaseSDKError as e:
    print(f"API Error: {e}")
```

Complete Example


```python

from datetime import datetime
import esignbase_sdk

# Setup client
client = esignbase_sdk.OAuth2Client(
    id="your_client_id",
    secret="your_client_secret",
    grant_type=GrantType.CLIENT_CREDENTIALS,
    scope=[Scope.CREATE_DOCUMENT, Scope.READ]
)

# Authenticate
esignbase_sdk.connect(client)

# Get available templates
templates = esignbase_sdk.get_templates(client)

# Create a document
recipients = [
    esignbase_sdk.Recipient(
        email="alice@example.com",
        first_name="Alice",
        last_name="Smith",
        role_name="Signer",
        locale="en"
    )
]
template_id = templates[0]["id"]

document = esignbase_sdk.create_document(
    client=client,
    template_id=template_id,
    document_name="NDA Agreement",
    recipients=recipients
)

# Check document status
document_details = esignbase_sdk.get_document(client, document["id"])

# Delete the document (if needed)
esignbase_sdk.delete_document(client, document["id"])
```


## Developer Notes:

To build the package, run the following commands inside a virtual environment from the directory
containing this README file.

```bash
python -m pip install --upgrade build
python -m build --wheel
```