EcoRoute Core Engine Docs
◀ Return Home

#Introduction

Welcome to the EcoRoute Core Engine API. Our infrastructure enables enterprises to perform precise, real-time multi-modal logistics audits, carbon tax calculations, and compliance verification under global reporting standards.

Base URL
https://ecoroute.stims.co.za

All requests require a valid live bearer token and must be structured as valid JSON payloads over secure HTTPS channels.

curl -X POST '/api/v1/logistics/audit' \
  -H 'Authorization: Bearer ecoroute_live_...' \
  -H 'Content-Type: application/json'

#Authentication

EcoRoute APIs authenticate requests using secret bearer tokens. Pass your token via the Authorization HTTP header on every call.

Authorization: Bearer ecoroute_live_YOUR_SECRET_TOKEN

#Rate Limits

Corporate accounts are governed by monthly active request tiers. Exceeding your token quota results in a 429 Too Many Requests response envelope.

#Pagination

Large record listings and historical audit queries accept optional 'page' and 'limit' cursor query parameters. The response envelope includes comprehensive metadata regarding total pages and record counts.

GET /api/v1/logistics/history?page=2&limit=50
Example Response Payload
{
  "pagination": {
    "current_page": 2,
    "per_page": 50,
    "total_records": 1420,
    "total_pages": 29,
    "has_next": true
  }
}

#Errors

EcoRoute uses standard HTTP response status codes coupled with explicit internal error codes to identify operational failures.

Standard Error Codes Roster
400 BAD_REQUESTMalformed JSON string or invalid body structure sent in request payload.
401 UNAUTHORIZEDMissing, expired, or malformed Bearer authorization security token header.
403 FORBIDDENAuthenticated token lacks required organizational clearance for this calculation endpoint.
422 UNPROCESSABLE_ENTITYValidation fault; required physical fields (e.g. mass, distance, fuel type) are invalid or zero.
429 RATE_LIMIT_EXCEEDEDMonthly active corporate quota limit reached. Upgrade tier or wait for period reset.
500 INTERNAL_ENGINE_FAULTUnexpected compute exception inside the Stims multi-modal emission calculation pipeline.
Error Response Envelope Example
{
  "success": false,
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "status_code": 422,
    "message": "Field 'distance' must be a positive quantitative float value.",
    "timestamp": "2026-08-14T09:15:00.000Z"
  }
}

#Webhooks

Configure your `webhook_destination_url` in your dashboard to receive automated real-time HTTPS POST pushes when critical telemetry benchmarks occur.

Available Webhook Event Types
carbon_threshold_alertTriggered immediately when aggregate corporate monthly carbon emissions cross 85% of your configured sustainability budget cap.
tax_liability_updatedDispatched at midnight SAST whenever South Africa carbon tax liability calculations accrue or adjust based on verified transport logs.
batch_audit_completedFired upon completion of a large multi-modal batch array ingestion job, returning the compiled audit reference identification hash.
quota_exhaustion_warningSent when your monthly request quota is running low (95% consumed), preventing sudden data integration blind spots.
Webhook Event Dispatch Payload Example
{
  "event": "carbon_threshold_alert",
  "organization": "Enterprise Logistics Ltd",
  "timestamp": "2026-08-14T09:20:00.000Z",
  "payload": {
    "accrued_tax_zar": 14500.00,
    "threshold_limit_zar": 20000.00
  }
}

API Documentation Specifications Reference

Audit Calculator

Executes real-time multi-category emissions footprint audits with organization quota tracking and ledger verification across 5 distinct modality profiles.

