Client Usage - Nioron07/Easy-Acumatica GitHub Wiki

This page provides a practical guide to using the AcumaticaClient wrapper in easy-acumatica. You’ll learn how to import, initialize, manage sessions, access sub‑services, and perform common API calls—all with concise examples.

1. Importing the Client

from easy_acumatica import AcumaticaClient

No additional packages are needed—everything is bundled under the top‑level easy_acumatica module.

2. Creating an Instance

Instantiate AcumaticaClient with your connection parameters. By default, the client logs in immediately upon creation.

client = AcumaticaClient(  
    base_url="https://demo.acumatica.com",  
    username="admin",  
    password="Pa$$w0rd",  
    tenant="Company",  
    branch="HQ",  
    locale="en-US",              # Optional: defaults to server setting  
    verify_ssl=True,             # Optional: defaults to True  
    persistent_login=True,       # Optional: defaults to True  
    retry_on_idle_logout=True    # Optional: defaults to True  
)

Parameters:

base_url (str): Root URL of the Acumatica site (no trailing slash).
username (str): Your Acumatica user name.
password (str): Your Acumatica password.
tenant (str): Target tenant (company) code.
branch (str): Branch code within the tenant.
locale (str, optional): UI locale; omit or pass None to use the server default.
verify_ssl (bool, optional): Whether to validate SSL certificates. Defaults to True.
persistent_login (bool, optional): If True (default), the client logs in once upon creation and logs out automatically when the program exits. If False, the client will log in before and log out after every single API call.
retry_on_idle_logout (bool, optional): If True (default), the client will automatically re-authenticate and retry an API call one time if it fails with a 401 Unauthorized error, which can happen if the session times out on the server.

3. Session Lifecycle

The client manages a single authenticated HTTP session via requests.Session.

3.1. Login Behavior

If persistent_login is True, the client logs in upon creation.
You can call client.login() manually if needed, which is useful if you have persistent_login set to False. The method returns the HTTP status code.

  status = client.login()  # 204 if already logged in, otherwise the status from the server

3.2. Logout and Cleanup

Call client.logout() to explicitly end the session and clear cookies.

  status = client.logout() # 204 if not logged in, otherwise the status from the server

A logout is also registered to run automatically when your program exits, ensuring the session is always cleaned up properly.

4. Sub-Services and Properties

Access Acumatica endpoints through typed sub-services attached to the client.

Property	Type	Description
session	`requests.Session`	The underlying HTTP session for all requests.
contacts	`ContactsService`	Methods for the Contact entity.
customers	`CustomersService`	Methods for the Customer entity.
codes	`CodesService`	Methods for payroll and benefit codes.
files	`FilesService`	Methods for file attachments.
inquiries	`InquiriesService`	Methods for Generic Inquiries.
records	`RecordsService`	Generic CRUD for any top-level entity.
transactions	`TransactionsService`	Methods for retrieving ledger transaction data.
actions	`ActionsService`	Methods for executing standard and custom business logic actions.
activities	`ActivitiesService`	Methods for creating and linking activities to other records.
accounts	`AccountsService`	Methods for managing GL Accounts and Account Groups.
payments	`PaymentsService`	Methods for creating, retreiving, and releasing payments.
invoices	`InvoicesService`	Allows for creating, retreiving, updating, and releasing invoices.
employees	`EmployeesService`	Simple service which provides creation and retrieval functionality for employees.
leads	`LeadsService`	Allows for the creation of new leads
ledgers	`LedgersService`	Allows for the retrieval of ledger records

5. `get_endpoint_info()`

This method is meant to provide general Acumatica build information as well as provide a list of endpoints

client = AcumaticaClient(
      base_url=cfg["ACU_URL"],
      username=cfg["ACU_USER"],
      password=cfg["ACU_PASS"],
      tenant=cfg["ACU_TENANT"],
      branch=cfg.get("ACU_BRANCH"),
      locale=cfg.get("ACU_LOCALE"),
  )

  endpoints = client.get_endpoint_info()
  print(endpoints)
