# BScheduler Partner Integration Gateway

## Purpose of the Integration

This Partner Integration Gateway provides partner-facing API endpoints for scheduling operations in BScheduler. The gateway translates between partner-specific terminology and BScheduler internals, allowing partners such as Truckmore to interact with BScheduler using their own field names and conventions.

## Getting Started

### API Key Requirements

To use this integration, partners must obtain an API key from BlueTread. Each API key is:
- **Unique to the tenant/account** - Ensures secure, isolated access per tenant
- **Provided and managed by BlueTread** - Contact BlueTread to receive your API key
- **Required for all requests** - Must be included in the Authorization header

### Authentication

Include your API key in the Authorization header of every request:
```
Authorization: Bearer YOUR_API_KEY_HERE
```

---

## Partner Endpoints (Truckmore v2)

All Truckmore endpoints are under `/truckmore/api/v2`. Request and response schemas, examples and error bodies are in the [API Reference](/api). Errors are returned as `application/problem+json`.

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/truckmore/api/v2/requests` | Submit a booking request |
| GET | `/truckmore/api/v2/requests` | List booking requests |
| GET | `/truckmore/api/v2/requests/{requestId}` | Get a booking request |
| POST | `/truckmore/api/v2/requests/{requestId}/cancel` | Cancel a booking request that is still `Held` |
| GET | `/truckmore/api/v2/appointments` | List appointments |
| GET | `/truckmore/api/v2/appointments/{appointmentId}` | Get an appointment |
| GET | `/truckmore/api/v2/rooftops` | List rooftops |
| GET | `/truckmore/api/v2/timeslots` | List available timeslots |
| POST | `/truckmore/api/v2/fleets/search` | Search fleets |

The v1 endpoints (`/truckmore/api/v1/*`) have been removed and return `404 Not Found`.

---

## Error Responses

| Status Code | Description |
|-------------|-------------|
| 400 | Bad Request - Invalid input or missing required fields |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - Insufficient permissions |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Processing failed |
| 503 | Service Unavailable - Backend service temporarily unavailable |

---

## Support

For API key requests, technical support, or questions about the integration:
- **Email**: support@bluetread.com
- **Purpose**: API key provisioning and integration assistance
