FastBound Core Module¶

Technical name: fastbound_core Version: 18.0.1.0.0 Category: Inventory / Compliance Dependencies: base, mail, contacts, stock, product, product_addons

The Core module is the foundation of the entire FastBound integration. It provides the centralized API client, configuration management, contact synchronization, SmartList reference data, and webhook infrastructure that all other modules depend on.

API Configuration¶

Configuration Record¶

Each FastBound account is represented by a fastbound.configuration record. Navigate to FastBound > Configuration to manage them.

Fields¶

Field	Required	Description
Name	Yes	Friendly label for this configuration
Account ID	Yes	Your FastBound account number (visible in your FastBound URL)
API Key	Yes	API key from FastBound settings (admin-only field)
API URL	Yes	Base URL -- defaults to `https://cloud.fastbound.com`
Audit User	No	Email recorded in FastBound audit trail
Company	Yes	Odoo company this account belongs to
Warehouse	No	Default warehouse for inventory operations
Timezone	Auto	Imported from FastBound on connection test
Webhook Base URL	Auto	Public HTTPS URL for webhook callbacks
Acquire On/After	No	Only sync acquisitions on or after this date

States¶

A configuration moves through three states:

stateDiagram-v2
    [*] --> Draft
    Draft --> Active : Test Connection + Activate
    Active --> Inactive : Deactivate
    Inactive --> Active : Re-Activate

State	Meaning
Draft	Initial state -- credentials entered but not verified
Active	Connection verified, ready for use
Inactive	Temporarily disabled (no API calls will be made)

Account Uniqueness

A SQL constraint enforces that each Account ID is unique per company. You cannot create two configurations pointing to the same FastBound account within one Odoo company.

Connection Test¶

The Test Connection button calls the FastBound GET /Account endpoint. On success:

A green notification confirms the connection.
The account timezone is automatically saved.
The configuration can be activated.

API Service¶

All HTTP communication with FastBound goes through the fastbound.api.service abstract model. This centralized client provides:

Authentication¶

FastBound uses HTTP Basic Authentication. The API key is used as both the username and password, Base64-encoded into an Authorization header. The raw API key is also sent in the apiToken header. An X-AuditUser header records who performed each action.

Retry Logic with Exponential Backoff¶

Scenario	Behavior
HTTP 429 (Rate Limit)	Wait and retry with exponential backoff (2s, 4s, 8s)
HTTP 5xx (Server Error)	Retry up to 3 times with exponential backoff
Timeout / Connection Error	Retry up to 3 times with exponential backoff
HTTP 4xx (Client Error)	Fail immediately with a descriptive error message

Rate Limiting¶

FastBound limits batch operations to 50 items per API call. The acquisition and disposition modules automatically chunk larger batches (see Acquisition and Disposition docs).

Request Constants¶

Constant	Value
`MAX_BATCH_SIZE`	50
`DEFAULT_TIMEOUT`	30 seconds
`MAX_RETRIES`	3
`RETRY_BACKOFF_BASE`	2 (exponential: 2s, 4s, 8s)

Contact Synchronization¶

FastBound Partner Model¶

The fastbound.partner model links Odoo res.partner records to FastBound contacts. A single Odoo partner can have multiple FastBound links (one per configuration/account).

Key Fields¶

Field	Description
FastBound ID	UUID assigned by FastBound
External ID	Odoo partner ID sent to FastBound for cross-referencing
FFL Number	Federal Firearms License number (format: `X-XX-XXX-XX-XX-XXXXX`)
FFL Expires	License expiration date
FFL Expired	Auto-computed boolean
License Name	Name on the FFL license
Trade Name	Business DBA name
Organization Name	Organization/company name
SOT/EIN	Special Occupational Tax / Employer Identification Number

FFL Validation¶

FFL numbers are validated on entry using two regex patterns:

Format	Pattern	Example
With dashes (20 chars)	`X-XX-XXX-XX-XX-XXXXX`	`1-23-456-78-90-12345`
Without dashes (15 chars)	`XXXXXXXXXXXXXXX`	`123456789012345`

When a 15-character FFL is entered, dashes are automatically inserted. Invalid formats trigger a validation error.

Syncing Contacts¶

Odoo to FastBound¶

Click Sync to FastBound on a FastBound partner record to create or update the contact in FastBound. The module:

Prepares contact data (name, address, phone, email, FFL info).
Maps Odoo partner status to FastBound status (Active to Approved, Inactive to Denied, Pending to Caution).
Creates (POST) or updates (PUT) the contact via the API.

FastBound to Odoo¶

Click Refresh from FastBound to pull the latest data. The module updates:

FFL number, expiration, and expired flag
License name, trade name, organization name
SOT/EIN
All license records attached to the contact

FFL Lookup

The FFL Lookup wizard calls FastBound's POST /Contacts with lookupFFL: true to query the ATF database. This auto-populates license name, trade name, SOT class, address, and expiration date from official ATF records.

License Management¶

Licenses are tracked in license.info.line records attached to each FastBound partner. Each license has:

Field	Description
Type	License type from SmartList (FFL, SOT, etc.)
Number	License number
Expiration	Expiration date
Copy on File	Whether a copy is on file
Posted to FastBound	Sync status flag
FastBound License ID	UUID in FastBound

FastBound Is Source of Truth

Licenses flow from FastBound to Odoo only. The ATF database is the authoritative source for license data. Pushing license changes from Odoo to FastBound is intentionally disabled to prevent overwriting official ATF records.

FFL Expiration Monitoring¶