# {
#     "version": {
#         "acumaticaBuildVersion": "25.093.0036",
#         "databaseVersion": "25.093.0036"
#     },
#     "endpoints": [
#         {
#             "name": "Default",
#             "version": "20.200.001",
#             "href": "/testdata/entity/Default/20.200.001/"
#         },
#         {
#             "name": "eCommerce",
#             "version": "20.200.001",
#             "href": "/testdata/entity/eCommerce/20.200.001/"
#         },
#         {
#             "name": "MANUFACTURING",
#             "version": "21.200.001",
#             "href": "/testdata/entity/MANUFACTURING/21.200.001/"
#         },
#         {
#             "name": "Default",
#             "version": "22.200.001",
#             "href": "/testdata/entity/Default/22.200.001/"
#         },
#         {
#             "name": "eCommerce",
#             "version": "22.200.001",
#             "href": "/testdata/entity/eCommerce/22.200.001/"
#         },
#         {
#             "name": "GLConsolidation",
#             "version": "22.200.001",
#             "href": "/testdata/entity/GLConsolidation/22.200.001/"
#         },
#         {
#             "name": "MANUFACTURING",
#             "version": "23.100.001",
#             "href": "/testdata/entity/MANUFACTURING/23.100.001/"
#         },
#         {
#             "name": "Default",
#             "version": "23.200.001",
#             "href": "/testdata/entity/Default/23.200.001/"
#         },
#         {
#             "name": "DeviceHub",
#             "version": "23.200.001",
#             "href": "/testdata/entity/DeviceHub/23.200.001/"
#         },
#         {
#             "name": "eCommerce",
#             "version": "23.200.001",
#             "href": "/testdata/entity/eCommerce/23.200.001/"
#         },
#         {
#             "name": "MANUFACTURING",
#             "version": "23.200.001",
#             "href": "/testdata/entity/MANUFACTURING/23.200.001/"
#         },
#         {
#             "name": "Default",
#             "version": "24.200.001",
#             "href": "/testdata/entity/Default/24.200.001/"
#         },
#         {
#             "name": "eCommerce",
#             "version": "24.200.001",
#             "href": "/testdata/entity/eCommerce/24.200.001/"
#         },
#         {
#             "name": "MANUFACTURING",
#             "version": "24.200.001",
#             "href": "/testdata/entity/MANUFACTURING/24.200.001/"
#         },
#         {
#             "name": "MANUFACTURING",
#             "version": "25.100.001",
#             "href": "/testdata/entity/MANUFACTURING/25.100.001/"
#         }
#     ]
# }

5. Usage Examples

5.1. Fetching Customers

from easy_acumatica.models.filter_builder import F  
from easy_acumatica.models.query_builder import QueryOptions

# Find all active customers in the RETAIL class  
my_filter = (F.Status == 'Active') & (F.CustomerClass == 'RETAIL')  
opts = QueryOptions(filter=my_filter, select=["CustomerID", "CustomerName"])

# Retrieve a list of customers (returns JSON-decoded dict)  
customers = client.customers.get_customers("24.200.001", options=opts)  
print(customers)

5.2. Creating a Generic Record

Combine AcumaticaClient with RecordBuilder to post new records to any endpoint.

from easy_acumatica.models.record_builder import RecordBuilder

# Build payload for a new Stock Item  
payload = (  
    RecordBuilder()  
    .field("InventoryID", "NEW-ITEM-001")  
    .field("Description", "A Brand New Stock Item")  
    .field("ItemClass", "STOCKITEM")  
)

# Send the create request using the generic records service  
response = client.records.create_record(  
    api_version="24.200.001",  
    entity="StockItem",  
    record=payload  
)  
print(response)

5.3. Explicit Logout

This is optional if persistent_login is True, as it will happen automatically

client.logout()