Developer API Documentation

Getting Started

Welcome to the enterprise 3rd-Party Delivery REST API. External platforms, ERPs, POS systems, and eCommerce engines can trigger delivery dispatch, query active parcel categories, calculate fee estimates, track live couriers, and receive real-time status updates via webhooks.

Production & Sandbox Base URLs

Production: https://api.truthecosystem.com/api/v1/3rd-party
Sandbox:    https://sandbox.truthecosystem.com/api/v1/3rd-party

Authentication & Security

Authenticate all API requests by passing your API Key as a Bearer token in the Authorization HTTP header. Requests must also send Accept: application/json.

Required Request Headers

Authorization: Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4
Accept: application/json
Content-Type: application/json

Error Response (401 Unauthorized)

{
  "status": "error",
  "code": 401,
  "message": "Unauthenticated or invalid API key provided."
}

GET /3rd-party/deliveries/categories

List Active Parcel Categories

Returns active parcel categories with base rates and per-km pricing multipliers.

cURL Request

curl -X GET "https://api.truthecosystem.com/api/v1/3rd-party/deliveries/categories" \
  -H "Authorization: Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4" \
  -H "Accept: application/json"

Success Response (200 OK)

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Documents & Letters",
      "parcel_per_km_shipping_charge": 5.50,
      "parcel_minimum_shipping_charge": 50.00,
      "description": "Envelopes, papers, and small flat items"
    },
    {
      "id": 2,
      "name": "Electronics & Fragile",
      "parcel_per_km_shipping_charge": 10.00,
      "parcel_minimum_shipping_charge": 100.00,
      "description": "Phones, laptops, and sensitive cargo"
    }
  ]
}

POST /3rd-party/deliveries/estimate

Estimate Delivery Fee

Calculates exact delivery charge, distance, and zone multipliers prior to order placement.

Field	Type	Required	Description
pickup.latitude	float	Yes	Pickup GPS latitude coordinate
pickup.longitude	float	Yes	Pickup GPS longitude coordinate
dropoff.latitude	float	Yes	Dropoff GPS latitude coordinate
dropoff.longitude	float	Yes	Dropoff GPS longitude coordinate
parcel_category_id	integer	Yes	ID from /deliveries/categories

Request Payload (JSON)

{
  "pickup": { "latitude": 9.0305, "longitude": 38.7456 },
  "dropoff": { "latitude": 9.0112, "longitude": 38.7612 },
  "parcel_category_id": 1
}

Success Response (200 OK)

{
  "status": "success",
  "data": {
    "distance_km": 4.25,
    "estimated_duration_minutes": 15,
    "base_fee": 50.00,
    "distance_fee": 23.38,
    "total_fee": 73.38,
    "currency": "ETB"
  }
}

POST /3rd-party/deliveries

Create Delivery Request

Triggers courier assignment and registers delivery order inside the platform dispatch engine.

Field	Type	Required	Description
pickup.contact_person_name	string	Yes	Name of sender at pickup location
pickup.contact_person_number	string	Yes	Phone number of sender
pickup.address	string	Yes	Full pickup street address
dropoff.contact_person_name	string	Yes	Name of receiver at dropoff location
dropoff.contact_person_number	string	Yes	Phone number of receiver
dropoff.address	string	Yes	Full dropoff street address
parcel_category_id	integer	Yes	Category ID
charge_payer	string	Yes	"sender" or "receiver"

Request Payload (JSON)

{
  "pickup": {
    "contact_person_name": "John Doe",
    "contact_person_number": "+251911223344",
    "address": "Bole Atlas, Addis Ababa",
    "latitude": 9.0012,
    "longitude": 38.7845
  },
  "dropoff": {
    "contact_person_name": "Jane Smith",
    "contact_person_number": "+251922334455",
    "address": "Kazanchis, Addis Ababa",
    "latitude": 9.0150,
    "longitude": 38.7620
  },
  "parcel_category_id": 1,
  "charge_payer": "sender",
  "note": "Handle with care"
}

Success Response (201 Created)

{
  "status": "success",
  "message": "Delivery request created successfully.",
  "data": {
    "order_id": 100482,
    "tracking_code": "TRT-882910",
    "order_status": "pending",
    "order_amount": 73.38,
    "charge_payer": "sender",
    "created_at": "2026-07-26T21:15:00Z"
  }
}

GET /3rd-party/deliveries/{order_id}

Live Order Tracking

Fetches real-time courier position, ETA, and order status lifecycle.

cURL Request

curl -X GET "https://api.truthecosystem.com/api/v1/3rd-party/deliveries/100482" \
  -H "Authorization: Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4" \
  -H "Accept: application/json"

Success Response (200 OK)

{
  "status": "success",
  "order_id": 100482,
  "order_status": "picked_up",
  "estimated_time_minutes": 12,
  "deliveryman": {
    "id": 45,
    "name": "Abebe Bikila",
    "phone": "+251911998877",
    "current_latitude": 9.0210,
    "current_longitude": 38.7520,
    "vehicle_type": "Motorcycle",
    "rating": 4.9
  }
}

