texasstarbc

API Documentation

This document describes the REST API query objects exposed by the Texas Star Nuts extension for external system integration.

Overview

The extension includes 54 API query objects that expose Business Central data via OData REST APIs. These APIs enable:

All APIs follow OData v4 protocol and support standard operations:

API Categories

1. Master Data APIs

2. Transaction APIs

3. Inventory APIs

4. Production APIs

5. Ledger APIs

Master Data APIs

TSN API Items (Query 50000)

Endpoint: /api/v1/tsnApiItems

Purpose: Retrieve item master data with Texas Star custom fields

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiItems?$filter=TSN_Brand_Code eq 'PRIVATE'&$select=No,Description,Unit_Price

Code Reference: TSNAPIItems.Query.al

TSN API Customers (Query 50001)

Endpoint: /api/v1/tsnApiCustomers

Purpose: Retrieve customer master data

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiCustomers?$filter=Balance gt 0

Code Reference: TSNAPICustomers.Query.al

TSN API Vendors (Query 50002)

Endpoint: /api/v1/tsnApiVendors

Purpose: Retrieve vendor/supplier master data

Key Fields:

Use Cases:

Code Reference: TSNAPIVendors.Query.al

TSN API Locations (Query 50003)

Endpoint: /api/v1/tsnApiLocations

Purpose: Retrieve warehouse location data

Key Fields:

Use Cases:

Code Reference: TSNAPILocations.Query.al

TSN API Bins (Query 50004)

Endpoint: /api/v1/tsnApiBins

Purpose: Retrieve bin/location detail data

Key Fields:

Use Cases:

Code Reference: TSNAPIBins.Query.al

Transaction APIs

TSN API Sales Headers (Query 50010)

Endpoint: /api/v1/tsnApiSalesHeaders

Purpose: Retrieve sales order headers

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiSalesHeaders?$filter=Status eq 'Released' and Shipment_Date eq 2026-01-13

Code Reference: TSNAPISalesHeaders.Query.al

TSN API Sales Lines (Query 50011)

Endpoint: /api/v1/tsnApiSalesLines

Purpose: Retrieve sales order line details

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiSalesLines?$filter=Document_No eq 'SO-12345'&$expand=Item

Code Reference: TSNAPISalesLines.Query.al

TSN API Purchase Headers (Query 50012)

Endpoint: /api/v1/tsnApiPurchaseHeaders

Purpose: Retrieve purchase order headers

Key Fields:

Use Cases:

Code Reference: TSNAPIPurchaseHeaders.Query.al

TSN API Purchase Lines (Query 50013)

Endpoint: /api/v1/tsnApiPurchaseLines

Purpose: Retrieve purchase order line details

Key Fields:

Use Cases:

Code Reference: TSNAPIPurchaseLines.Query.al

TSN API Transfer Orders (Query 50014)

Endpoint: /api/v1/tsnApiTransferOrders

Purpose: Retrieve inter-location transfer orders

Key Fields:

Use Cases:

Code Reference: TSNAPITransferOrders.Query.al

Warehouse APIs

TSN API Warehouse Shipment Headers (Query 50020)

Endpoint: /api/v1/tsnApiWarehouseShipmentHeaders

Purpose: Retrieve warehouse shipment documents

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiWarehouseShipmentHeaders?$filter=Shipment_Date eq 2026-01-13&$select=No,Bill_of_Lading_No,Seal_No

Code Reference: TSNAPIWarehouseShipmentHeaders.Query.al

TSN API Warehouse Shipment Lines (Query 50021)

Endpoint: /api/v1/tsnApiWarehouseShipmentLines

Purpose: Retrieve warehouse shipment line details

Key Fields:

Use Cases:

Code Reference: TSNAPIWarehouseShipmentLines.Query.al

TSN API Warehouse Receipt Headers (Query 50022)

Endpoint: /api/v1/tsnApiWarehouseReceiptHeaders

Purpose: Retrieve warehouse receipt documents

Key Fields:

Use Cases:

Code Reference: TSNAPIWarehouseReceiptHeaders.Query.al

TSN API Warehouse Receipt Lines (Query 50023)

Endpoint: /api/v1/tsnApiWarehouseReceiptLines

Purpose: Retrieve warehouse receipt line details

Key Fields:

Use Cases:

Code Reference: TSNAPIWarehouseReceiptLines.Query.al

Inventory APIs

TSN API Bin Content (Query 50030)

