Python Private API SDK

A Python client library for the CATAPA Private API with session-based authentication.

Features

• 🔐 Session-Based Authentication - Automatic login and session management with cookie handling

• 🚀 Simple API - Clean interface for making authenticated requests to CATAPA Private API

• 🔄 Automatic Session Management - Sessions are automatically maintained and refreshed

Installation

Using pip

pip

pip install catapa-private

poetry

uv

Quick Start

A complete Hello World example to get you started immediately.

from catapa_private import CatapaPrivate

def main() -> None:
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    response = client.get("/core/countries", params={"page": 0, "size": 10})
    response.raise_for_status()
    data = response.json()
    print(f"Found {len(data.get('content', []))} countries")

if __name__ == "__main__":
    main()

💡 Tip: By default, the SDK connects to https://api.catapa.com. To use a different base URL (e.g., for staging or testing), pass the base_url parameter:

client = CatapaPrivate(
    tenant="your-tenant",
    username="your-username",
    password="your-password",
    base_url="https://api-development.catapa.com"  # Optional: override default base URL
)

Getting Your Credentials

To use the SDK with your own account, you'll need the following authentication credentials:

Tenant ID

Your tenant ID is your organization's unique identifier in CATAPA. To obtain it, please contact [e-mail].

Username and Password

Your username and password are your CATAPA account credentials used for session-based authentication.

⚠️ Important: Keep your credentials secure and never commit them to version control. Consider using environment variables or a secrets management system.

Private API Documentation

Explore our interactive Swagger documentation to understand the available endpoints, request schemas, and response models for each module.

Core API

https://api.catapa.com/core/swagger/swagger-ui/index.html

Time Management

https://api.catapa.com/timemanagement/swagger/swagger-ui/index.html

Recruitment

https://api.catapa.com/recruitment/swagger/swagger-ui/index.html

Tutorials

More intermediate examples to help you learn the SDK.

Tutorial 1: Complete CRUD Operations

A complete example showing how to perform Create, Read, Update, and Delete operations.

import random
import string

from catapa_private import CatapaPrivate

def main() -> None:
    """Main function demonstrating CRUD operations."""
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    # Step 1: GET - Retrieve list of countries
    response = client.get("/core/countries", params={"page": 0, "size": 10})
    response.raise_for_status()
    data = response.json()
    countries = data.get("content", [])
    print(f"Found {len(countries)} countries")

    # Step 2: POST - Create a new country
    random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
    new_country = {
        "code": f"IDN{random_suffix[:3].upper()}",
        "callingCode": "+62",
        "name": f"Indonesia_{random_suffix}",
        "taxTreaty": True,
    }
    response = client.post("/core/countries", json=new_country)
    response.raise_for_status()
    created_country = response.json()
    country_id = created_country.get("id")
    print(f"Created country: {created_country.get('name')} (ID: {country_id})")

    # Step 3: GET - Retrieve the created country by ID
    response = client.get(f"/core/countries/{country_id}")
    response.raise_for_status()
    retrieved_country = response.json()
    print(f"Retrieved country: {retrieved_country.get('name')}")

    # Step 4: PUT - Update the country
    retrieved_country["name"] = f"Indonesia_{random_suffix}_updated"
    response = client.put(f"/core/countries/{country_id}", json=retrieved_country)
    response.raise_for_status()
    updated_country = response.json()
    print(f"Updated country: {updated_country.get('name')}")

    # Step 5: DELETE - Delete the country
    payload = [{"id": country_id}]
    response = client.delete("/core/countries", json=payload)
    response.raise_for_status()
    print(f"Deleted country (ID: {country_id})")

if __name__ == "__main__":
    main()

Tutorial 2: Error Handling and Response Management

A complete example showing how to handle errors and manage responses properly.

from catapa_private import CatapaPrivate
from requests.exceptions import HTTPError, RequestException

def main() -> None:
    """Main function demonstrating error handling."""
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    try:
        response = client.get("/core/countries", params={"page": 0, "size": 10})
        response.raise_for_status()
        data = response.json()
        print(f"Success: Retrieved {len(data.get('content', []))} countries")
    except HTTPError as e:
        print(f"HTTP Error {e.response.status_code}: {e.response.text}")
    except RequestException as e:
        print(f"Request failed: {e}")

if __name__ == "__main__":
    main()

Cookbook

Intermediate to Advanced examples for real-world scenarios.

Cookbook 1: Concurrent API Calls

A complete example for making concurrent API calls efficiently.

from catapa_private import CatapaPrivate
from concurrent.futures import ThreadPoolExecutor, as_completed

def main() -> None:
    """Main function for concurrent API calls example."""
    client = CatapaPrivate(
        tenant="zfrl",
        username="demo",
        password="dmo-password"
    )

    # Define API call functions
    def get_countries():
        response = client.get("/core/countries", params={"page": 0, "size": 10})
        response.raise_for_status()
        return response.json()

    def get_banks():
        response = client.get("/core/banks", params={"page": 0, "size": 10})
        response.raise_for_status()
        return response.json()

    def get_companies():
        response = client.get("/core/companies", params={"page": 0, "size": 10})
        response.raise_for_status()
        return response.json()

    # Execute API calls concurrently
    with ThreadPoolExecutor(max_workers=3) as executor:
        futures = {
            executor.submit(get_countries): "countries",
            executor.submit(get_banks): "banks",
            executor.submit(get_companies): "companies"
        }

        results = {}
        for future in as_completed(futures):
            task_name = futures[future]
            try:
                results[task_name] = future.result()
                print(f"✅ {task_name} retrieved successfully")
            except Exception as e:
                print(f"❌ {task_name} failed: {e}")

    # Use the results
    if "countries" in results:
        data = results["countries"]
        print(f"Countries: {len(data.get('content', []))}")
    if "banks" in results:
        data = results["banks"]
        print(f"Banks: {len(data.get('content', []))}")
    if "companies" in results:
        data = results["companies"]
        print(f"Companies: {len(data.get('content', []))}")

if __name__ == "__main__":
    main()

Requirements

• Python 3.11+