GET /driver/nearby-drivers

Nearby Driver Dispatch Query

Find active drivers within a radius for immediate order allocation.

cURL Request

curl -X GET "https://api.truthecosystem.com/api/v1/driver/nearby-drivers?latitude=9.0305&longitude=38.7456&radius_km=5" \
  -H "Authorization: Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4"

Success Response (200 OK)

{
  "status": "success",
  "available_drivers_count": 8,
  "closest_driver_distance_km": 0.8,
  "estimated_pickup_minutes": 4
}

GET /stores/items

Vendor Catalog & Items API

Query multi-vendor products, prices, stock levels, and store categories.

cURL Request

curl -X GET "https://api.truthecosystem.com/api/v1/stores/items?store_id=12&limit=10" \
  -H "Authorization: Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4"

Success Response (200 OK)

{
  "status": "success",
  "total_size": 25,
  "limit": 10,
  "offset": 1,
  "items": [
    {
      "id": 102,
      "name": "Fresh Roasted Coffee Beans 1kg",
      "price": 450.00,
      "image_full_url": "https://truthecosystem.com/storage/product/coffee.jpg",
      "store_id": 12,
      "store_name": "Abyssinia Coffee Roasters"
    }
  ]
}

GET /nearby-places

Nearby Places 3rd-Party API

Query verified nearby places, cafes, pharmacies, supermarkets, and service centers programmatically by GPS coordinates, distance radius, category, or minimum rating using Bearer API Key authentication.

Query Parameters

Parameter	Type	Status	Description
latitude	float	Optional	User/device GPS latitude coordinate (e.g. 9.0150)
longitude	float	Optional	User/device GPS longitude coordinate (e.g. 38.7620)
radius_km	float	Optional	Distance radius filter in kilometers (default: 10km, max: 500km)
category_id	integer	Optional	Category ID filter from /nearby-places/categories
search	string	Optional	Search keyword for place name, service detail, or address
min_rating	float	Optional	Minimum average rating threshold (e.g. 4.0)
limit	integer	Optional	Results per page (default: 25, max: 100)
offset	integer	Optional	Pagination offset index (default: 1)

cURL Request Example

curl -X GET "https://api.truthecosystem.com/api/v1/nearby-places?latitude=9.0150&longitude=38.7620&radius_km=5&min_rating=4.0" \
  -H "Authorization: Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4" \
  -H "Accept: application/json"

Success Response (200 OK)

{
  "status": "success",
  "total_size": 1,
  "limit": 25,
  "offset": 1,
  "places": [
    {
      "id": 2,
      "name": "Zewditu Pharmacy & Diagnostic Hub",
      "category": {
        "id": 2,
        "name": "Pharmacies & Medical"
      },
      "contact": "+251922334455",
      "image_full_url": "https://api.truthecosystem.com/storage/app/public/nearby/pharmacy.jpg",
      "rating": 4.8,
      "rating_count": 42,
      "service_detail": "24/7 prescription medicines, health diagnostics, and emergency delivery.",
      "license": "LIC-882109",
      "address": "Kazanchis Main Road, Addis Ababa",
      "latitude": 9.0150,
      "longitude": 38.7620,
      "distance_km": 0.0,
      "created_at": "2026-07-26T21:22:00.000000Z"
    }
  ]
}

Webhooks & Real-time Events

Subscribe your endpoint to receive HTTP POST webhooks on delivery state changes. Verify payloads using the signature header X-Truth-Signature.

Webhook Event Payload (order.delivered)

{
  "event": "order.delivered",
  "timestamp": 1722005400,
  "data": {
    "order_id": 100482,
    "delivered_at": "2026-07-26T18:30:00Z",
    "deliveryman_id": 45,
    "signature_proof_url": "https://truthecosystem.com/storage/proof/100482.jpg"
  }
}

SDK & Integration Code Snippets

Instant integration snippets for Node.js, cURL, PHP, and Dart / Flutter.

Node.js / JavaScript

const axios = require('axios');

async function getNearbyPlaces(lat, lng) {
  const response = await axios.get('https://api.truthecosystem.com/api/v1/3rd-party/nearby-places', {
    params: { latitude: lat, longitude: lng, radius_km: 5 },
    headers: { 
      'Authorization': 'Bearer tp_live_8f0a91e5c2b14d89a7f0c9d4',
      'Accept': 'application/json'
    }
  });
  return response.data;
}

REST API & SDK Documentation

Getting Started

Authentication & Security

List Active Parcel Categories

Estimate Delivery Fee

Create Delivery Request

Live Order Tracking

Nearby Driver Dispatch Query

Vendor Catalog & Items API

Nearby Places 3rd-Party API

Query Parameters

Webhooks & Real-time Events

SDK & Integration Code Snippets