Quickstart Guide

Installation

pip install -e .

Configuration

Create a .env.staging file in your project root:

ABCONNECT_USERNAME=myuser
ABCONNECT_PASSWORD=mypass
ABCONNECT_CLIENT_ID=myapp
ABCONNECT_CLIENT_SECRET=my-secret-uuid
ABCONNECT_ENVIRONMENT=staging

Basic Usage

from ab import ABConnectAPI

# Initialize — authenticates automatically
api = ABConnectAPI(env="staging")

Common Operations

Get a Company

company = api.companies.get_by_id("93179b52-3da9-e311-b6f8-000c298b59ee")
print(company.name)  # "Navis Pack & Ship #14004OH"

# Or use a company code
company = api.companies.get_by_id("14004OH")

Get Current User’s Contact

me = api.contacts.get_current_user()
print(me.full_name)

Search Companies

results = api.companies.search({"searchText": "Navis"})
for r in results:
    print(r.id, r.name)

List Catalogs

# Basic listing
catalogs = api.catalog.list()

# With filter parameters
catalogs = api.catalog.list(agent="Smith", is_completed=False, page_size=10)

Paginate Through All Results

from ab import ABConnectAPI, paginate

api = ABConnectAPI(env="staging")
for page in paginate(api.catalog.list, page_size=10):
    for item in page.items:
        print(item.title)

Get Lookup Data

countries = api.lookup.get_countries()
statuses = api.lookup.get_job_statuses()
contact_types = api.lookup.get_contact_types()

List Users and Roles

users = api.users.list({"page": 1, "pageSize": 10})
roles = api.users.get_roles()

Django Integration

from ab import ABConnectAPI

def my_view(request):
    api = ABConnectAPI(request=request)
    company = api.companies.get_by_id("14004OH")
    return render(request, "company.html", {"company": company})

When using request=, tokens are stored in the Django session instead of the filesystem.

For a login view, authenticate explicitly with form credentials:

def login_view(request):
    api = ABConnectAPI(request=request, allow_password_fallback=False)
    api.login(request.POST["username"], request.POST["password"])

allow_password_fallback=False is recommended for user-session flows so an expired session token cannot fall back to service-account credentials.

Error Handling

from ab.exceptions import AuthenticationError, RequestError

try:
    company = api.companies.get_by_id("nonexistent")
except RequestError as e:
    print(f"API error {e.status_code}: {e.message}")
except AuthenticationError:
    print("Invalid credentials")