Quickstart

Follow this guide to understand the fundamental workflow of `easy-acumatica`. Each step introduces a core concept, from initializing the client to filtering data.

1. Initialize the Client

Everything starts with the `AcumaticaClient`. This object is the main entry point to the API, and it handles all the complex session management (login, cookies, logout) for you. You only need to create one instance for your application.


from easy_acumatica import AcumaticaClient

# The client handles login automatically
client = AcumaticaClient(
    base_url="https://your-instance.acumatica.com",
    username="your_username",
    password="your_password",
    tenant="YourTenant",
    branch="YourBranch"
)

2. Use a Sub-Service

The client provides access to modular sub-services that are organized by Acumatica entities. These services are attached directly to the client instance. For example, to interact with customers, you call methods on `client.customers`. To work with invoices, you'd use `client.invoices`.


# Get a list of all customers using the 'customers' sub-service
all_customers = client.customers.get_customers(api_version="24.200.001")

3. Use a Builder

To create or update records, you use fluent builders. These helper classes allow you to construct complex JSON payloads in a clean, readable way by chaining methods. Builders for specific entities are found in the `easy_acumatica.models` module.


from easy_acumatica.models.customer_builder import CustomerBuilder

# Create a builder instance for a new customer
customer_builder = (
    CustomerBuilder()
    .customer_id("NEWCUST01")
    .customer_name("New Awesome Customer")
    .customer_class("DEFAULT")
)

# This builder object is now ready to be passed to a create method
# e.g., client.customers.create_customer("24.200.001", customer_builder)

4. Filter with QueryOptions

When fetching data, you can refine your results using the `QueryOptions` class and the `F` filter factory object, both also available in `easy_acumatica.models`. This provides a typed, Pythonic way to create complex OData queries for filtering, selecting specific fields, and more.


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

# Define query options to get the top 5 active customers,
# selecting only their ID and name.
options = QueryOptions(
    filter=F.Status == 'Active',
    select=['CustomerID', 'CustomerName'],
    top=5
)

# Pass the options to the get_customers method
active_customers = client.customers.get_customers(
    api_version="24.200.001",
    options=options
)

for customer in active_customers:
    print(customer['CustomerName']['value'])