Metadata-Version: 2.4
Name: issyx-sign
Version: 1.0.0
Summary: Official Python client for the Issyx Sign e-signature API
Author: Issyx
License-Expression: MIT
Keywords: issyx,e-signature,esignature,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# issyx-sign

Official Python client for the Issyx Sign e-signature API.

```bash
pip install issyx-sign
```

Requires Python 3.10+.

## Authentication

Create an API key from **Organization → API keys** in the Issyx Sign dashboard (org admin only). API keys are scoped to one organization and bypass per-user permission checks — treat them like a full-access credential for that org.

```python
from issyx_sign import IssyxSignClient

client = IssyxSignClient(
    api_key="issyx_...",
    # base_url defaults to https://app.issyx.com/sign/api -- override for a self-hosted instance
    base_url="https://your-instance.example.com/api",
)
```

Webhook management (`list_webhooks`/`create_webhook`/`update_webhook`/`delete_webhook`) runs on session authentication rather than an API key — pass `session_cookie=` (the value of an `issyx_sign_session` cookie) instead of `api_key=` if you need those.

## Send a document for signature

```python
with open("contract.pdf", "rb") as f:
    doc = client.upload_document(file=f, filename="contract.pdf", title="Master Services Agreement")

client.add_recipients(doc["id"], [
    {"email": "alice@example.com", "name": "Alice", "recipient_role": "signer", "signing_order": 0},
    {"email": "bob@example.com", "name": "Bob", "recipient_role": "approver", "signing_order": 1},
])

client.send_document(
    doc["id"],
    sender_name="Jordan Sales",  # attributes invite emails to a real person instead of the API caller
    sender_email="jordan@example.com",
)
```

## Check status / download the signed PDF

```python
result = client.get_document(doc["id"])
print(result["document"]["status"], [(r["email"], r["status"]) for r in result["recipients"]])

if result["document"]["status"] == "completed":
    pdf_bytes = client.download_signed_pdf(doc["id"])
```

## Verify a webhook

Every delivery is a POST with body `{"event": ..., "payload": ..., "timestamp": ...}` (the shape of `payload` depends on `event` — e.g. `document.completed` sends `{"documentId": ...}`) and an `X-Issyx-Signature: sha256=<hex>` header.

```python
from issyx_sign import verify_webhook_signature

@app.route("/issyx-webhook", methods=["POST"])
def issyx_webhook():
    raw_body = request.get_data()  # exact, unparsed bytes -- verify before parsing
    if not verify_webhook_signature(raw_body, request.headers.get("X-Issyx-Signature"), subscription_secret):
        return "", 401

    payload = request.get_json()
    # ... handle payload["event"] / payload["payload"]
    return "", 200
```

## Your own ids, safe retries, and canceling

Give an envelope or a recipient a `reference` (your own id, up to 200 characters) and it comes back on the
document and on every webhook event, so you never need to keep a mapping of Issyx ids. A recipient whose
`reference` is already on the document is skipped, so adding the same party twice is harmless.

Upload, add recipients and send also take an idempotency key. Retrying with the same key returns the first
successful answer instead of doing the work again, so a request that timed out can be retried without making
a second envelope:

```python
with open("contract.pdf", "rb") as f:
    doc = client.upload_document(
        file=f, filename="contract.pdf", title="Master Services Agreement",
        reference="deal-1042", idempotency_key="upload-deal-1042",
    )
client.add_recipients(doc["id"], [{"email": "alice@example.com", "reference": "contact-77"}], idempotency_key="recipients-deal-1042")
client.send_document(doc["id"], idempotency_key="send-deal-1042")

client.remind_document(doc["id"])   # every signer whose turn it is
client.cancel_document(doc["id"])   # withdraw it while it is still open
```

## Error handling

Every non-2xx response raises `IssyxSignError` with `.status`, the parsed error `.body`, and `.code` when the
server gives a machine-readable reason (for example `document_not_sendable` or `document_not_cancelable`):

```python
from issyx_sign import IssyxSignError

try:
    client.get_document("does-not-exist")
except IssyxSignError as err:
    if err.status == 404:
        ...
```

## Full method reference

See `GET /api/openapi.json` on your instance for the canonical API reference. Every client method maps 1:1 to a single REST endpoint:

- **Documents**: `list_documents`, `summary`, `upload_document`, `get_document`, `delete_document`, `add_recipients`, `send_document`, `remind_document`, `cancel_document`, `download_signed_pdf`, `get_analytics`
- **Templates**: `list_templates`, `create_template`, `use_template`, `bulk_send_template`, `get_merge_fields`
- **Webhooks** (session_cookie only): `list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook`
