ExtensivSharp 1.4.0

ExtensivSharp

A C# client library for the Extensiv (formerly 3PL Central) Warehouse Management System REST API.

Features

• OAuth authentication with Extensiv's auth server
• Strongly-typed request/response models
• Fluent RQL (Resource Query Language) query builder
• Full outbound surface: picking, movable units, allocation, load-out, packing and shipping
• Orders, inventory, items, receivers and facility properties
• Built for dependency injection with IHttpClientFactory

Requirements

• .NET 10.0 or later
• Extensiv API credentials (API key and user login)

Installation

dotnet add package ExtensivSharp

Dependencies

• Microsoft.Extensions.Http (v9.0.0)
• Newtonsoft.Json (v13.0.3)

Quick Start

Authentication

using ExtensivSharp.Services;
using ExtensivSharp.Models.Auth;

var authRequest = new ExtensivAuthRequest
{
    Key = "your-base64-encoded-api-key",
    UserId = "your-user-login"
};

var authResponse = await AuthenticationService.GetAuthenticationKey(authRequest);
string token = authResponse.AccessToken;

Fetching Orders

using ExtensivSharp.Endpoints.Orders;

var getOrders = new GET_Orders
{
    AuthorizationToken = token,
    PageSize = 50,
    PageNumber = 1,
    Detail = SpecifyDetailType.All
};

var result = await getOrders.GetAsync(httpClientFactory);

if (result.Success)
{
    foreach (var order in result.Data.ResourceList)
    {
        Console.WriteLine($"Order: {order.ReferenceNum}");
    }
}

Using the RQL Query Builder

The library includes a fluent query builder for Extensiv's Resource Query Language:

using ExtensivSharp.RQL;

var query = new RqlQueryBuilder()
    .Where("Status", "==", "Open")
    .Where("CreationDate", ">=", "2024-01-01")
    .In("Facility", "WH1", "WH2", "WH3")
    .HasValue("ShipDate", false)
    .Build();

var getOrders = new GET_Orders
{
    AuthorizationToken = token,
    RqlFilter = query
};

Available RQL Methods:

• Where(field, operator, value) - Add an AND condition
• Or(field, operator, value) - Add an OR condition
• In(field, values...) - Match any of the provided values
• NotIn(field, values...) - Exclude the provided values
• HasValue(field, bool) - Check if field has/doesn't have a value

Available Endpoints

Orders

Picking

Movable Units

Movable unit contents come from GET_StockDetails, not from these. The pallet rels return metadata only.

Inventory

Packing and Shipping

Items

Properties

Picking a Whole Movable Unit

Extensiv has no bulk pick endpoint. POST /orders/pickjobs/{jid}/pickitems/picker takes exactly one pickItemId, requires If-Match, and returns the entire updated pick list with a new ETag. So picks cannot be issued in parallel - they have to be chained.

What makes movable-unit picking possible anyway is that pick lists are consolidated by Location + ItemTraits, and ItemTraits carries the movable unit. For serialized inventory that means one pick line per serial, each tagged with the unit it sits on:

// 1. Read the unit's contents and allocate the whole thing in one request.
var stock = await new GET_StockDetails
{
    AuthorizationToken = token,
    CustomerId = customerId,
    FacilityId = facilityId,
    PageSize = 500,
    RqlFilter = $"palletidentifier.namekey.name=={scannedLabel}"
}.GetAsync(factory);

// 2. Create and start the pick job, then read the pick list for its ETag.
var list = await new GET_PickList { AuthorizationToken = token, PickJobId = jobId }.GetAsync(factory);

// 3. Filter to the scanned unit and chain the picks, threading the ETag through.
var etag = list.Etag;
var lines = list.Data.Items
    .Where(i => i.PickItem?.ItemTraits?.PalletIdentifier?.NameKey?.Name == scannedLabel)
    .Where(i => i.PickItem!.PickedQty < i.PickItem.Qty);

foreach (var line in lines)
{
    var pick = await new POST_Pick
    {
        AuthorizationToken = token,
        PickJobId = jobId,
        IsMatch = etag,
        PickInfo = new PickInfo { PickItemId = line.PickItemId, Qty = line.PickItem!.Qty }
    }.PostAsync(factory);

    if (!pick.Success)
    {
        // 412 means the ETag went stale because something else touched the job.
        // Re-read the pick list and resume from the lines still short of their quantity.
        break;
    }

    etag = pick.Etag;
}

This library deliberately does not wrap that loop. Partial failure mid-run is a real physical state - the operator is holding a half-picked unit - and how to recover is an application decision.

Project Structure

ExtensivSharp/
├── Endpoints/
│   ├── Orders/        # Orders, picking, packing and shipping
│   ├── Inventory/     # Inventory, receivers and movable units
│   ├── Items/         # Item master
│   └── Properties/    # Facilities, locations, carriers, movable unit types
├── Models/
│   ├── Auth/          # Authentication models
│   ├── Order/         # Order, package and allocation models
│   ├── Pick/          # Pick job, pick list and pick action models
│   ├── Inventory/     # Inventory, stock detail and pallet models
│   ├── Items/         # Item models
│   ├── Receivers/     # Receiver models
│   ├── Properties/    # Facility, location and pallet type models
│   ├── Generic/       # Shared identifiers, ItemTraits, allocations
│   ├── Helper/        # API result wrapper
│   └── Webhooks/      # Webhook payload models
├── RQL/
│   └── RqlQueryBuilder.cs  # Fluent RQL query builder
└── Services/
    └── AuthenticationService.cs  # OAuth token generation

Response Handling

All endpoint methods return an ExtensivApiResult<T> wrapper:

public class ExtensivApiResult<T>
{
    public bool Success { get; set; }
    public HttpStatusCode StatusCode { get; set; }
    public string? Message { get; set; }
    public string? Etag { get; set; }
    public T Data { get; set; } = default!;
}

On failure, Message carries the raw response body from Extensiv - which for a 400 or 403 is a typed error envelope with ErrorCode and Hint - falling back to the HTTP reason phrase when the body is empty. StatusCode carries the semantics. The codes worth handling explicitly:

Every endpoint that receives an ETag returns it on Etag, including the ones whose response body is empty, so a chain of mutations never has to re-read a resource just to get a fresh tag.

Breaking Changes in 1.4.0

• HttpStatusCodeHelper has been removed. It mapped statuses to canned English strings and discarded Extensiv's own error payload on exactly the codes that matter. Message now carries the response body verbatim.
• Package.PackageContents is now projected onto a _embedded wrapper rather than being a wire property. Extensiv carries package contents under _embedded on both requests and responses, so the old mapping never bound. Reading and setting PackageContents still works.
• PackageContent.Qty is now decimal rather than double, matching the API specification.
• Models.Order.NameKey and Models.Inventory.NameKey have been removed in favour of Models.Generic.NameKey; all three were identical.
• Models.Inventory.PalletIdentifier has moved to Models.Generic.PalletIdentifier.
• RqlQueryBuilder.Build() now returns a raw RQL expression. It previously URL-encoded values a second time on top of the RQL-level escaping, which double-encoded any value containing %, !, parentheses, *, =, , or ;. Callers URL-encode the built expression exactly once.

API Documentation

For full API documentation, refer to the Extensiv API Reference or REL documentation

License

MIT License

Last Modified: 2026-08-18