agmission/Development/server/docs/SATLOC_API_SPECIFICATION.md

SatLoc Partner Integration API Specification

Overview

This document specifies the integration between AgMission and SatLoc Cloud services using a dual-user system:

1. Partner Users: Organizations like SatLoc that provide services
2. Partner System Users: Customer/applicator accounts within each partner system

Architecture

User Model Structure

// Partner Organization (e.g., SatLoc company)
const Partner = User.discriminator('PARTNER', {
  partnerCode: 'SATLOC',
  partnerName: 'SatLoc Cloud',
  configuration: { /* partner-specific settings */ }
});

// Customer account in SatLoc system
const PartnerSystemUser = User.discriminator('PARTNER_SYSTEM_USER', {
  partner: ObjectId,          // Reference to Partner
  customer: ObjectId,         // AgMission customer  
  partnerUserId: String,      // SatLoc user ID
  companyId: String,          // SatLoc company ID
  apiKey: String,             // Customer's SatLoc API key
  // ... additional SatLoc-specific fields
});

Environment Configuration

Partner system settings are managed via environment variables:

# SatLoc Configuration
SATLOC_API_ENDPOINT=https://www.satloccloud.com/api/Satloc
SATLOC_API_KEY=default_api_key
SATLOC_API_SECRET=default_api_secret
SATLOC_API_TIMEOUT=30000
SATLOC_RETRY_ATTEMPTS=3
SATLOC_RATE_LIMIT=60

SatLoc Cloud API Endpoints

Authenticate API User

GET /api/Satloc/AuthenticateAPIUser?userLogin={userLogin}&password={password}

Example:

GET /api/Satloc/AuthenticateAPIUser?userLogin=vendor%40myk.com&password=Home4663%23

Response:

{
  "userId": "a2991888-5c7f-4101-8e0d-0a390c26720c",
  "companyId": "36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff",
  "email": "vendor@myk.com"
}

2. Health Check

Is Alive Check

GET /api/Satloc/IsAlive

Response:

true

3. Aircraft Management

Get Aircraft List

GET /api/Satloc/GetAircraftList?userId={userId}&companyId={companyId}

Example:

GET /api/Satloc/GetAircraftList?userId=a2991888-5c7f-4101-8e0d-0a390c26720c&companyId=36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff

Response:

[
  {
    "id": "23bee7aa-c949-4089-854a-2ab58b40294f",
    "tailNumber": "MYK AIR01"
  },
  {
    "id": "ced67805-41c8-4dc7-b8fd-7bcabc0ce6c4",
    "tailNumber": "MYK AIR03"
  },
  {
    "id": "b2ae08d8-6ff5-43d4-9fe1-a8f91dbcb0fb",
    "tailNumber": "AIR 02"
  }
]

4. Flight Logs

Get Aircraft Logs

GET /api/Satloc/GetAircraftLogs?userId={userId}&aircraftId={aircraftId}

Example:

GET /api/Satloc/GetAircraftLogs?userId=a2991888-5c7f-4101-8e0d-0a390c26720c&aircraftId=23bee7aa-c949-4089-854a-2ab58b40294f

Response:

[
  {
    "id": "d4bbbebf-ea9d-44af-a901-aab9f81bc841",
    "logFileName": "Liquid_NAAA_200.log",
    "uploadedDate": "2020-07-04T15:59:54.577"
  },
  {
    "id": "f425cea7-1644-48ef-9fbf-b2c9642c6cbe",
    "logFileName": "Liquid_NAAA_800.log",
    "uploadedDate": "2020-07-04T15:56:19.167"
  },
  {
    "id": "2e38fc84-431c-4473-a6c0-e0a24a3ab07a",
    "logFileName": "Liquid_NAAA_150.log",
    "uploadedDate": "2020-07-04T15:53:53.74"
  }
]

Get Aircraft Log Data

GET /api/Satloc/GetAircraftLogData?userId={userId}&logId={logId}

Example:

GET /api/Satloc/GetAircraftLogData?userId=a2991888-5c7f-4101-8e0d-0a390c26720c&logId=d4bbbebf-ea9d-44af-a901-aab9f81bc841

Response:

{
  "id": "d4bbbebf-ea9d-44af-a901-aab9f81bc841",
  "logFile": "QVM0LjAxL0FUVCAzLjE5LjExOC4xNjI1ICAgICBI~",
  "logFileName": "Liquid_NAAA_200.log"
}

Note: The logFile field contains base64-encoded binary data that should be decoded to access the actual log file content.

5. Job Upload

Upload Job Data

POST /api/Satloc/UploadJobData

Request Body Structure:

{
  "CompanyId": "36c0f342-e4e2-4fcb-b219-9cd1fad2c1ff",
  "UserId": "a2991888-5c7f-4101-8e0d-0a390c26720c",
  "JobDataList": [
    {
      "AircraftId": "23bee7aa-c949-4089-854a-2ab58b40294f",
      "JobName": "Binary.PMD",
      "Notes": null,
      "JobData": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA~",
      "Overwrite": true,
      "Id": "275e3dba-1a06-4bc2-bd3c-f06f65fdcaa5",
      "LastModified": "2020-07-07T14:51:01.4147813-05:00",
      "LastModifiedBy": "Bay",
      "CreatedDate": "2020-07-07T14:51:01.4307691-05:00",
      "CreatedBy": "Bay"
    }
  ]
}

Fields Explanation:

• CompanyId: Company identifier from authentication
• UserId: User identifier from authentication
• JobDataList: Array of job data objects
  • AircraftId: Target aircraft ID (maps to partnerAircraftId in AgMission)
  • JobName: Job file name
  • Notes: Optional notes for the job
  • JobData: Base64-encoded job file content
  • Overwrite: Whether to overwrite existing job (default: false)
  • Id: Unique job identifier
  • Audit fields: LastModified, LastModifiedBy, CreatedDate, CreatedBy