AcumaticaClient

Version v0.3.9

The `AcumaticaClient` is the core of the package. It's the primary object you'll interact with to manage sessions, access API services, and configure connection behavior. This page provides an in-depth guide to every aspect of the client.

Initialization

Instantiate the `AcumaticaClient` with your ERP credentials. By default, the client logs in immediately upon creation. Below is a breakdown of every parameter you can use.

base_url

Type: str | Required

This is the root URL of your Acumatica ERP instance. It should not include a trailing slash.

client = AcumaticaClient(base_url='https://my-erp.acumatica.com', ...)

username, password, tenant, branch

Type: str | Required

These are your standard Acumatica login credentials. Ensure the user has the necessary API access rights.

client = AcumaticaClient(
    username='api-user',
    password='YourPassword',
    tenant='YourCompanyTenant',
    branch='MAINBRANCH',
    ...
)

persistent_login

Type: bool | Default: True

This parameter controls the session lifecycle. When `True`, the client logs in once upon creation and registers an automatic logout for when your script exits. This is efficient for scripts making multiple API calls. When `False`, the client will perform a login before and a logout after every single API call, which is less efficient but can be useful in certain serverless or stateless environments.

# For long-running scripts (recommended)
client = AcumaticaClient(persistent_login=True, ...)

# For single-use or stateless functions
client_stateless = AcumaticaClient(persistent_login=False, ...)

retry_on_idle_logout

Type: bool | Default: True

If your script is idle for longer than the server's session timeout, your next API call will fail with a `401 Unauthorized` error. When this parameter is `True`, the client will automatically detect this specific error, re-authenticate, and retry the failed API call one time. This adds significant resiliency to long-running applications.

# A resilient client that can recover from session timeouts
client = AcumaticaClient(retry_on_idle_logout=True, ...)

Sub-Services

Access Acumatica endpoints through typed sub-services attached directly to the client instance. This provides a clean, object-oriented way to organize your API calls.


# Fetch customers using the 'customers' service
customers = client.customers.get_customers("24.200.001")

# Create an invoice using the 'invoices' service
# new_invoice = client.invoices.create_invoice(...)

get_endpoint_info()

This utility method retrieves the Acumatica build version and a list of all available API endpoints and their versions from your instance. This is useful for discovery and ensuring compatibility.


# Fetch endpoint information
endpoints_info = client.get_endpoint_info()

# Print the Acumatica build version
print(endpoints_info['version']['acumaticaBuildVersion'])

# List all available endpoint versions
for endpoint in endpoints_info['endpoints']:
    if endpoint['name'] == 'Default':
        print(f"Default Endpoint Version: {endpoint['version']}")