workbench-sdk 1.0.3

Official Python SDK for the Workbench CRM API

workbench-sdk

Official Python SDK for the Workbench CRM API.

Installation

pip install workbench-sdk

Quick Start

from workbench import WorkbenchClient

# Initialize with your API key
client = WorkbenchClient(api_key="wbk_live_xxxxxxxxxxxxxxxxxxxxx")

# List clients
response = client.clients.list(status="active", per_page=10)
for c in response["data"]:
    print(f"{c['first_name']} {c['last_name']}")

# Create an invoice
invoice = client.invoices.create(
    client_id=response["data"][0]["id"],
    items=[
        {"description": "Consulting Services", "quantity": 2, "unit_price": 150}
    ],
    tax_rate=8.5
)

# Send the invoice
client.invoices.send(invoice["data"]["id"])

Authentication

API Key Authentication

Get your API key from Workbench Settings > API Keys.

client = WorkbenchClient(api_key="wbk_live_xxxxxxxxxxxxxxxxxxxxx")

OAuth Authentication

For third-party applications using OAuth 2.0:

client = WorkbenchClient(access_token="wbk_at_xxxxxxxxxxxxxxxxxxxxx")

Configuration

client = WorkbenchClient(
    api_key="wbk_live_xxx",

    # Optional: Custom base URL (default: https://api.tryworkbench.app)
    base_url="https://api.tryworkbench.app",

    # Optional: Request timeout in seconds (default: 30)
    timeout=30.0,

    # Optional: Maximum retries for failed requests (default: 3)
    max_retries=3
)

Context Manager

The client can be used as a context manager to ensure proper cleanup:

with WorkbenchClient(api_key="wbk_live_xxx") as client:
    response = client.clients.list()

Resources

Clients

# List clients
response = client.clients.list(
    status="active",
    search="john",
    page=1,
    per_page=20
)

# Get a client
result = client.clients.get("client-uuid")

# Create a client
new_client = client.clients.create(
    first_name="John",
    last_name="Doe",
    email="[e-mail]",
    phone="[phone]",
    company="Acme Corp",
    status="active",
    tags=["vip", "commercial"]
)

# Update a client
updated = client.clients.update("client-uuid", status="inactive")

# Delete a client
client.clients.delete("client-uuid")

Invoices

# List invoices
response = client.invoices.list(status="sent", client_id="client-uuid")

# Get an invoice
result = client.invoices.get("invoice-uuid")

# Create an invoice
invoice = client.invoices.create(
    client_id="client-uuid",
    due_date="2024-02-15",
    items=[
        {"description": "Web Development", "quantity": 10, "unit_price": 100},
        {"description": "Hosting Setup", "quantity": 1, "unit_price": 50}
    ],
    tax_rate=8.5,
    notes="Payment due within 30 days"
)

# Update an invoice
client.invoices.update("invoice-uuid", status="paid")

# Send an invoice
client.invoices.send("invoice-uuid")

# Delete an invoice
client.invoices.delete("invoice-uuid")

Quotes

# List quotes
response = client.quotes.list(status="sent")

# Create a quote
quote = client.quotes.create(
    client_id="client-uuid",
    valid_until="2024-03-01",
    items=[
        {"description": "Kitchen Renovation", "quantity": 1, "unit_price": 5000}
    ]
)

# Send a quote
client.quotes.send(quote["data"]["id"])

Jobs

# List jobs
response = client.jobs.list(status="scheduled", priority="high")

# Create a job
job = client.jobs.create(
    client_id="client-uuid",
    title="Kitchen Faucet Installation",
    priority="high",
    scheduled_start="2024-01-20T09:00:00Z",
    scheduled_end="2024-01-20T12:00:00Z"
)

# Update job status
client.jobs.update(job["data"]["id"], status="completed")

Service Requests

# List service requests
response = client.service_requests.list(status="new")

# Create a service request
request = client.service_requests.create(
    title="AC Repair",
    contact_name="Jane Smith",
    contact_email="[e-mail]",
    contact_phone="[phone]",
    address="123 Main St",
    priority="urgent"
)

Webhooks

# List webhooks
response = client.webhooks.list()

# Create a webhook
webhook = client.webhooks.create(
    name="Invoice Notifications",
    url="https://example.com/webhooks/workbench",
    events=["invoice.created", "invoice.paid"]
)

# IMPORTANT: Store the webhook secret securely!
print(f"Webhook secret: {webhook['data']['secret']}")

# Update a webhook
client.webhooks.update(
    webhook["data"]["id"],
    events=["invoice.created", "invoice.paid", "invoice.overdue"]
)

# Delete a webhook
client.webhooks.delete(webhook["data"]["id"])

Webhook Signature Verification

Verify that webhooks are actually from Workbench:

from workbench import verify_webhook_signature, construct_webhook_event, WebhookVerificationError
import os

# In your webhook handler (e.g., Flask)
@app.route("/webhooks", methods=["POST"])
def handle_webhook():
    payload = request.get_data()
    signature = request.headers.get("X-Workbench-Signature")
    secret = os.environ["WEBHOOK_SECRET"]

    try:
        # Option 1: Just verify
        verify_webhook_signature(payload, signature, secret)
        event = json.loads(payload)

        # Option 2: Verify and parse in one step
        event = construct_webhook_event(payload, signature, secret)

        # Handle the event
        if event["event"] == "invoice.paid":
            print(f"Invoice paid: {event['data']['id']}")
        elif event["event"] == "client.created":
            print(f"New client: {event['data']['first_name']}")

        return "", 200

    except WebhookVerificationError as e:
        print(f"Webhook verification failed: {e}")
        return "", 400

Error Handling

from workbench import WorkbenchClient, WorkbenchError

try:
    result = client.clients.get("invalid-uuid")
except WorkbenchError as e:
    print(f"API Error: {e.message}")
    print(f"Status: {e.status}")
    print(f"Code: {e.code}")
    print(f"Request ID: {e.request_id}")

    if e.details:
        for detail in e.details:
            print(f"  {detail['field']}: {detail['message']}")

Type Hints

This SDK includes full type hints for better IDE support:

from workbench import WorkbenchClient
from workbench.types import Client, Invoice, CreateClientParams

client = WorkbenchClient(api_key="wbk_live_xxx")

# Types are inferred
response = client.clients.list()  # ListResponse[Client]
data = response["data"]  # List[Client]

result = client.invoices.get("uuid")  # ApiResponse[Invoice]
invoice = result["data"]  # Invoice

API Documentation

For complete API documentation, visit docs.tryworkbench.app.

Support

• Documentation: docs.tryworkbench.app
• Issues: GitHub Issues
• Email: [e-mail]

License

MIT License - see LICENSE for details.