EaglesNest

Overview

EaglesNest is an ASP.NET Core Web API that acts as a secure gateway between CargoWise (or any eAdapter-compatible sender) and downstream systems. It provides:

• Certificate-based OAuth 2.0 — RS256 client assertions, Microsoft Entra ID tokens
• XML receive & routing — validates, saves, and forwards XML to FTP destinations
• Message filter gate — per-sender allow/block via tblMessageConfig
• Stockwell financial reports — AP/AR invoices and trial balance from Odyssey SQL
• User management — local accounts with salted password hashing and session tokens

Prerequisites

Base URL & Common Headers

https://localhost:7196   # Development
https://your-server/api  # Production

Common Request Headers

Error Responses

All endpoints return a consistent JSON envelope:

{
  "success": false,
  "message": "Unauthorized",
  "reason":  "Token expired at 2025-04-10 12:00:00Z. Request a new token.",
  "hint":    "Obtain a valid token via POST /api/auth/token or from Microsoft Entra ID.",
  "errors":  []
}

Option A — Swagger UI (Interactive)

Best for exploring the API during development.

Option B — Postman / Client Credentials

Best for testing with Postman or any HTTP client using a client secret.

POST https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={your-client-id}
&client_secret={your-client-secret}
&scope=api://ef770885-965b-4152-90c8-ddb4e78110d6/.default

Use the returned access_token as Authorization: Bearer {token}.

Option C — Certificate M2M (CargoWise / Production)

Automated service-to-service flow using RS256 certificate-based client assertions.

{
  "clientName":   "My CargoWise App",
  "azureClientId": "your-azure-app-client-id"
}

{
  "certificatePem": "-----BEGIN CERTIFICATE-----\n...",
  "privateKeyPem":  "-----BEGIN RSA PRIVATE KEY-----\n..."
}

{
  "certificatePem":  "-----BEGIN CERTIFICATE-----\n...",
  "clientAssertion": "eyJhbGciOiJS..."
}

Option D — Basic Authentication

Use Basic Auth when your client cannot obtain a Microsoft Entra ID token. Credentials are validated against the local tblUsers table. The scheme is auto-selected by the API when the Authorization header starts with Basic.

How it works

1. Create a local user via POST /api/user (or use an existing account).
2. Base64-encode username:password.
3. Pass the result in the Authorization header on every request.

Header format

Authorization: Basic {base64(username:password)}

Encoding example

Generate the Base64 value

Use any of the following:

# PowerShell
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("john.doe:P@ssw0rd!"))

# Linux / macOS
echo -n "john.doe:P@ssw0rd!" | base64

# Online
# https://www.base64encode.org/

Full request example

POST /api/cargowisedata/receive HTTP/1.1
Authorization: Basic am9obi5kb2U6UEBzc3cwcmQh
Content-Type: application/xml
eAdaptor-RecipientID: MYRECIPIENT
eAdaptor-EDIClientName: CargoWiseClient

<?xml version="1.0"?>
<UniversalShipment>...</UniversalShipment>

Validation logic

The BasicAuthenticationService performs the following checks on every request:

1. Authorization header present and scheme is Basic
2. Header value is valid Base64 with exactly one : separator
3. Username found in tblUsers
4. Password matches: SHA-256(salt + password) equals stored hash
5. Account Status = true (active)

Switching between Basic and Bearer

The API uses a dynamic scheme selector — you can mix Basic and Bearer in the same deployment. The scheme is chosen automatically based on the Authorization header prefix:

Create a user (prerequisite)

POST /api/user
Content-Type: application/json

{
  "username": "john.doe",
  "password": "P@ssw0rd!"
}

Common errors

Message Configuration Setup

Every sender (eAdaptor-EDIClientName + eAdaptor-RecipientID pair) must be registered in tblMessageConfig before XML can be received. The message filter controls whether routed delivery to FTP is enabled.

{
  "ediClientName": "CargoWiseClient",
  "recipientId":   "MYRECIPIENT",
  "procedureId":   1,
  "status":        true,
  "enableRouting": true
}

{
  "type":     "FTP",
  "uri":      "ftp://ftp.example.com/incoming/cargowise/",
  "username": "ftpuser",
  "password": "P@ssw0rd",
  "senderId": "SYD"
}

{ "routingEnabled": false }

Receiving CargoWise XML

Endpoint: POST /api/cargowisedata/receive

Required Headers

Authorization: Bearer {access_token}
Content-Type: application/xml
eAdaptor-RecipientID: MYRECIPIENT
eAdaptor-EDIClientName: CargoWiseClient
traceparent: 4bf92f3577b34da6a3ce929d0e0e4736   (optional)

Body

<?xml version="1.0" encoding="utf-8"?>
<UniversalShipment xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
  <Shipment>...</Shipment>
</UniversalShipment>

Validation Pipeline (in order)

1. Required headers present (eAdaptor-RecipientID, eAdaptor-EDIClientName)
2. Message filter gate — sender must be registered and active in tblMessageConfig
3. Content-Type is application/xml or text/xml
4. Payload size within configured limit (default 10 MB)
5. Well-formed XML document
6. Root element in allowed list (if configured)

