12 Entity API Reference

9.3

contents ← prev up next →

12 Entity API Reference🔗

bcnav provides modules for accessing different categories of Business Central entities.

12.1 Master Data🔗

(require bcnav/api/master-data)

package: bcnav-lib

Master data entities represent core business objects like customers, vendors, and items.

12.1.1 Customers🔗

value
customers : bc-entity?

Entity descriptor for BC customers. Use with inspect, peek, and sample.

procedure
(customers-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all customers as a bc-result, optionally filtered by q. Auto-pagination is controlled by current-bc-auto-paginate. See Result Wrapper for working with results.

Example: Customers modified since a specific datetime

The 'lastModifiedDateTime field is an Edm.DateTimeOffset. Use odata-datetime for filtering:

(customers-list
  #:query (make-query
            #:filter (ge 'lastModifiedDateTime
                         (odata-datetime "2024-12-01T00:00:00Z"))
            #:orderby '(lastModifiedDateTime . desc)))

procedure
(customers-get id) → hash?
id : string?

Returns the customer with the given id (a GUID string). Raises exn:fail:bcnav:http if not found.

procedure
(customers-create data) → hash?
data : hash?

Creates a new customer with the given field values. Returns the created customer, including generated fields like 'id.

Required fields typically include 'displayName.

procedure
(customers-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates the customer with the given id. Only fields present in data are modified.

If etag is provided, the update only succeeds if the record’s current ETag matches (optimistic concurrency). Otherwise, a wildcard ETag is used.

Returns the updated customer.

procedure
(customers-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes the customer with the given id.

12.1.2 Vendors🔗

value
vendors : bc-entity?

Entity descriptor for BC vendors. Use with inspect, peek, and sample.

procedure
(vendors-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all vendors as a bc-result.

procedure
(vendors-get id) → hash?
id : string?

Returns the vendor with the given id.

procedure
(vendors-create data) → hash?
data : hash?

Creates a new vendor.

procedure
(vendors-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates a vendor.

procedure
(vendors-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes a vendor.

12.1.3 Items🔗

value
items : bc-entity?

Entity descriptor for BC items (products/services). Use with inspect, peek, and sample.

procedure
(items-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all items (products/services) as a bc-result.

procedure
(items-get id) → hash?
id : string?

Returns the item with the given id.

procedure
(items-create data) → hash?
data : hash?

Creates a new item.

procedure
(items-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates an item.

procedure
(items-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes an item.

12.2 Sales🔗

(require bcnav/api/sales)

package: bcnav-lib

Sales entities for orders and invoices.

12.2.1 Sales Orders🔗

value
sales-order : bc-entity?

Entity descriptor for BC sales orders. Use with inspect, peek, and sample.

procedure
(sales-order-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all sales orders as a bc-result.

Common expand: 'salesOrderLines to include line items.

Example: Open orders from 2024

(sales-order-list
  #:query (make-query
            #:filter (and: (eq 'status "Open")
                           (date-between 'orderDate "2024-01-01" "2024-12-31"))
            #:expand '(salesOrderLines)))

procedure
(sales-order-get id) → hash?
id : string?

Returns the sales order with the given id.

procedure
(sales-order-create data) → hash?
data : hash?

Creates a new sales order.

procedure
(sales-order-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates a sales order.

procedure
(sales-order-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes a sales order.

12.2.2 Sales Invoices🔗

value
sales-invoice : bc-entity?

Entity descriptor for BC sales invoices. Use with inspect, peek, and sample.

procedure
(sales-invoice-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all sales invoices as a bc-result.

Common expand: 'salesInvoiceLines to include line items.

Example: Invoices posted in December 2024

(sales-invoice-list
  #:query (make-query
            #:filter (date-between 'postingDate "2024-12-01" "2024-12-31")
            #:select '(id number customerName totalAmountIncludingTax)))

procedure
(sales-invoice-get id) → hash?
id : string?

Returns the sales invoice with the given id.

procedure
(sales-invoice-create data) → hash?
data : hash?

Creates a new sales invoice.

procedure
(sales-invoice-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates a sales invoice.

procedure
(sales-invoice-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes a sales invoice.

12.3 Purchasing🔗

(require bcnav/api/purchasing)

package: bcnav-lib

Purchasing entities for orders and invoices from vendors.

12.3.1 Purchase Orders🔗

value
purchase-order : bc-entity?

Entity descriptor for BC purchase orders. Use with inspect, peek, and sample.

procedure
(purchase-order-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all purchase orders as a bc-result.

Common expand: 'purchaseOrderLines to include line items.

Example: Open orders expected this month

(purchase-order-list
  #:query (make-query
            #:filter (and: (eq 'status "Open")
                           (date-between 'expectedReceiptDate
                                         "2024-12-01" "2024-12-31"))
            #:expand '(purchaseOrderLines)))

procedure
(purchase-order-get id) → hash?
id : string?

Returns the purchase order with the given id.

procedure
(purchase-order-create data) → hash?
data : hash?

Creates a new purchase order.

Required fields typically include 'vendorNumber or 'vendorId.

procedure
(purchase-order-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates a purchase order.

procedure
(purchase-order-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes a purchase order.

12.3.2 Purchase Invoices🔗

value
purchase-invoice : bc-entity?

Entity descriptor for BC purchase invoices. Use with inspect, peek, and sample.

procedure
(purchase-invoice-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all purchase invoices as a bc-result.

Common expand: 'purchaseInvoiceLines to include line items.

Example: Invoices posted in Q4 2024

(purchase-invoice-list
  #:query (make-query
            #:filter (date-between 'postingDate "2024-10-01" "2024-12-31")
            #:orderby '(postingDate . desc)))

procedure
(purchase-invoice-get id) → hash?
id : string?

Returns the purchase invoice with the given id.

procedure
(purchase-invoice-create data) → hash?
data : hash?

Creates a new purchase invoice.

procedure
(purchase-invoice-update id
data
[ #:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates a purchase invoice.

procedure
(purchase-invoice-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes a purchase invoice.

12.4 Finance🔗

(require bcnav/api/finance)

package: bcnav-lib

Finance entities for the chart of accounts, trial balance, general ledger entries, and journals.

12.4.1 Accounts🔗

value
account : bc-entity?

Entity descriptor for BC G/L accounts (chart of accounts). Use with inspect, peek, and sample.

procedure
(account-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all G/L accounts as a bc-result.

Key fields: 'number, 'displayName, 'category, 'accountType, 'netChange, 'blocked.

Navigation property: 'trialBalance can be expanded to get trial balance data.

procedure
(account-get id) → hash?
id : string?

Returns the G/L account with the given id.

12.4.2 Trial Balance🔗

value
trial-balance : bc-entity?

Entity descriptor for BC trial balance. Use with inspect, peek, and sample.

The trial balance provides account balance information as of a specific date.

procedure
(trial-balance-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns trial balance entries for all accounts as a bc-result.

Key fields:

'accountId — GUID of the related G/L account
'number — Account number
'display — Account display name
'totalDebit — Total debit amount
'totalCredit — Total credit amount
'balanceAtDateDebit — Positive balance as of the filter date
'balanceAtDateCredit — Negative balance as of the filter date
'dateFilter — The date filter applied

Example: Get account balances as of a specific date

The 'dateFilter field accepts date strings. Use odata-date to ensure correct formatting:

(trial-balance-list
#:query (make-query #:filter (eq 'dateFilter (odata-date "2024-12-31"))))

procedure
(trial-balance-get id) → hash?
id : string?

Returns the trial balance entry for a specific account.

12.4.3 General Ledger Entries🔗

value
general-ledger-entry : bc-entity?

Entity descriptor for BC general ledger entries. Use with inspect, peek, and sample.

G/L entries are read-only and represent posted transactions.

procedure
(general-ledger-entry-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all general ledger entries as a bc-result.

Key fields:

'entryNumber — Sequential entry number
'postingDate — Date the entry was posted
'documentNumber — Source document number
'documentType — Type of source document (Invoice, Payment, etc.)
'accountId / 'accountNumber — Related G/L account
'debitAmount / 'creditAmount — Entry amounts
'description — Entry description

Example: Get entries for a specific account up to a date

The 'postingDate field is an Edm.Date, so use odata-date:

(general-ledger-entry-list
  #:query (make-query
            #:filter (and: (eq 'accountNumber "1000")
                           (le 'postingDate (odata-date "2024-12-31")))
            #:select '(postingDate debitAmount creditAmount description)))

For a date range, use the date-between convenience function:

(general-ledger-entry-list
  #:query (make-query
            #:filter (and: (eq 'accountNumber "1000")
                           (date-between 'postingDate "2024-01-01" "2024-12-31"))))

procedure
(general-ledger-entry-get id) → hash?
id : string?

Returns the general ledger entry with the given id.

12.4.4 Journals🔗

value
journal : bc-entity?

Entity descriptor for BC journals. Use with inspect, peek, and sample.

Journals are containers for journal lines that can be posted to create G/L entries.

procedure
(journal-list [#:query q]) → bc-result?
q : odata-query/c = #f

Returns all journals as a bc-result.

Key fields: 'code, 'displayName, 'balancingAccountId, 'balancingAccountNumber.

Navigation property: 'journalLines can be expanded to include lines.

procedure
(journal-get id) → hash?
id : string?

Returns the journal with the given id.

procedure
(journal-create data) → hash?
data : hash?

Creates a new journal.

Required fields: 'code, 'displayName.

procedure
(journal-update id data [#:etag etag]) → hash?
  id : string?
  data : hash?
  etag : (or/c #f string?) = #f

Updates a journal.

procedure
(journal-delete id [#:etag etag]) → void?
id : string?
etag : (or/c #f string?) = #f

Deletes a journal. The journal must be empty (no journal lines).

12.5 Custom API Framework🔗

(require bcnav/api/custom)

package: bcnav-lib

Macros for defining access to custom and publisher APIs.

struct
(struct custom-api-info (publisher group version)
    #:extra-constructor-name make-custom-api-info)
  publisher : string?
  group : string?
  version : string?

Stores connection information for a custom or publisher API. Created by define-custom-api.

syntax
(define-custom-api name publisher group version)

Defines name as a custom-api-info struct holding the API coordinates.

publisher — The API publisher (e.g., "microsoft", "contoso")
group — The API group name
version — The API version (e.g., "v1.0")

(define-custom-api contoso-api "contoso" "inventory" "v1.0")

syntax
(define-entity name entity-name)
(define-entity name api-info entity-name)

Defines an entity struct value and CRUD functions.

Two forms:

2-argument form: Uses the standard BC v2.0 API. The entity-name is a string literal naming the BC entity (e.g., "taxGroups").
3-argument form: Uses a custom/publisher API. The api-info is a custom-api-info created by define-custom-api.

Creates six bindings:

name — A bc-entity struct for use with inspect, peek, and sample
name-list — List records with optional #:query
name-get — Get one record by ID
name-create — Create a record
name-update — Update a record (supports #:etag)
name-delete — Delete a record (supports #:etag)

Use entity-out to provide these bindings from your module.

Note: Entity names are not validated at definition time. If you use an entity name that doesn’t exist in BC, you’ll get an HTTP error when you make a request.

;; Standard API (2-arg form)
(define-entity tax-group "taxGroups")
(provide (entity-out tax-group))
;; Provides: tax-group, tax-group-list, tax-group-get, tax-group-create, ...

;; Custom API (3-arg form)
(define-custom-api contoso-api "contoso" "inventory" "v1.0")
(define-entity widget contoso-api "widgets")
(provide (entity-out widget))

syntax
(define-entity/read-only name entity-name)
(define-entity/read-only name api-info entity-name)

Like define-entity, but only creates the entity struct and read functions (name, name-list, name-get).

Use this for entities that don’t support create, update, or delete operations. When used with entity-out, only the read bindings are provided.

(define-entity/read-only account "accounts")
(provide (entity-out account))
;; Provides: account, account-list, account-get

syntax
(entity-out name)

A provide transformer (like struct-out) that exports all bindings associated with an entity defined via define-entity or define-entity/read-only.

For full CRUD entities, provides: name, name-list, name-get, name-create, name-update, name-delete.

For read-only entities, provides: name, name-list, name-get.

(define-entity customers "customers")
(define-entity/read-only account "accounts")

(provide (entity-out customers) ;; 6 bindings
(entity-out account)) ;; 3 bindings

12.6 Entity Function Patterns🔗

All entity functions follow consistent patterns:

12.6.1 List functions🔗

(name-list #:query q) ;; -> bc-result?

Returns a bc-result containing all matching records. Use for to iterate directly, or bc-result->list to convert to a list. Each record is a hash table with symbol keys corresponding to entity fields. The special key 'odata.etag contains the record’s ETag.

See Result Wrapper for the full bc-result API.

12.6.2 Get functions🔗

(name-get id) ;; -> hash?

Returns a single hash table. Raises exn:fail:bcnav:http with status 404 if not found.

12.6.3 Create functions🔗

(name-create data) ;; -> hash?

Takes a hash table of field values. Returns the created record with server-generated fields.

12.6.4 Update functions🔗

(name-update id data #:etag etag) ;; -> hash?

Takes an ID, a hash of fields to change, and an optional ETag. Returns the updated record.

12.6.5 Delete functions🔗

(name-delete id #:etag etag) ;; -> void?

Takes an ID and an optional ETag. Returns (void) on success.

contents ← prev up next →

1	Introduction
2	Quick Tour
3	Setup & Authentication
4	Querying with OData
5	Working with Entities
6	Metadata Discovery
7	Custom APIs
8	Logging & Debugging
9	Response Caching
10	Core Module Reference
11	OData Query Reference
12	Entity API Reference
13	Metadata Discovery Reference
14	Appendix: Security

12.1	Master Data
12.2	Sales
12.3	Purchasing
12.4	Finance
12.5	Custom API Framework
12.6	Entity Function Patterns