softsolz

Official Python SDK for the SoftSolz platform API.

pip install softsolz

Requires Python 3.9 or later. Fully type-annotated (py.typed).

Usage

import os
from softsolz import SoftSolz

client = SoftSolz(api_key=os.environ["SOFTSOLZ_API_KEY"])

me = client.whoami()

form = client.forms.create_form({"name": "Contact Us", "status": "published"})
client.forms.submit_form(form["slug"], {"data": {"full_name": "Jane Doe", "email": "jane@example.com"}})

invoice = client.invoicing.create_invoice({
    "customer_id": 42,
    "lines": [{"description": "Design work", "quantity": 1, "unit_price_cents": 50000}],
})
client.invoicing.send_invoice(invoice["id"])

Use an sk_test_* key to run against your sandbox workspace; swap to sk_live_* in production. No other configuration changes.

Services

client.blogs, client.customer_auth, client.forms, client.invoicing, client.payments, client.smart_chat, client.social, client.workflows - one method per API operation, generated from the platform's service manifests.

Pagination

List methods return a Page you can iterate; extra pages are fetched automatically:

for invoice in client.invoicing.list_invoices({"status": "overdue"}):
    print(invoice["invoice_number"])

Or page manually with page.data, page.has_more, and page.next_page().

Errors

All API failures raise a typed subclass of SoftSolzError carrying status, code, message, details, and request_id:

from softsolz import NotFoundError

try:
    client.forms.get_form(999)
except NotFoundError as err:
    print(err.code, err.request_id)

Classes: InvalidRequestError (400/422), AuthenticationError (401), PaymentRequiredError (402), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), RateLimitError (429, with retry_after_seconds), APIConnectionError (network).

Retries and idempotency

429 and 5xx responses are retried automatically with exponential backoff (default 2 retries), honouring Retry-After. Every mutating request carries an auto-generated Idempotency-Key, so retries are always safe. Pass your own to control replays:

client.invoicing.create_invoice(body, idempotency_key="order-1234")

Configure per client: SoftSolz(api_key=..., max_retries=3, timeout=60.0).

Webhooks

Verify the Softsolz-Signature header on incoming webhooks using the raw request body:

from softsolz import webhooks

webhooks.assert_valid(
    raw_body=request.get_data(),
    header_value=request.headers.get("Softsolz-Signature"),
    secret=os.environ["SOFTSOLZ_WEBHOOK_SECRET"],
)

webhooks.verify(...) returns {"valid": False, "reason": ...} if you prefer not to raise.

Escape hatch

Call any endpoint directly while keeping auth, retries, and errors:

client.request("GET", "/api/v1/services/forms/forms", query={"limit": 10})

Sending files

client.files.upload() sends an image, video, PDF or Word, PowerPoint or Excel file to a service and returns a file_id to pass to that service. Files up to 700 KB go inline; larger ones go through a one-time upload link, handled for you.

file = client.files.upload("smart-chat", "handbook.pdf")
client.request(
    "POST",
    "/api/v1/services/smart-chat/kb/documents/import",
    body={"collection_id": collection_id, "file_id": file["file_id"]},
)

The real type is read from the file's bytes, and a file can only be used by the key that sent it, with that service, for 24 hours.

Documentation

• API reference: https://developer.softsolz.uk/api-reference.html
• Webhooks: https://developer.softsolz.uk/webhooks.html
• Developer hub: https://developer.softsolz.uk

License

MIT