API Reference

Complete REST API documentation for the Flotac platform.

Base URL

https://chwjbbvcqsxxgaytqlix.supabase.co/functions/v1/api-gateway

Authentication

All endpoints require authentication via Bearer token:

Authorization: Bearer <your_token>

See the Authentication Guide for details on obtaining tokens.

Response Format

All responses follow this structure:

Success Response

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-10-14T12:00:00Z",
    "version": "v1",
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "totalPages": 10,
      "totalRecords": 250,
      "hasNextPage": true,
      "hasPreviousPage": false
    }
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "constraint": "email format"
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-10-14T12:00:00Z"
  }
}

Customers

List Customers

GET /api/v1/customers

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | page | number | Page number (default: 1) | | page_size | number | Results per page (default: 25, max: 100) | | status | string | Filter by status: active, inactive | | customer_type | string | Filter by type: individual, fleet, dealer | | search | string | Search by name, email, or phone | | sort_by | string | Sort field: name, created_at, email | | sort_order | string | Sort direction: asc, desc |

Example:

curl -X GET "https://chwjbbvcqsxxgaytqlix.supabase.co/functions/v1/api-gateway/api/v1/customers?status=active&page_size=50" \
  -H "Authorization: Bearer $FLOTAC_API_KEY"

Get Customer

GET /api/v1/customers/:id

Create Customer

POST /api/v1/customers

Request Body:

{
  "name": "Acme Trucking",
  "customer_type": "fleet",
  "email": "contact@acme.com",
  "phone": "+1-555-0100",
  "status": "active",
  "billing_address": {
    "street": "123 Main St",
    "city": "Springfield",
    "state": "IL",
    "zip": "62701"
  }
}

Update Customer

PUT /api/v1/customers/:id

Delete Customer

DELETE /api/v1/customers/:id

Performs a soft delete (sets deleted_at timestamp).

Vehicles

List Vehicles

GET /api/v1/vehicles

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | customer_id | uuid | Filter by customer | | status | string | Filter by status | | make | string | Filter by make | | model | string | Filter by model | | year | number | Filter by year | | search | string | Search by VIN, license plate, or name |

Get Vehicle

GET /api/v1/vehicles/:id

Create Vehicle

POST /api/v1/vehicles

Request Body:

{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "vin": "1HGCM82633A123456",
  "year": 2023,
  "make": "Freightliner",
  "model": "Cascadia",
  "license_plate": "TRK-1234",
  "status": "active",
  "mileage": 50000
}

Update Vehicle

PUT /api/v1/vehicles/:id

Delete Vehicle

DELETE /api/v1/vehicles/:id

Service Orders

List Service Orders

GET /api/v1/service-orders

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | customer_id | uuid | Filter by customer | | vehicle_id | uuid | Filter by vehicle | | status | string | Filter: pending, in_progress, completed, cancelled | | priority | string | Filter: low, normal, high, urgent | | scheduled_start_from | datetime | Filter by scheduled start date | | scheduled_start_to | datetime | Filter by scheduled end date |

Get Service Order

GET /api/v1/service-orders/:id

Create Service Order

POST /api/v1/service-orders

Request Body:

{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "vehicle_id": "987fcdeb-51a2-3e4d-b567-890123456789",
  "status": "pending",
  "priority": "normal",
  "description": "Annual maintenance and inspection",
  "scheduled_start": "2025-10-20T09:00:00Z",
  "estimated_hours": 3.5,
  "estimated_cost": 450.00
}

Update Service Order

PUT /api/v1/service-orders/:id

Delete Service Order

DELETE /api/v1/service-orders/:id

Invoices

List Invoices

GET /api/v1/invoices

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | customer_id | uuid | Filter by customer | | status | string | Filter: draft, sent, paid, overdue, cancelled | | payment_status | string | Filter: unpaid, partial, paid | | invoice_date_from | date | Filter by invoice date | | invoice_date_to | date | Filter by invoice date | | due_date_from | date | Filter by due date | | due_date_to | date | Filter by due date |

Get Invoice

GET /api/v1/invoices/:id

Create Invoice

POST /api/v1/invoices

Request Body:

{
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "service_order_id": "456fcdeb-78a9-0b1c-d234-567890abcdef",
  "status": "draft",
  "invoice_date": "2025-10-14",
  "due_date": "2025-11-14",
  "subtotal": 400.00,
  "tax_amount": 32.00,
  "total_amount": 432.00,
  "line_items": [
    {
      "description": "Labor - Annual Maintenance",
      "quantity": 3.5,
      "unit_price": 85.00,
      "amount": 297.50
    },
    {
      "description": "Oil Filter",
      "quantity": 2,
      "unit_price": 25.00,
      "amount": 50.00
    }
  ]
}

Update Invoice

PUT /api/v1/invoices/:id

Delete Invoice

DELETE /api/v1/invoices/:id

Parts

List Parts

GET /api/v1/parts

Query Parameters:

| Parameter | Type | Description | |-----------|------|-------------| | category | string | Filter by category | | manufacturer | string | Filter by manufacturer | | track_inventory | boolean | Filter parts with inventory tracking | | low_stock | boolean | Filter parts below reorder point | | search | string | Search by part number, name, or description |

Get Part

GET /api/v1/parts/:id

Create Part

POST /api/v1/parts

Request Body:

{
  "part_number": "OIL-FILTER-001",
  "name": "Premium Oil Filter",
  "description": "High-capacity oil filter for heavy-duty trucks",
  "category": "Filters",
  "manufacturer": "FleetPro",
  "price": 24.99,
  "cost": 12.50,
  "quantity_on_hand": 150,
  "reorder_point": 25,
  "track_inventory": true
}

Update Part

PUT /api/v1/parts/:id

Delete Part

DELETE /api/v1/parts/:id

Pagination

All list endpoints support pagination:

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | page | number | 1 | Current page number | | page_size | number | 25 | Results per page (max: 100) |

Example:

GET /api/v1/customers?page=2&page_size=50

Pagination Metadata:

{
  "meta": {
    "pagination": {
      "page": 2,
      "pageSize": 50,
      "totalPages": 10,
      "totalRecords": 500,
      "hasNextPage": true,
      "hasPreviousPage": true
    }
  }
}

Error Codes

| Code | HTTP Status | Description | |------|-------------|-------------| | UNAUTHORIZED | 401 | Missing or invalid authentication | | FORBIDDEN | 403 | Insufficient permissions | | RESOURCE_NOT_FOUND | 404 | Resource does not exist | | VALIDATION_ERROR | 422 | Invalid request data | | CONFLICT | 409 | Duplicate resource or constraint violation | | RATE_LIMIT_EXCEEDED | 429 | Too many requests | | INTERNAL_ERROR | 500 | Server error |

Rate Limits

  • Default: 100 requests per minute per company
  • Burst: Up to 200 requests allowed
  • Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Next Steps