AutoCom Docs

Reseller API Reference

Complete API documentation for all reseller platform endpoints.

Authentication

All endpoints require authentication via Bearer token:

Authorization: Bearer <your-api-token>

Headers

Required Headers

Header Description
Authorization Bearer token for authentication
X-Tenant Your tenant ID
Content-Type application/json for POST/PUT requests

Optional Headers

Header Description
X-Effective-Tenant Target tenant ID (super_admin context switching)

Base URLs

Production: https://api.autocom.example.com/api/v1
Development: http://localhost:8000/api/v1

ResellerCatalog API

Master Products

List Master Products

GET /reseller-catalog/master-products

Query Parameters:

Parameter Type Description
search string Search by name or SKU
status string Filter by status (active, inactive)
per_page integer Items per page (default: 20)
page integer Page number

Response:

{
  "products": [
    {
      "id": "uuid",
      "sku": "PROD-001",
      "name": "Product Name",
      "base_cost": 100.00,
      "minimum_margin_percent": 15,
      "recommended_retail_price": 180.00,
      "stock_quantity": 500,
      "status": "active",
      "resellers_count": 12,
      "images": ["url1", "url2"],
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 20,
    "total": 95
  }
}

Create Master Product

POST /reseller-catalog/master-products

Request Body:

{
  "sku": "PROD-001",
  "name": "Product Name",
  "description": "Product description",
  "base_cost": 100.00,
  "minimum_margin_percent": 15,
  "recommended_retail_price": 180.00,
  "stock_quantity": 500,
  "track_inventory": true,
  "images": ["url1", "url2"],
  "attributes": {
    "color": "blue",
    "size": "large"
  },
  "status": "active"
}

Response: 201 Created

{
  "message": "Product created successfully",
  "product": { ... }
}

Get Master Product

GET /reseller-catalog/master-products/{id}

Update Master Product

PUT /reseller-catalog/master-products/{id}

Delete Master Product

DELETE /reseller-catalog/master-products/{id}

My Catalog (Reseller)

List Available Products

GET /reseller-catalog/my-catalog

Response:

{
  "products": [
    {
      "id": "uuid",
      "sku": "PROD-001",
      "name": "Product Name",
      "your_cost": 120.00,
      "minimum_margin_percent": 12,
      "suggested_selling_price": 138.00,
      "available_stock": 500,
      "is_available": true,
      "images": ["url1"],
      "attributes": {}
    }
  ]
}

Pricing

List Pricing for Sub-Resellers

GET /reseller-catalog/pricing

Response:

{
  "pricing": [
    {
      "id": "pricing-uuid",
      "product": {
        "id": "prod-uuid",
        "name": "Product Name",
        "sku": "PROD-001"
      },
      "sub_reseller": {
        "id": "reseller-uuid",
        "name": "Reseller Name"
      },
      "cost_to_reseller": 138.00,
      "your_margin": 18.00,
      "margin_percent": 15,
      "is_available": true
    }
  ]
}

Set Pricing for Sub-Reseller

POST /reseller-catalog/pricing/set

Request Body:

{
  "product_id": "prod-uuid",
  "sub_reseller_id": "reseller-uuid",
  "margin_percent": 15,
  "is_available": true
}

Get Price Breakdown

GET /reseller-catalog/pricing/{productId}/breakdown

Response:

{
  "product": {
    "id": "prod-uuid",
    "name": "Product Name",
    "base_cost": 100.00
  },
  "your_cost": 138.00,
  "breakdown": [
    {
      "level": 0,
      "tenant_name": "Super Admin",
      "cost": 100.00,
      "margin_percent": 20,
      "margin_amount": 20.00,
      "selling_price": 120.00
    },
    {
      "level": 1,
      "tenant_name": "Distributor ABC",
      "cost": 120.00,
      "margin_percent": 15,
      "margin_amount": 18.00,
      "selling_price": 138.00
    }
  ]
}

ResellerOrders API

Chain Orders

List All Chain Orders

GET /chain-orders

Query Parameters:

Parameter Type Description
status string Filter by status
from_date date Filter by date range start
to_date date Filter by date range end
search string Search by order number, customer
per_page integer Items per page

List Incoming Orders

GET /chain-orders/incoming

Returns orders from your sub-resellers awaiting action.

List Forwarded Orders

GET /chain-orders/forwarded

Returns orders you've forwarded up the chain.

List Fulfillment Queue

GET /chain-orders/fulfillment

Returns orders you need to fulfill.

Get Order Statistics

GET /chain-orders/stats

Response:

{
  "stats": {
    "pending_forward": 5,
    "forwarded": 3,
    "accepted": 12,
    "processing": 8,
    "shipped": 45,
    "delivered": 234,
    "total_value": 125000.00
  }
}

Single Order

Get Order Details

GET /chain-orders/{id}

Response:

{
  "order": {
    "id": "uuid",
    "origin_order_number": "ORD-2024-001",
    "chain_status": "shipped",
    "chain_path": [...],
    "customer": {...},
    "shipping_address": {...},
    "items": [...],
    "pricing": {
      "origin_total": 155.00,
      "your_cost": 120.00,
      "your_margin": 18.00,
      "cod_amount": 155.00
    },
    "shipping": {
      "carrier": "delhivery",
      "tracking_number": "DEL123456",
      "shipped_at": "2024-01-15T10:30:00Z"
    },
    "payment": {
      "method": "cod",
      "status": "pending"
    }
  }
}

Get Order Timeline

GET /chain-orders/{id}/timeline

Order Actions

Forward Order

POST /chain-orders/{id}/forward

Forwards the order to your parent tenant.

Accept Order

POST /chain-orders/{id}/accept

Accepts an incoming order from a sub-reseller.

Ship Order

POST /chain-orders/{id}/ship

Request Body:

{
  "tracking_number": "DEL123456789",
  "carrier": "delhivery"
}

Mark as Delivered

POST /chain-orders/{id}/deliver

Note: This triggers the COD settlement process.

Cancel Order

POST /chain-orders/{id}/cancel

Request Body:

{
  "reason": "Customer requested cancellation"
}

ResellerFinance API

Wallet

Get Wallet Balance

GET /finance/wallet

Response:

{
  "wallet": {
    "id": "uuid",
    "balance": 25000.00,
    "available_balance": 22000.00,
    "effective_balance": 35000.00,
    "pending_credits": 5000.00,
    "pending_debits": 3000.00,
    "total_earned": 150000.00,
    "total_paid_out": 125000.00,
    "credit_limit": 10000.00,
    "currency": "INR",
    "last_settlement_at": "2024-01-15T00:00:00Z"
  }
}

Get Wallet Summary

GET /finance/wallet/summary

Query Parameters:

Parameter Type Description
period string week, month, quarter, year

List Transactions

GET /finance/wallet/transactions

Query Parameters:

Parameter Type Description
type string credit, debit, hold, release
reference_type string chain_order, remittance, etc.
from_date date Start date
to_date date End date
per_page integer Items per page

Export Transactions

GET /finance/wallet/transactions/export

Returns CSV file download.

Get Single Transaction

GET /finance/wallet/transactions/{id}

Settlements

Get Settlement Summary

GET /finance/settlements/summary

Query Parameters:

Parameter Type Description
period string week, month, quarter, year

Response:

{
  "summary": {
    "period": "month",
    "wallet_balance": 25000.00,
    "pending_credits": 5000.00,
    "pending_debits": 3000.00,
    "collections_count": 45,
    "collections_total": 125000.00,
    "remittances_paid": 85000.00,
    "remittances_received": 92000.00,
    "net_earnings": 7000.00
  }
}

Get Pending Remittances

GET /finance/settlements/pending

Response:

{
  "to_pay": [...],
  "to_receive": [...],
  "totals": {
    "owed": 8500.00,
    "receivable": 12000.00,
    "net_position": 3500.00
  }
}

List COD Collections

GET /finance/settlements/collections

Query Parameters:

Parameter Type Description
status string pending, settled
flow_type string upstream, downstream
from_date date Start date
to_date date End date

List Remittance History

GET /finance/settlements/remittances

Query Parameters:

Parameter Type Description
status string pending, completed
direction string incoming, outgoing
from_date date Start date
to_date date End date

Process Remittance

POST /finance/settlements/remittances/{id}/process

Processes a pending remittance (debits your wallet, credits recipient).

Response:

{
  "message": "Remittance processed successfully",
  "remittance": {
    "id": "uuid",
    "status": "completed",
    "completed_at": "2024-01-17T14:30:00Z"
  },
  "wallet": {
    "new_balance": 17500.00,
    "deducted": 4500.00
  }
}

Bulk Process Remittances

POST /finance/settlements/remittances/bulk-process

Request Body:

{
  "remittance_ids": ["uuid-1", "uuid-2", "uuid-3"]
}

Response:

{
  "processed": ["uuid-1", "uuid-2"],
  "errors": {
    "uuid-3": "Insufficient balance"
  },
  "message": "Processed 2 remittances, 1 failed"
}

Admin Endpoints (Super Admin Only)

Get Global Statistics

GET /finance/admin/stats

Query Parameters:

Parameter Type Description
period string week, month, quarter, year

Response:

{
  "period": "month",
  "start_date": "2024-01-01T00:00:00Z",
  "totals": {
    "collections": 1250000.00,
    "pending_remittances": 85000.00,
    "completed_remittances": 420000.00
  },
  "overdue": {
    "count": 12,
    "total_amount": 45000.00,
    "items": [...]
  },
  "top_debtors": [
    {
      "tenant_id": "uuid",
      "tenant_name": "Reseller XYZ",
      "total_owed": 15000.00
    }
  ]
}

Error Responses

Standard Error Format

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {}
}