A daily cron job checks for FFLs expiring within 30 days and creates warning activities on the partner record, so your team is alerted before a vendor or customer's license lapses.

Partner Extensions¶

The Core module extends res.partner with:

Field	Description
Is FFL (`requires_compliance`)	Flags this partner as a Federal Firearms Licensee
FastBound Links	One2many to all `fastbound.partner` records
Has FastBound Link	Computed -- whether at least one link exists
Primary FFL	Computed -- FFL number from the first linked record
FFL Expired	Computed -- whether the primary FFL is expired

When compliance-relevant fields change on res.partner (name, address, phone, email), the module can trigger a sync to FastBound.

SmartList Reference Data¶

SmartLists are FastBound's master data lists. The Core module syncs them into dedicated Odoo models so that dropdown menus throughout the system always show current values.

Available SmartLists¶

SmartList	Odoo Model	Company-Specific	Description
Manufacturer	`acquisition.manufacturer`	No	Glock, Ruger, S&W, etc.
Caliber	`acquisition.caliber`	No	9mm, .45 ACP, 5.56 NATO
ItemType	`product.type`	No	Pistol, Rifle, Shotgun, Frame
Condition	`item.condition`	Yes	New, Used, Refurbished
Importer	`acquisition.importer`	No	Century Arms, IWI US
AcquireType	`acquire.type`	Yes	Purchase, Consignment
DisposeType	`general.dispose.type`	Yes	Sale, Transfer
TheftLossType	`disposition.sub.type`	Yes	Stolen, Lost
LicenseType	`license.type`	Yes	FFL, SOT

Additional Local Models¶

Model	Description
`product.model`	Firearm models (local only, not synced from FastBound)
`partner.status`	Contact status for local management
`webhook.event`	Webhook event types synced from FastBound

Sync Behavior¶

New values are created automatically when they appear in the SmartList.
Existing values are not overwritten (idempotent sync).
Company-specific models store one copy per company; others are shared globally.
A Last SmartList Sync timestamp is recorded on each configuration.
The weekly cron job refreshes all SmartLists for all active configurations.

Webhook Infrastructure¶

Webhooks enable FastBound to push changes back to Odoo in real time. The Core module provides both the configuration framework and the event processing pipeline.

Webhook Configuration¶

Each webhook is a fastbound.webhook record with:

Field	Description
Name	Unique identifier in FastBound (e.g., `odoo-contacts`)
Endpoint Path	Local URL path (e.g., `/fastbound/contact`)
Description	Human-readable description
Events	Many2many to `webhook.event` records
Synced	Whether registered with FastBound
Signing Secret	HMAC signing key from FastBound (admin-only)

Standard Webhooks¶

The Setup Standard Webhooks button creates five pre-configured webhooks covering all major event categories. See the Overview for the full list.

Webhook Processing Pipeline¶

Incoming webhook payloads are stored as fastbound.history records and processed through a queue:

flowchart LR
    A[FastBound Event] -->|HTTPS POST| B[Odoo Controller]
    B --> C[fastbound.history record]
    C -->|Cron Job| D{Route by Model}
    D --> E[Partner Handler]
    D --> F[Item Handler]
    D --> G[Acquisition Handler]
    D --> H[Disposition Handler]

History Record Fields¶

Field	Description
Webhook ID	Unique ID from the payload
Event Name	Event type (e.g., `contact.created`, `item.acquired`)
Model	Target Odoo model
Operation	`create`, `write`, or `delete`
State	`draft` (pending), `in_progress`, `done`, or `error`
JSON Data	Raw webhook payload
Retry Count	Number of processing attempts

Processing States¶

State	Meaning
Pending	Queued for processing
Processing	Currently being handled
Completed	Successfully processed
Error	Processing failed (will be retried up to 3 times)

Event Handlers¶

The Core module handles these event types:

Event	Handler	Action
`contact.created`	`_create_partner_from_webhook`	Creates `res.partner` + `fastbound.partner` link
`contact.edited`	`_update_partner_from_webhook`	Updates partner fields
`contact.deleted`	`_delete_partner_from_webhook`	Clears FastBound ID (soft delete)
`item.acquired`	`_handle_item_acquired`	Updates `stock.lot` with FastBound data
`item.disposed`	`_handle_item_disposed`	Marks lot as disposed
`item.deleted`	`_handle_item_deleted`	Clears FastBound tracking from lot
`item.edited`	`_handle_item_edited`	Updates lot fields
`acquisition.committed`	`_handle_acquisition_committed`	Updates lots with item numbers
`acquisition.deleted`	`_handle_acquisition_deleted`	Clears FastBound data from lots

Failed events can be manually reprocessed or marked as done from the FastBound > History list view.

Multi-Company Support¶

The entire FastBound integration is company-aware:

Configuration records are company-specific. Each company gets its own FastBound account.
SmartList data for company-specific models (Condition, AcquireType, DisposeType, etc.) is isolated per company.
Record rules enforce that users only see data from their current company.
Partner links (fastbound.partner) are tied to a configuration, which is tied to a company.
The res.company model is extended with FFL number, FFL expiration, and a default FastBound configuration field.

Company FFL Settings¶

The Core module extends res.company with fields for your own FFL:

Field	Description
FFL Number	Your company's Federal Firearms License number
FFL Expiration	Your FFL expiration date
Default FastBound Config	The default FastBound configuration for this company

These fields are used throughout the acquisition and disposition modules to identify your company as the licensee.

Bound Book Download¶

The configuration form includes a Download Bound Book button that requests a PDF export from FastBound's POST /Downloads/BoundBook endpoint. The file opens in a new browser tab for download or printing.