On Success

• XML saved to C:\eAdapterNext\XmlFolder\{RecipientID}\{EdiClientName}\{timestamp}_{traceId}.xml
• If routing is enabled → file uploaded to all configured FTP routes (background, non-blocking)
• Per-route delivery counter incremented in tblMessageCount
• Per-client log entry written to C:\eAdapterNext\Logs\{RecipientID}\{EdiClientName}\

Success Response

{
  "success": true,
  "message": "XML received, validated and saved successfully.",
  "data": {
    "traceParent":   "4bf92f3577b34da6a3ce929d0e0e4736",
    "recipientId":   "MYRECIPIENT",
    "ediClientName": "CargoWiseClient",
    "receivedAt":    "2025-04-10T03:00:00Z",
    "rootElement":   "UniversalShipment",
    "elementCount":  1,
    "callerAppId":   "ef770885-965b-4152-90c8-ddb4e78110d6",
    "callerName":    "CargoWise Integration",
    "savedFileName": "20250410030000000_-_CargoWiseClient_-_MYRECIPIENT_4bf92f35.xml"
  }
}

Sending XML to CargoWise

Endpoint: POST /api/cargowisedata/send

Authenticates via Basic Auth. The authenticated username is used as the partitionKey — no route parameter required. The API fetches a Bearer token from eAdapterNext.Token using the username, then forwards the raw XML body to the CargoWise eAdaptorNext endpoint. An admin alert email is sent automatically (throttled — 1 per username per hour) for any of these failures: no Azure Table record for the username, CargoWise returning a non-2xx response, or a network/unexpected error.

Flow

POST /api/cargowisedata/send
Authorization: Basic {base64(username:password)}
Content-Type: application/xml

<?xml version="1.0" encoding="utf-8"?>
<UniversalTransaction xmlns="http://www.cargowise.com/Schemas/Universal/2011/11">
  <Header>
    <SenderID>SIPSYD</SenderID>
    ...
  </Header>
</UniversalTransaction>

var senderId = username[..6];  // e.g. "SIPSYD" from "SIPSYDclient"

https://{senderId}services.wisegrid.net/eAdaptorNext

POST {TokenApiBaseUrl}/api/token
Content-Type: application/json

{ "partitionKey": "{username}" }

POST https://{senderId}services.wisegrid.net/eAdaptorNext
Authorization: Bearer {token}
Content-Type: application/xml

<!-- original XML body -->

Success Response

{
  "success": true,
  "message": "XML forwarded to CargoWise — HTTP 200.",
  "data": {
    "traceParent":  "a3f1c2d4e5b6...",
    "sentAt":       "2025-04-20T06:30:00Z",
    "cwStatusCode": 200,
    "cwResponse":   "<!-- CargoWise response body -->",
    "tokenSource":  "Cached",
    "targetUrl":    "https://SIPSYDservices.wisegrid.net/eAdaptorNext"
  }
}

Error cases

FTP Routing Detail

URI Formats Accepted

ftp://ftp.example.com/incoming/cargowise/
ftps://secure.example.com/drop/
ftp.example.com/incoming/          (ftp:// assumed)
ftp.example.com                    (uploads to root)

Behaviour

• Passive mode (PASV) — works through NAT and most firewalls
• Auto-upgrades to FTPS if the server advertises AUTH TLS
• Remote directories are created automatically if missing
• All routes for a config are dispatched concurrently
• Each successful delivery increments tblMessageCount for that route

Log Locations

Stockwell — AP/AR Invoice Report

GET /api/stockwell/AP?token={your-token}

Returns all open (unpaid) AP and AR invoices from the Odyssey AccTransactionHeader table.

Authentication

Pass the API token as a query parameter:

GET /api/stockwell/AP?token=eyJhbGci...

Token validation can be disabled by setting eAdapterSettings:activatedstokwelltoken = false.

Response Fields

Stockwell — Trial Balance

GET /api/stockwell/trialbalance?token={your-token}

Returns period-level GL movements from cvw_ProfitandLossMovement, grouped by account, period, branch, and department.

Response Fields

User Management

Local user accounts with salted SHA-256 password hashing and session tokens (stored in tblUsers).

Create a user

POST /api/user
Content-Type: application/json

{
  "username": "john.doe",
  "password": "P@ssw0rd!"
}

Login

POST /api/user/login
Content-Type: application/json

{
  "username": "john.doe",
  "password": "P@ssw0rd!"
}

{
  "success": true,
  "data": {
    "user": { "userId": "...", "username": "john.doe", "status": true },
    "token":        "base64-session-token",
    "refreshToken": "base64-refresh-token"
  }
}

Refresh token

POST /api/user/refresh
{ "refreshToken": "base64-refresh-token" }

Logout

POST /api/user/logout
{ "token": "base64-session-token" }

Full Endpoint Reference

Auth

CargoWise Data

Message Configuration

Stockwell Reports

User Management