API Documentation

Integrate ecotrovy delivery into your platform. Create parcels, track deliveries, and manage payments with our RESTful Business API.

Base URL: https://api.ecotrovy/v1Auth: X-API-Key

Quick Start

1. Register a business account

Create your business account via the API or at https://ecotrovy.com/. Your API key is returned on successful registration.

cURL

curl -X POST https://api.ecotrovy/v1/business/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "FastDeliver Ltd",
    "website": "https://fastdeliver.com",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@fastdeliver.com",
    "phone": "+447012345678",
    "password": "SecurePass123",
    "api_key_name": "Production Key"
  }'

2. Save your API key

The response contains your api_key (prefixed flx_live_). Save it securely — it is only shown once.

3. Make your first request

Pass the key in the X-API-Key header for all subsequent API calls.

cURL

curl -X GET https://api.ecotrovy/v1/business/account \
  -H "X-API-Key: flx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Authentication

ecotrovy uses API key authentication via the X-API-Key header. Keys are prefixed with flx_live_ for production and flx_test_ for sandbox.

Header:X-API-Key: flx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Key Prefix:flx_live_ (production) / flx_test_ (sandbox)

Code Examples

JavaScript

const response = await fetch('https://api.ecotrovy/v1/business/parcels', {
  headers: {
    'X-API-Key': 'flx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6',
    'Content-Type': 'application/json',
  },
});
const { data } = await response.json();

Python

import requests

response = requests.get(
    'https://api.ecotrovy/v1/business/parcels',
    headers={'X-API-Key': 'flx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6'}
)
data = response.json()['data']

req, _ := http.NewRequest("GET", "https://api.ecotrovy/v1/business/parcels", nil)
req.Header.Set("X-API-Key", "flx_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6")

resp, err := http.DefaultClient.Do(req)

Key Management

You can create, rotate, and revoke API keys via the endpoints. Rotating a key immediately invalidates the old one.

Response Format

All responses follow a consistent envelope structure:

Success

JSON

{
  "status": 200,
  "data": { ... },
  "code": "SUC0001",
  "detail": "Success"
}

Error

JSON

{
  "status": 400,
  "code": "ERR0001",
  "detail": "Bad Request - Invalid JSON or malformed request"
}

API Endpoints

Base URL: https://api.ecotrovy/v1

Endpoints marked with a lock require the X-API-Key header.

Parcel State Machine

Parcels progress through the following states. Invalid transitions return ERR0017.

incompleteParcel created, awaiting payment/completion

availableParcel available for drivers to accept

pick_up_acceptedDriver has accepted the pickup

pick_up_confirmedSender confirmed driver's pickup

going_for_pick_upDriver en route to pickup location

picked_upDriver has collected the parcel

going_for_deliveryDriver en route to destination

deliveredParcel successfully delivered

State	Description
`incomplete`	Parcel created, awaiting payment/completion
`available`	Parcel available for drivers to accept
`pick_up_accepted`	Driver has accepted the pickup
`pick_up_confirmed`	Sender confirmed driver's pickup
`going_for_pick_up`	Driver en route to pickup location
`picked_up`	Driver has collected the parcel
`going_for_delivery`	Driver en route to destination
`delivered`	Parcel successfully delivered

Rate Limiting

Tier	Limit	Scope	Endpoints
Strict	10 req/min	Per IP	`POST /v1/business/accounts`
Payment	15 req/min	Per user	`POST /v1/business/payment/intent`
Standard	500 req/min	Per user	`All other business endpoints`

Note: Exceeding rate limits returns 429 Too Many Requests (ERR0019). Use the Retry-After header to determine when to retry.

Webhooks

Register webhook URLs to receive real-time delivery and payment updates. Webhooks are sent as POST requests with a JSON body, signed with your webhook secret (whsec_) via HMAC-SHA256.

Available Events

parcel.created— Parcel was created

parcel.status_changed— Parcel state changed

pickup.accepted— Driver accepted pickup

pickup.rejected— Driver rejected pickup

pickup.collected— Parcel collected by driver

parcel.delivered— Parcel delivered to recipient

payment.completed— Payment succeeded

payment.failed— Payment failed

payment.refunded— Payment refunded

Webhook Payload Example

{
  "event": "parcel.status_changed",
  "timestamp": "2025-03-10T11:00:00Z",
  "data": {
    "parcel_id": "parcel-9f8e7d6c-5b4a-3210-fedc-ba9876543210",
    "ref": "PSL-20250310-A1B2C3D4",
    "old_state": "going_for_pick_up",
    "new_state": "picked_up",
    "updated_at": "2025-03-10T11:00:00Z"
  }
}

Signature Verification (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Error Codes

Code	HTTP	Description
`ERR0001`	400	Bad Request - Invalid JSON or malformed request
`ERR0002`	400	Validation error - Please check your input
`ERR0003`	401	Unauthorized - No API key provided
`ERR0004`	401	Invalid or malformed API key
`ERR0005`	401	Token/key has expired
`ERR0010`	404	Parcel not found
`ERR0011`	404	Payment not found
`ERR0016`	409	Duplicate entry - Resource already exists
`ERR0017`	400	Invalid status transition
`ERR0019`	429	Too many requests
`ERR1002`	500	Internal server error
`ERR1008`	400	Invalid JSON body

SDKs & Libraries

JavaScript / TypeScript

Coming Soon

npm install @eco-trovy/sdk

Python

Coming Soon

pip install eco_trovy

Go

Coming Soon

go get github.com/eco-trovy/go-sdk

Dart / Flutter

Coming Soon

dart pub add eco_trovy_sdk

Sandbox / Testing

Use our sandbox environment to test your integration without affecting production data or triggering real deliveries.

Sandbox Base URL:https://sandbox.api.ecotrovy/v1

Test API Key Prefix:flx_test_

Tip: Sandbox keys start with flx_test_ while production keys start with flx_live_. Sandbox data is reset weekly.