Python SDK Custom Requests

Python SDK Custom Requests

Explanation

What are Custom Requests?

The Python SDK provides a generic request() method that lets you call any CATAPA API endpoint, including those not yet wrapped by generated methods.

---

Quickstart

A simple example:

from catapa import Catapa, HTTPMethod

client = Catapa(
    tenant="zfrl",
    client_id="demo",
    client_secret="demo-secret"
)

# Make a custom GET request
response = client.request(
    method=HTTPMethod.GET,
    path="/core/v1/employees",
    params={"page": 0, "size": 10}
)

print(f"Found {len(response.json()['content'])} employees")

---

Tutorial: Basic CRUD Operations

This tutorial demonstrates complete CRUD (Create, Read, Update, Delete) operations on Employee Identity Cards.

Setup

from datetime import datetime, timedelta
from catapa import Catapa, HTTPMethod

EMPLOYEE_ID = "019c4aec-457e-7314-aedb-e9652227d9f6"

client = Catapa(
    tenant="zfrl",
    client_id="demo",
    client_secret="demo-secret"
)

1. CREATE - Add Employee Identity Card

# Get identity card type ID (reference data)
today = datetime.now()
response = client.request(
    method=HTTPMethod.GET,
    path="/core/v1/identity-cards"
)
identity_cards = response.json()
identity_card_id = identity_cards["content"][0]["id"]

# Create employee identity card
employee_identity_card_request = {
    "identityCardId": identity_card_id,
    "identityCardNumber": "123456789012345",
    "expiredDate": (today + timedelta(days=365)).strftime("%Y-%m-%d")
}

response = client.request(
    method=HTTPMethod.POST,
    path=f"/core/v1/employees/{EMPLOYEE_ID}/employee-identity-cards",
    body=employee_identity_card_request
)

if response.status_code == 201:
    result = response.json()
    employee_identity_card_id = result["id"]
    print(f"✓ Created: ID={employee_identity_card_id}")

2. READ - List Employee Identity Cards

response = client.request(
    method=HTTPMethod.GET,
    path=f"/core/v1/employees/{EMPLOYEE_ID}/employee-identity-cards"
)

identity_cards = response.json()
if identity_cards.get("content"):
    for card in identity_cards["content"]:
        print(f"ID: {card['id']}, Number: {card['identityCardNumber']}")

3. UPDATE - Modify Employee Identity Card

updated_data = {
    "identityCardId": identity_card_id,
    "identityCardNumber": "123456789012340",  # Updated number
    "expiredDate": (today + timedelta(days=730)).strftime("%Y-%m-%d")
}

response = client.request(
    method=HTTPMethod.PUT,
    path=f"/core/v1/employees/{EMPLOYEE_ID}/employee-identity-cards/{employee_identity_card_id}",
    body=updated_data
)

if response.status_code in [200, 204]:
    print(f"✓ Updated: ID={employee_identity_card_id}")

4. DELETE - Remove Employee Identity Card

response = client.request(
    method=HTTPMethod.DELETE,
    path=f"/core/v1/employees/{EMPLOYEE_ID}/employee-identity-cards/{employee_identity_card_id}"
)

if response.status_code in [200, 204]:
    print(f"✓ Deleted: ID={employee_identity_card_id}")

---

Cookbook

Recipe 1: Upload Files with Multipart Form-Data

Create a company with logo upload using multipart/form-data:

import json
from catapa import Catapa, HTTPMethod

client = Catapa(
    tenant="zfrl",
    client_id="demo",
    client_secret="demo-secret"
)

company_data = {
    "name": "Demo Corporation",
    "code": "DEMO-001",
    "website": "http://www.demo-corp.catapa.com",
    "siup": "SIUP/123/000-67.8",
    "tdp": "TDP/123/000-67.8",
    "timeZone": {"code": "Asia/Jakarta", "offset": "+07:00"},
    "email": "[e-mail]",
    "location": {"id": "019c7518-7205-77e5-b220-239dba546f63"}
}

with open("company-logo.png", "rb") as logo_file:
    response = client.request(
        method=HTTPMethod.POST,
        path="/core/v1/companies",
        files={
            "request": (None, json.dumps(company_data), "application/json"),
            "file": logo_file
        }
    )

if response.status_code == 201:
    company = response.json()
    print(f"✓ Company created: {company['name']}")
    print(f"  ID: {company['id']}")

Key Points:

• "request" field contains JSON data with application/json content type

• "file" field contains the actual file to upload

• Use None as filename for JSON fields (not a file attachment)

• SDK automatically sets multipart/form-data with boundary

Recipe 2: Download Files

from pathlib import Path
from catapa import Catapa, HTTPMethod

client = Catapa(
    tenant="zfrl",
    client_id="demo",
    client_secret="demo-secret"
)

# 1. List available tax reports
response = client.request(
    method=HTTPMethod.GET,
    path="/core/v1/tax-reports/1721-a1"
)

reports = response.json().get("content", [])
print(f"Found {len(reports)} reports")

# 2. Download the first report
if reports:
    report_id = reports[0]["id"]

    response = client.request(
        method=HTTPMethod.GET,
        path=f"/core/v1/tax-reports/1721-a1/{report_id}/download"
    )

    downloads_dir = Path.home() / "Downloads"
    downloads_dir.mkdir(exist_ok=True)

    filepath = downloads_dir / "tax-report-1721-a1.pdf"
    with open(filepath, "wb") as f:
        f.write(response.content)

    print(f"✓ Downloaded to: {filepath}")

Key Points:

• Use response.content for binary data

• Use response.json() for JSON data

---

Advanced Topics

parse_json Parameter

By default request() returns an HttpResponse object so you can check status_code.

response = client.request(method=HTTPMethod.GET, path="/core/v1/employees")
print(response.status_code)
print(response.json())

If you only need the JSON body, you can enable auto-parse:

data = client.request(
    method=HTTPMethod.GET,
    path="/core/v1/employees",
    parse_json=True
)
print(data["content"][0]["name"])

Content-Type Handling

JSON Requests (default):

client.request(method=HTTPMethod.POST, path="/path", body={"key": "value"})

Multipart Requests (with files):

client.request(method=HTTPMethod.POST, path="/path", files={...})

Important: When using files, do not set Content-Type manually. The SDK sets the correct multipart boundary.

HTTPMethod Enum

from catapa import HTTPMethod

# Using string
client.request(method="GET", path="/path")

# Using HTTPMethod enum
client.request(method=HTTPMethod.GET, path="/path")

Available methods: HTTPMethod.GET, HTTPMethod.POST, HTTPMethod.PUT, HTTPMethod.DELETE, HTTPMethod.PATCH

Response Object (HttpResponse)

response = client.request(method=HTTPMethod.GET, path="/core/v1/employees")

response.status_code   # HTTP status
response.headers       # dict
response.content       # bytes
response.text          # string
response.json()        # parse JSON

---

API Reference

client.request() Parameters

Parameter	Type	Required	Description
method	str | HTTPMethod	✅ Yes	HTTP method (GET, POST, PUT, DELETE, PATCH)
path	str	✅ Yes	API endpoint path (e.g., "/core/v1/employees")
params	dict[str, Any]	❌ No	Query parameters
headers	dict[str, str]	❌ No	Additional headers
body	Any	❌ No	Request body (sent as JSON)
files	dict[str, Any]	❌ No	Files for multipart uploads
parse_json	bool	❌ No	If True, return parsed dict/list

Returns ​ ​ HttpResponse when parse_json=False (default) ​ dict or list when parse_json=True