HTTP Headers
Key
Type
Description
Content-Type
String
Set strictly to 'application/json'
Authorization
String
Bearer token signature block (e.g., 'Bearer ecoroute_live_...')
Parameters
Field
Required
Description
typeString
True
Category tier. Options: 'vehicle', 'flight', 'shipping', 'electricity', 'gas'.
reference_idString
Conditional
Required if save_log is true. Unique manifest key to block double logging.
vehicle_idString
Conditional
Required for land vehicles. String UUID matching an asset key from fleet registry.
distanceDecimal
Conditional
Required for vehicle and shipping. Positive decimal tracking value.
unitString
Conditional
Measurement unit parameter. Accepts 'km' or 'miles'.
origin_identifier / dest_identifierString
Conditional
Required for aviation flights. Numeric airport lookup keys.
passengersInteger
False
Flight occupants count tracking boundaries. Defaults to 1.
cargo_weight / mass_unitMixed
Conditional
Required for shipping freight. Mass unit accepts 'kg', 'lbs', or 'tonnes'.
energy_kwh / country_codeMixed
Conditional
Required for grid power. Electricity units paired with 2-char country ISO code.
gas_quantity / gas_type / gas_unitMixed
Conditional
Required for gas combustion. Gas type accepts 'NATURAL_GAS' or 'LPG'.
emission_dateString
False
Format YYYY-MM-DD. Future dates are blocked. Defaults to today.
save_logBoolean
False
Defaults to true. If false, calculates footprint but skips database write while still decrementing quota.
POST/api/v1/logistics/audit
Request Payloads / Query Structure
1. Land Vehicles
{
  "reference_id": "YOUR_UNIQUE_REF_001",
  "type": "vehicle",
  "vehicle_id": "YOUR_UUID",
  "distance": 124.5,
  "unit": "km",
  "emission_date": "2026-08-01",
  "save_log": true
}
2. Aviation Flights
{
  "reference_id": "YOUR_UNIQUE_REF_002",
  "type": "flight",
  "origin_identifier": "31055",
  "dest_identifier": "2775",
  "passengers": 7,
  "emission_date": "2026-08-05",
  "save_log": true
}
3. Cargo Freight Shipping
{
  "reference_id": "YOUR_UNIQUE_REF_003",
  "type": "shipping",
  "cargo_weight": 18500.0,
  "mass_unit": "kg",
  "distance": 840.2,
  "unit": "km",
  "emission_date": "2026-08-06",
  "save_log": true
}
4. Grid Power Electricity
{
  "reference_id": "YOUR_UNIQUE_REF_004",
  "type": "electricity",
  "energy_kwh": 4500.75,
  "country_code": "ZA",
  "emission_date": "2026-08-07",
  "save_log": true
}
5. Gas Fuel Combustion
{
  "reference_id": "YOUR_UNIQUE_REF_005",
  "type": "gas",
  "gas_quantity": 120.0,
  "gas_type": "LPG",
  "gas_unit": "kg",
  "emission_date": "2026-08-08",
  "save_log": true
}
Response Envelope (200 OK Example)
{
  "success": true,
  "status": "TRANSACTION_AUDIT_VERIFIED",
  "timestamp": "2026-08-08T01:45:00.000Z",
  "organization": "Your Enterprise Profile Name",
  "quota_requests_remaining": 99942,
  "metrics": {
    "carbon_kg": 230.20,
    "carbon_g": 230200,
    "carbon_mt": 0.2302,
    "carbon_lb": 507.5
  },
  "telemetry": {
    "userAssignedDate": "2026-08-08",
    "processedViaSecureTunnel": true
  },
  "record": {
    "id": "c7b508f2-11da-4bc3-9fae-cc9231f82110"
  }
}

Bulk Matrix Logger

Ingests and processes mixed parameter arrays of up to 50 concurrent items simultaneously. Applies conditional duplicate reference key filters.

HTTP Headers
Key
Type
Description
Content-Type
String
Set to 'application/json'
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
cost_centerString
False
Global corporate cost center grouping parameter fallback label.
batch_itemsArray
True
A collection array containing up to 50 separate tracking objects.
POST/api/v1/bulk-log
Request Payloads / Query Structure
Mixed Batch Request JSON
{
  "cost_center": "Durban-Main-Hub",
  "batch_items": [
    {
      "reference_id": "REF_9901_VEH",
      "type": "vehicle",
      "vehicle_id": "9cd3ed83-4d36-4fc8-857f-f19c0aaa2407",
      "distance": 124.5,
      "unit": "km",
      "save_log": true
    }
  ]
}
Response Envelope (200 OK Example)
{
  "success": true,
  "total_items_processed": 1,
  "total_items_saved": 1,
  "quota_requests_remaining": 2963,
  "results": [
    {
      "reference_id": "REF_9901_VEH",
      "type": "vehicle",
      "saved_to_ledger": true
    }
  ]
}

Route Checker

Pre-dispatch distance simulation using sequential coordinate paths list coordinates array mapped strictly in Google format.