Endpoint: /api/v1/tsnApiBinContent

Purpose: Real-time inventory by bin and lot

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiBinContent?$filter=Location_Code eq 'MAIN' and Item_No eq 'NUT-001'

Code Reference: TSNAPIBinContent.Query.al

TSN API Item Ledger Entries (Query 50031)

Endpoint: /api/v1/tsnApiItemLedgerEntries

Purpose: Item transaction history

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiItemLedgerEntries?$filter=Item_No eq 'NUT-001' and Lot_No eq 'LOT-12345'

Code Reference: TSNAPIItemLedgerEntries.Query.al

TSN API Warehouse Entries (Query 50032)

Endpoint: /api/v1/tsnApiWarehouseEntries

Purpose: Warehouse movement transaction history

Key Fields:

Use Cases:

Code Reference: TSNAPIWarehouseEntries.Query.al

TSN API Lot No. Information (Query 50033)

Endpoint: /api/v1/tsnApiLotNoInformation

Purpose: Lot master data with expiration and traceability

Key Fields:

Use Cases:

Example Request:

GET /api/v1/tsnApiLotNoInformation?$filter=Expiration_Date lt 2026-02-01

Code Reference: TSNAPILotNoInformation.Query.al

Production APIs

TSN API Production Orders (Query 50040)

Endpoint: /api/v1/tsnApiProductionOrders

Purpose: Manufacturing order headers

Key Fields:

Use Cases:

Code Reference: TSNAPIProductionOrders.Query.al

TSN API Prod Order Components (Query 50041)

Endpoint: /api/v1/tsnApiProdOrderComponents

Purpose: Manufacturing order component/material requirements

Key Fields:

Use Cases:

Code Reference: TSNAPIProdOrderComponents.Query.al

TSN API Prod Order Routing Lines (Query 50042)

Endpoint: /api/v1/tsnApiProdOrderRoutingLines

Purpose: Manufacturing routing steps/operations

Key Fields:

Use Cases:

Code Reference: TSNAPIProdOrderRoutingLines.Query.al

TSN API BOMs (Query 50043)

Endpoint: /api/v1/tsnApiBOMs

Purpose: Bill of Materials structure

Key Fields:

Use Cases:

Code Reference: TSNAPIBOMs.Query.al

TSN API Work Centers (Query 50044)

Endpoint: /api/v1/tsnApiWorkCenters

Purpose: Work center/production resource data

Key Fields:

Use Cases:

Code Reference: TSNAPIWorkCenters.Query.al

Ledger APIs

TSN API GL Entries (Query 50050)

Endpoint: /api/v1/tsnApiGLEntries

Purpose: General ledger transaction detail

Key Fields:

Use Cases:

Code Reference: TSNAPIGLEntries.Query.al

TSN API Capacity Ledger Entries (Query 50051)

Endpoint: /api/v1/tsnApiCapacityLedgerEntries

Purpose: Labor/machine time tracking entries

Key Fields:

Use Cases:

Code Reference: TSNAPICapacityLedgerEntries.Query.al

Authentication & Security

OAuth 2.0 Authentication

Business Central OData APIs use OAuth 2.0 for authentication:

  1. Register Application in Azure AD
  2. Grant Permissions to Business Central APIs
  3. Obtain Access Token using client credentials or authorization code flow
  4. Include Token in API requests

Example Authorization Header:

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

Permissions

API Usage Examples

Example 1: Get Today’s Shipments

Request:

GET /api/v1/tsnApiWarehouseShipmentHeaders?$filter=Shipment_Date eq 2026-01-13

Response:

{
  "value": [
    {
      "No": "SHIP-001",
      "Location_Code": "MAIN",
      "Shipment_Date": "2026-01-13",
      "Bill_of_Lading_No": "BOL-12345",
      "Seal_No": "SEAL-9876",
      "Trailer_Reference": "TRLR-5555",
      "Manual_Pallets": 5
    }
  ]
}

Example 2: Get Item Inventory by Location

Request:

GET /api/v1/tsnApiBinContent?$filter=Item_No eq 'NUT-ALMOND-1000' and Quantity gt 0&$select=Location_Code,Bin_Code,Lot_No,Quantity

Response:

{
  "value": [
    {
      "Location_Code": "MAIN",
      "Bin_Code": "A-01-01",
      "Lot_No": "PO-12345-10",
      "Quantity": 100
    },
    {
      "Location_Code": "MAIN",
      "Bin_Code": "A-01-02",
      "Lot_No": "PO-12345-20",
      "Quantity": 150
    }
  ]
}