HTTP Status Codes

Code Description
200 Success
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
422 Validation Error
500 Server Error

Common Errors

// Insufficient Balance
{
  "error": "Insufficient balance",
  "code": "INSUFFICIENT_BALANCE",
  "details": {
    "required": 4500.00,
    "available": 2000.00
  }
}

// Remittance Not Pending
{
  "error": "Remittance is not pending",
  "code": "INVALID_STATUS",
  "details": {
    "current_status": "completed"
  }
}

// Unauthorized Context Switch
{
  "error": "Cannot access this tenant",
  "code": "UNAUTHORIZED_CONTEXT",
  "details": {
    "target_tenant": "uuid"
  }
}

Rate Limits

Endpoint Category Limit
Read endpoints 100 requests/minute
Write endpoints 30 requests/minute
Export endpoints 5 requests/minute

Webhooks

Available Events

Event Description
chain_order.created New chain order created
chain_order.status_changed Order status changed
chain_order.delivered Order delivered
remittance.created New remittance created
remittance.due Remittance approaching due date
remittance.overdue Remittance past due date
wallet.low_balance Wallet below threshold

Webhook Payload

{
  "event": "chain_order.delivered",
  "timestamp": "2024-01-17T14:30:00Z",
  "tenant_id": "uuid",
  "data": {
    "chain_order_id": "uuid",
    "origin_order_number": "ORD-2024-001"
  }
}