HTTP Headers
Key
Type
Description
Content-Type
String
Set to 'application/json'
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
vehicle_idString
True
Registered database transport truck or delivery vehicle UUID string hash.
coordinates_stringArray
True
An array of 2 or more lat/lon coordinate strings matching standard Google format ['lat, lon'].
POST/api/v1/route-check
Request Payloads / Query Structure
Route Sequence Request payload
{
  "vehicle_id": "9cd3ed83-4d36-4fc8-857f-f19c0aaa2407",
  "coordinates_string": [
    "-25.966000, 28.233000",
    "-28.212325, 30.675712"
  ]
}
Response Envelope (200 OK Example)
{
  "success": true,
  "dispatch_status": "APPROVED_HAVERSINE_SEQUENCE_ROUTE",
  "route_projection": {
    "actual_distance_km": 482.6,
    "projected_fuel_litres": 55.50,
    "projected_carbon_kg": 111.000
  }
}

Carbon Tax Report

Compiles aggregated emissions data matrix lines to compute real-time statutory carbon tax exposure statement balances under SARS constants.

HTTP Headers
Key
Type
Description
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
start_dateString
False
Lower date limit calendar bounding filter (YYYY-MM-DD).
end_dateString
False
Upper date limit calendar bounding filter (YYYY-MM-DD).
GET/api/v1/tax-report
Request Payloads / Query Structure
Query Parameters Format
GET /api/v1/tax-report?start_date=2026-03-01&end_date=2026-05-31
Response Envelope (200 OK Example)
{
  "success": true,
  "organization": "Express Carrier Hub",
  "sars_tax_compliance_ledger": {
    "statutory_base_rate_zar_per_tonne": 159.00,
    "free_basic_allowance_exemption_percentage": "60%",
    "taxable_emissions_volume_mt": 1.6800,
    "total_accrued_liability_zar": 319.20
  }
}

Emission History

Retrieves complete transactional records ledger history rows lists. Free operation: does NOT bump or draw down your corporate request token usage allowance.

HTTP Headers
Key
Type
Description
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
limitInteger
False
Defines maximum data list density response bounds (default: 50, max: 100).
GET/api/v1/history
Request Payloads / Query Structure
Query Filter Syntax
GET /api/v1/history?limit=25
Response Envelope (200 OK Example)
{
  "success": true,
  "total_records": 1,
  "history": [
    {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "category_display": "VEHICLE",
      "distance_km": 310.2,
      "carbon_kg": 71.346
    }
  ]
}

Vehicle Roster

Fetches active tracking elements, model descriptors, and carbon multipliers associated with your profile. Free read query action.

HTTP Headers
Key
Type
Description
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
limitInteger
False
Maximum registered asset objects returned per view list query.
GET/api/v1/vehicles
Request Payloads / Query Structure
Roster Request Configuration
GET /api/v1/vehicles?limit=50
Response Envelope (200 OK Example)
{
  "success": true,
  "total_vehicles": 1,
  "vehicles": [
    {
      "id": "9cd3ed83-4d36-4fc8-857f-f19c0aaa2407",
      "make": "Aston Martin",
      "model": "DB12 V8",
      "carbon_multiplier": 0.230
    }
  ]
}

Airport Registry

Queries high-volume 50,000-row stationary airport hub directories safely avoiding performance lag. Free read query implementation.

HTTP Headers
Key
Type
Description
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
continentString
False
Filter by 2-character continent uppercase zone identifier string (e.g. 'AF').
iso_countryString
False
Filter by 2-character country uppercase identifier code (e.g. 'ZA').
pageInteger
False
The pagination tracking index cursor window (default: 1).
GET/api/v1/airports
Request Payloads / Query Structure
Paginated Airport Lookup Syntax
GET /api/v1/airports?continent=AF&iso_country=ZA&page=1&limit=2
Response Envelope (200 OK Example)
{
  "success": true,
  "pagination": { "total_records": 134, "current_page": 1, "per_page": 2 },
  "airports": [
    { "id": 31055, "name": "Cape Town International", "municipality": "Cape Town" }
  ]
}

Country Directory

Lists active stationary international boundary ISO codes matrix direct reference mappings records data cleanly without pagination. Free read operation.

HTTP Headers
Key
Type
Description
Authorization
String
Bearer token signature block
Parameters
Field
Required
Description
continentString
False
Filter response rows matrix by regional continent block designation.
GET/api/v1/countries
Request Payloads / Query Structure
Directory Filter Query
GET /api/v1/countries?continent=AF
Response Envelope (200 OK Example)
{
  "success": true,
  "total_countries": 54,
  "countries": [
    { "id": 182, "code": "ZA", "name": "South Africa", "continent": "AF" }
  ]
}