Example 3: Get Lots Expiring Soon

Request:

GET /api/v1/tsnApiLotNoInformation?$filter=Expiration_Date le 2026-02-01 and Expiration_Date gt 2026-01-13&$orderby=Expiration_Date asc

Response:

{
  "value": [
    {
      "Item_No": "NUT-CASHEW-500",
      "Lot_No": "PO-11111-10",
      "Expiration_Date": "2026-01-20",
      "Alternate_Lot_No": "VENDOR-LOT-ABC",
      "Country_of_Origin": "VN"
    }
  ]
}

Example 4: Get Open Sales Orders by Customer

Request:

GET /api/v1/tsnApiSalesHeaders?$filter=Sell_to_Customer_No eq 'CUST-001' and Status eq 'Released'&$expand=Lines

Response:

{
  "value": [
    {
      "No": "SO-12345",
      "Sell_to_Customer_No": "CUST-001",
      "Sell_to_Customer_Name": "ABC Grocery",
      "Order_Date": "2026-01-10",
      "Shipment_Date": "2026-01-15",
      "Status": "Released",
      "Amount_Including_VAT": 5250.00,
      "Lines": [
        {
          "Line_No": 10000,
          "Item_No": "NUT-ALMOND-1000",
          "Description": "Almonds 1000g",
          "Quantity": 50,
          "Unit_Price": 10.00,
          "Amount": 500.00
        }
      ]
    }
  ]
}

Performance Considerations

Best Practices

  1. Use Filters: Always filter data to reduce payload size 
    ?$filter=Posting_Date ge 2026-01-01
  2. Select Specific Fields: Only retrieve fields you need 
    ?$select=No,Description,Quantity
  3. Pagination: Use $top and $skip for large datasets 
    ?$top=100&$skip=200
  4. Indexing: Filters on indexed fields perform better
    • Primary keys (No, Entry_No, etc.)
    • Posting dates
    • Status fields
  5. Caching: Cache master data (items, customers) locally
    • Reduces API calls
    • Improves response time
    • Use webhooks for change notifications (if available)

Rate Limiting

Error Handling

Common HTTP Status Codes

Code Meaning Action
200 Success Process response
400 Bad Request Check query syntax
401 Unauthorized Refresh access token
403 Forbidden Check permissions
404 Not Found Verify endpoint URL
429 Too Many Requests Implement retry with backoff
500 Server Error Log and retry

Error Response Example

{
  "error": {
    "code": "BadRequest",
    "message": "The query parameter $filter has an invalid value."
  }
}

Integration Scenarios

Scenario 1: eCommerce Inventory Sync

Flow:

  1. eCommerce system queries available inventory every 15 minutes
  2. GET /api/v1/tsnApiBinContent?$filter=Quantity gt 0
  3. Calculate ATP (Available to Promise) by item
  4. Update eCommerce inventory levels

Benefits:

Scenario 2: WMS Integration

Flow:

  1. WMS queries warehouse shipments due today
  2. GET /api/v1/tsnApiWarehouseShipmentHeaders?$filter=Shipment_Date eq {today}
  3. For each shipment, get lines with lots
  4. Generate pick lists in WMS
  5. Update pick status back to BC (via BC standard APIs)

Benefits:

Scenario 3: BI/Analytics Dashboard

Flow:

  1. Nightly ETL job extracts data
  2. GET item ledger entries for date range
  3. GET sales orders and lines
  4. GET production orders
  5. Load into data warehouse
  6. Build dashboards/reports

Benefits:

Scenario 4: Mobile Receiving App

Flow:

  1. Warehouse receiver scans PO barcode
  2. App queries: GET /api/v1/tsnApiPurchaseLines?$filter=Document_No eq {PO}
  3. Display expected items
  4. Receiver confirms quantities, enters lot/expiration
  5. App posts receipt via BC standard API

Benefits:

Summary

The API layer provides:

  1. Comprehensive Access: 54 query objects covering all major data areas
  2. Standard Protocol: OData v4 with full filtering, selection, expansion
  3. Real-Time Data: Direct queries to live BC database
  4. Secure: OAuth 2.0 with BC permission enforcement
  5. Integration Ready: Enables WMS, eCommerce, BI, mobile apps
  6. Custom Fields: Exposes TSN custom fields for specialized data

Key API Groups

See Also: